Skip to main content

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.

This page covers what you need to implement to build a custom ACP agent that works with Devin Desktop. For the full protocol specification, see agentclientprotocol.com. Official client libraries are available in Rust, TypeScript, Python, Kotlin, and 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 — Negotiate the protocol version, advertise your agent’s capabilities, and return agent info (name, version).
  • session/new — 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 — Receive a user message, drive the prompt turn, and return a stopReason when finished.
  • session/cancel — 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.
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, 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 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 with the "mode" category instead.
  • Terminal capabilities are not exposed. Devin Desktop does not advertise terminal capabilities, 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.