> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building a custom ACP agent

> Build a custom agent that runs inside Devin Desktop via the Agent Client Protocol.

This page covers what you need to implement to build a custom [ACP](/desktop/acp) agent that works with Devin Desktop.

For the full protocol specification, see [agentclientprotocol.com](https://agentclientprotocol.com/). Official client libraries are available in [Rust](https://agentclientprotocol.com/libraries/rust), [TypeScript](https://agentclientprotocol.com/libraries/typescript), [Python](https://agentclientprotocol.com/libraries/python), [Kotlin](https://agentclientprotocol.com/libraries/kotlin), and [Java](https://agentclientprotocol.com/libraries/java).

## Basics

ACP agents run as local sub-processes that Devin Desktop launches on demand. All communication happens over JSON-RPC on stdio.

### Methods you must implement

At minimum, your agent needs to handle these methods from Devin Desktop:

* [`initialize`](https://agentclientprotocol.com/protocol/initialization) — Negotiate the protocol version, advertise your agent's capabilities, and return agent info (name, version).
* [`session/new`](https://agentclientprotocol.com/protocol/session-setup) — Create a new session for a working directory and return a session ID. Devin Desktop passes the cwd and any configured MCP servers.
* [`session/prompt`](https://agentclientprotocol.com/protocol/prompt-turn) — Receive a user message, drive the prompt turn, and return a `stopReason` when finished.
* [`session/cancel`](https://agentclientprotocol.com/protocol/prompt-turn) — Abort any in-flight work for a session when the user cancels.

### Prompt turn lifecycle

During a `session/prompt` turn, your agent streams updates back to Devin Desktop as JSON-RPC notifications:

* `session/update` with `agent_message_chunk` for streaming assistant text.
* `session/update` with `tool_call` and `tool_call_update` to show tool calls and their status in the Devin Desktop UI.
* `session/request_permission` to ask the user before running a sensitive tool call.
* `session/update` with `plan` if your agent maintains an [agent plan](https://agentclientprotocol.com/protocol/agent-plan).

The turn ends when your agent returns a `session/prompt` response with a `stopReason` (e.g. `end_turn`, `cancelled`, `max_tokens`).

## Testing

To test your agent against Devin Desktop:

1. Add an entry for your agent in your [local registry config](/desktop/acp#local-registry-config), pointing `cmd` at the path of your local agent binary (or a wrapper script).
2. Make changes to your agent and rebuild as needed.
3. Run `Reload ACP Connections` from the Command Palette to pick up the latest version — no need to restart Devin Desktop between iterations.

## Limitations

Devin Desktop does not currently support every part of the ACP spec. The following are the main differences to be aware of when building an agent targeting Devin Desktop:

* **Session modes are not supported.** [Session modes](https://agentclientprotocol.com/protocol/session-modes) are not exposed in the Devin Desktop UI. If your agent needs to let users pick between modes (e.g. plan / build / review), expose them as a [session config option](https://agentclientprotocol.com/protocol/session-config-options) with the `"mode"` category instead.
* **Terminal capabilities are not exposed.** Devin Desktop does not advertise [terminal capabilities](https://agentclientprotocol.com/protocol/terminals), so agents cannot create terminals in the Devin Desktop UI. Agents should run commands in their own subprocess and stream output back via `tool_call` updates.