docs/src/oss/deepagents/acp.mdx at 979d68c2e01f55e1dc2744b7f660ddc87b466db6 · langchain-ai/docs

title	Agent Client Protocol (ACP)
description	Expose Deep Agents over the Agent Client Protocol (ACP) to integrate with code editors and IDEs.

Agent Client Protocol (ACP) standardizes communication between coding agents and code editors or IDEs. With the ACP protocol, you can make use of your custom deep agents with any ACP-compatible client, allowing your code editor to provide project context and receive rich updates.

ACP is designed for agent-editor integrations. If you want your agent to call tools hosted by external servers, see [Model Context Protocol (MCP)](/oss/langchain/mcp/).

Quickstart

Install the ACP integration package:

:::python

pip install deepagents-acp

uv add deepagents-acp

:::

:::js

npm install deepagents-acp

yarn add deepagents-acp

pnpm add deepagents-acp

:::

Then expose a deep agent over ACP.

This starts an ACP server in stdio mode (it reads requests from stdin and writes responses to stdout). In practice, you usually run this as a command launched by an ACP client (for example, your editor), which then communicates with the server over stdio.

:::python

import asyncio

from acp import run_agent
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

from deepagents_acp.server import AgentServerACP


async def main() -> None:
    agent = create_deep_agent(
        model="google_genai:gemini-3.1-pro-preview",
        # You can customize your deep agent here: set a custom prompt,
        # add your own tools, attach middleware, or compose subagents.
        system_prompt="You are a helpful coding assistant",
        checkpointer=MemorySaver(),
    )

    server = AgentServerACP(agent)
    await run_agent(server)


if __name__ == "__main__":
    asyncio.run(main())

:::

:::js

import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "coding-assistant",
    description: "AI coding assistant with filesystem access",
  },
  workspaceRoot: process.cwd(),
});

You can also use the CLI without writing any code:

npx deepagents-acp

:::

:::python The deepagents-acp package includes an example coding agent with filesystem and shell that you can run out of the box. :::

:::js The deepagents-acp package provides both a CLI and a programmatic API for exposing deep agents over ACP. :::

Clients

Deep agents work anywhere you can run an ACP agent server. Some notable ACP clients include:

Zed
JetBrains IDEs
Visual Studio Code (via vscode-acp)
Neovim (via ACP-compatible plugins)

Zed

:::python

The deepagents repo includes a demo ACP entrypoint you can register with Zed:

Clone the deepagents repo and install dependencies:

git clone https://github.com/langchain-ai/deepagents.git
cd deepagents/libs/acp
uv sync --all-groups
chmod +x run_demo_agent.sh

Configure credentials for the demo agent:

cp .env.example .env

Then set ANTHROPIC_API_KEY in .env.

Configure your ACP agent server command in Zed's settings.json:

{
  "agent_servers": {
    "DeepAgents": {
      "type": "custom",
      "command": "/your/absolute/path/to/deepagents/libs/acp/run_demo_agent.sh"
    }
  }
}

Open Zed's Agents panel and start a DeepAgents thread.

:::

:::js

Register your deep agent with Zed by adding it to your Zed settings (~/.config/zed/settings.json on Linux, ~/Library/Application Support/Zed/settings.json on macOS):

Simple setup (no code required):

{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",
        "command": "npx",
        "args": ["deepagents-acp"],
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-..."
        }
      }
    }
  }
}

With CLI options:

{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",
        "command": "npx",
        "args": [
          "deepagents-acp",
          "--name", "my-assistant",
          "--skills", "./skills",
          "--debug"
        ],
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-..."
        }
      }
    }
  }
}

Custom server script:

For more control, create a TypeScript server script:

// server.ts
import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "my-agent",
    description: "My custom coding agent",
    skills: ["./skills/"],
  },
});

Then point Zed at it:

{
  "agent": {
    "profiles": {
      "my-agent": {
        "name": "My Agent",
        "command": "npx",
        "args": ["tsx", "./server.ts"]
      }
    }
  }
}

Open Zed's Agents panel and start a DeepAgents thread.

:::

:::python

Toad

If you want to run an ACP agent server as a local dev tool, you can use Toad to manage the process.

uv tool install -U batrachian-toad

toad acp "python path/to/your_server.py" .
# or
toad acp "uv run python path/to/your_server.py" .

:::

:::js

ACP Registry

DeepAgents is available in the ACP Agent Registry for one-click installation in Zed and JetBrains IDEs. When an ACP client supports the registry, users can discover and install Deep Agents without any manual configuration.

:::

:::js

CLI reference

The CLI is the fastest way to start an ACP server. It requires no code — just run npx deepagents-acp and connect your editor.

npx deepagents-acp [options]

Option	Short	Description
`--name <name>`	`-n`	Agent name (default: `"deepagents"`)
`--description <desc>`	`-d`	Agent description
`--model <model>`	`-m`	LLM model (default: `"claude-sonnet-4-5-20250929"`)
`--workspace <path>`	`-w`	Workspace root directory (default: cwd)
`--skills <paths>`	`-s`	Comma-separated skill paths
`--memory <paths>`		Comma-separated AGENTS.md paths
`--debug`		Enable debug logging to stderr
`--help`	`-h`	Show help message
`--version`	`-v`	Show version

Environment variables

Variable	Description
`ANTHROPIC_API_KEY`	API key for Anthropic/Claude models (required)
`OPENAI_API_KEY`	API key for OpenAI models
`DEBUG`	Set to `"true"` to enable debug logging
`WORKSPACE_ROOT`	Alternative to `--workspace` flag

:::

:::js

Programmatic API

`startServer`

Convenience function to create and start a server in one call:

import { startServer } from "deepagents-acp";

const server = await startServer({
  agents: {
    name: "coding-assistant",
    description: "AI coding assistant with filesystem access",
  },
  workspaceRoot: process.cwd(),
});

`DeepAgentsServer`

For full control, use the DeepAgentsServer class directly:

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "claude-sonnet-4-5-20250929",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

Server options

Option	Type	Default	Description
`agents`	`DeepAgentConfig \| DeepAgentConfig[]`	required	Agent configuration(s)
`serverName`	`string`	`"deepagents-acp"`	Server name for ACP
`serverVersion`	`string`	`"0.0.1"`	Server version
`workspaceRoot`	`string`	`process.cwd()`	Workspace root directory
`debug`	`boolean`	`false`	Enable debug logging

Agent configuration

Option	Type	Description
`name`	`string`	Unique agent name (required)
`description`	`string`	Agent description
`model`	`string`	LLM model (default: `"claude-sonnet-4-5-20250929"`)
`tools`	`StructuredTool[]`	Custom LangChain tools
`systemPrompt`	`string`	Custom system prompt
`middleware`	`AgentMiddleware[]`	Custom middleware
`backend`	`AnyBackendProtocol`	Filesystem backend
`skills`	`string[]`	Skill source paths
`memory`	`string[]`	Memory source paths (AGENTS.md)
`interruptOn`	`Record<string, boolean \| InterruptOnConfig>`	Tools requiring user approval (HITL)
`commands`	`Array<{ name, description, input? }>`	Custom slash commands

:::

:::js

Customization

Multiple agents

You can expose multiple agents from a single server. The ACP client selects which agent to use when creating a session:

const server = new DeepAgentsServer({
  agents: [
    { name: "code-agent", description: "General coding" },
    { name: "reviewer", description: "Code reviews" },
  ],
});

Some ACP clients (like Zed) don't currently expose a UI for selecting between agents. In that case, consider running separate server instances with a single agent each.

Slash commands

The server registers built-in slash commands with the IDE: /plan, /agent, /ask, /clear, and /status. You can also define custom commands per agent:

const server = new DeepAgentsServer({
  agents: {
    name: "my-agent",
    commands: [
      { name: "test", description: "Run the project's test suite" },
      { name: "lint", description: "Run linter and fix issues" },
      {
        name: "deploy",
        description: "Deploy to staging",
        input: { hint: "environment (staging or production)" },
      },
    ],
  },
});

Human-in-the-loop

Use interruptOn to require user approval in the IDE before the agent runs sensitive tools:

const server = new DeepAgentsServer({
  agents: {
    name: "careful-agent",
    interruptOn: {
      execute: { allowedDecisions: ["approve", "edit", "reject"] },
      write_file: true,
    },
  },
});

When the agent calls a protected tool, the IDE prompts the user to allow or reject the operation, with options to remember the decision for the session.

Custom tools

import { DeepAgentsServer } from "deepagents-acp";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const searchTool = tool(
  async ({ query }) => {
    return `Results for: ${query}`;
  },
  {
    name: "search",
    description: "Search the codebase",
    schema: z.object({ query: z.string() }),
  },
);

const server = new DeepAgentsServer({
  agents: {
    name: "search-agent",
    tools: [searchTool],
  },
});

await server.start();

Custom backend

import { DeepAgentsServer } from "deepagents-acp";
import { CompositeBackend, FilesystemBackend, StateBackend } from "deepagents";

const server = new DeepAgentsServer({
  agents: {
    name: "custom-agent",
    backend: new CompositeBackend({
      routes: [
        {
          prefix: "/workspace",
          backend: new FilesystemBackend({ rootDir: "./workspace" }),
        },
        { prefix: "/", backend: new StateBackend() },
      ],
    }),
  },
});

await server.start();

Skills and memory

import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "project-agent",
    description: "Agent with project-specific knowledge",
    skills: ["./skills/", "~/.deepagents/skills/"],
    memory: ["./.deepagents/AGENTS.md"],
  },
  workspaceRoot: process.cwd(),
});

:::

See the upstream ACP docs for protocol details and editor support: - Introduction: https://agentclientprotocol.com/get-started/introduction - Clients/editors: https://agentclientprotocol.com/get-started/clients

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quickstart

Clients

Zed

Toad

ACP Registry

CLI reference

Environment variables

Programmatic API

`startServer`

`DeepAgentsServer`

Server options

Agent configuration

Customization

Multiple agents

Slash commands

Human-in-the-loop

Custom tools

Custom backend

Skills and memory

FilesExpand file tree

acp.mdx

Latest commit

History

acp.mdx

File metadata and controls

Quickstart

Clients

Zed

Toad

ACP Registry

CLI reference

Environment variables

Programmatic API

startServer

DeepAgentsServer

Server options

Agent configuration

Customization

Multiple agents

Slash commands

Human-in-the-loop

Custom tools

Custom backend

Skills and memory

`startServer`

`DeepAgentsServer`