Agent Client Protocol (ACP) | LangChain 中文文档

Agent Client Protocol (ACP) 标准化了编码智能体与代码编辑器或 IDE 之间的通信。借助 ACP 协议，你可以在任何兼容 ACP 的客户端中使用你的自定义深度智能体，让你的代码编辑器提供项目上下文并接收丰富的更新。

INFO

ACP 专为智能体与编辑器的集成而设计。如果你希望智能体调用由外部服务器托管的工具，请参阅 Model Context Protocol (MCP)。

快速开始

安装 ACP 集成包：

bash

pip install deepagents-acp

bash

uv add deepagents-acp

bash

npm install deepagents-acp

bash

yarn add deepagents-acp

bash

pnpm add deepagents-acp

然后通过 ACP 暴露一个深度智能体。

这将以 stdio 模式启动一个 ACP 服务器（它从 stdin 读取请求并将响应写入 stdout）。在实践中，你通常将其作为由 ACP 客户端（例如你的编辑器）启动的命令来运行，然后该客户端通过 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.6-flash",
        # 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())

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="openai:gpt-5.5",
        # 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())

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="anthropic:claude-sonnet-4-6",
        # 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())

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="openrouter:z-ai/glm-5.2",
        # 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())

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="fireworks:accounts/fireworks/models/glm-5p2",
        # 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())

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="baseten:zai-org/GLM-5.2",
        # 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())

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="ollama:north-mini-code-1.0",
        # 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())

import { startServer } from "deepagents-acp";

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

你也可以在不编写任何代码的情况下使用 CLI：

bash

npx deepagents-acp

示例编码智能体 — deepagents-acp 包包含一个带有文件系统和 shell 的示例编码智能体，你可以开箱即用地运行它。
npm 上的 Deep Agents ACP — deepagents-acp 包同时提供 CLI 和编程式 API，用于通过 ACP 暴露深度智能体。

客户端

在任何可以运行 ACP 智能体服务器的地方，深度智能体都可以工作。一些值得注意的 ACP 客户端包括：

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

Zed

deepagents 仓库包含一个你可以注册到 Zed 的演示 ACP 入口点：

克隆 deepagents 仓库并安装依赖：

bash

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

为演示智能体配置凭据：

bash

cp .env.example .env

然后在 .env 中设置 ANTHROPIC_API_KEY。

在 Zed 的 settings.json 中配置你的 ACP 智能体服务器命令：

json

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

打开 Zed 的 Agents 面板并启动一个 Deep Agents 会话。

通过将你的深度智能体添加到 Zed 设置中来将其注册到 Zed（在 Linux 上是 ~/.config/zed/settings.json，在 macOS 上是 ~/Library/Application Support/Zed/settings.json）：

简单设置（无需代码）：

json

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

带 CLI 选项：

json

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

自定义服务器脚本：

为了获得更多控制，请创建一个 TypeScript 服务器脚本：

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

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

然后让 Zed 指向它：

json

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

打开 Zed 的 Agents 面板并启动一个 Deep Agents 会话。

Toad

如果你希望将 ACP 智能体服务器作为本地开发工具运行，可以使用 Toad 来管理该进程。

bash

uv tool install -U batrachian-toad

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

ACP Registry

Deep Agents 已上架 ACP Agent Registry，可在 Zed 和 JetBrains IDE 中一键安装。当 ACP 客户端支持该注册表时，用户无需任何手动配置即可发现并安装 Deep Agents。

CLI 参考

CLI 是启动 ACP 服务器最快的方式。它不需要代码——只需运行 npx deepagents-acp 并连接你的编辑器。

bash

npx deepagents-acp [options]

选项	简写	描述
`--name <name>`	`-n`	智能体名称（默认值：`"deepagents"`）
`--description <desc>`	`-d`	智能体描述
`--model <model>`	`-m`	LLM 模型（默认值：`"claude-sonnet-4-5-20250929"`）
`--workspace <path>`	`-w`	工作区根目录（默认值：cwd）
`--skills <paths>`	`-s`	逗号分隔的技能路径
`--memory <paths>`		逗号分隔的 AGENTS.md 路径
`--debug`		向 stderr 启用调试日志记录
`--help`	`-h`	显示帮助信息
`--version`	`-v`	显示版本

环境变量

变量	描述
`ANTHROPIC_API_KEY`	Anthropic/Claude 模型的 API 密钥（必需）
`OPENAI_API_KEY`	OpenAI 模型的 API 密钥
`DEBUG`	设置为 `"true"` 以启用调试日志记录
`WORKSPACE_ROOT`	`--workspace` 标志的替代方案

编程式 API

`startServer`

在一个调用中创建并启动服务器的便捷函数：

import { startServer } from "deepagents-acp";

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

`DeepAgentsServer`

为了获得完全的控制，请直接使用 DeepAgentsServer 类：

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "google-genai:gemini-3.6-flash",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "openai:gpt-5.5",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "anthropic:claude-sonnet-4-6",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "openrouter:openrouter:z-ai/glm-5.2",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "fireworks:accounts/fireworks/models/glm-5p2",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "baseten:zai-org/GLM-5.2",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "ollama:north-mini-code-1.0",
      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();

服务器选项

选项	类型	默认值	描述
`agents`	`DeepAgentConfig \| DeepAgentConfig[]`	必需	智能体配置
`serverName`	`string`	`"deepagents-acp"`	用于 ACP 的服务器名称
`serverVersion`	`string`	`"0.0.1"`	服务器版本
`workspaceRoot`	`string`	`process.cwd()`	工作区根目录
`debug`	`boolean`	`false`	启用调试日志记录

智能体配置

选项	类型	描述
`name`	`string`	唯一智能体名称（必需）
`description`	`string`	智能体描述
`model`	`string`	LLM 模型（默认值：`"claude-sonnet-4-5-20250929"`）
`tools`	`StructuredTool[]`	自定义 LangChain 工具
`systemPrompt`	`string`	自定义系统提示词
`middleware`	`AgentMiddleware[]`	追加到默认栈的自定义中间件
`backend`	`AnyBackendProtocol`	文件系统后端
`skills`	`string[]`	技能源路径
`memory`	`string[]`	记忆源路径（AGENTS.md）
`interruptOn`	`Record<string, boolean \| InterruptOnConfig>`	需要用户批准的工具（人在回路 / HITL）
`commands`	`Array<{ name, description, input? }>`	自定义斜杠命令

自定义

多个智能体

你可以从单个服务器暴露多个智能体。ACP 客户端在创建会话时选择要使用的智能体：

import { DeepAgentsServer } from "deepagents-acp";

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

INFO

一些 ACP 客户端（如 Zed）目前不提供用于在智能体之间进行选择的界面（UI）。在这种情况下，可以考虑运行单独的服务器实例，每个实例只包含一个智能体。

斜杠命令

服务器向 IDE 注册内置斜杠命令：/plan、/agent、/ask、/clear 和 /status。你还可以为每个智能体定义自定义命令：

import { DeepAgentsServer } from "deepagents-acp";

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)" },
      },
    ],
  },
});

人在回路

使用 interruptOn，在智能体运行敏感工具之前要求用户在 IDE 中批准：

import { DeepAgentsServer } from "deepagents-acp";

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

当智能体调用受保护的工具时，IDE 会提示用户允许或拒绝该操作，并提供记住该会话决定的选项。

自定义工具

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();

自定义后端

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

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

技能与记忆

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(),
});

INFO

有关协议细节和编辑器支持，请参阅上游 ACP 文档：

简介：https://agentclientprotocol.com/get-started/introduction
客户端/编辑器：https://agentclientprotocol.com/get-started/clients

Going to production

Interpreters

Patterns

Configuration

快速开始

客户端

Zed

Toad

ACP Registry

CLI 参考

环境变量

编程式 API

`startServer`

`DeepAgentsServer`

服务器选项

智能体配置

自定义

多个智能体

斜杠命令

人在回路

自定义工具

自定义后端

技能与记忆

快速开始 ​

客户端 ​

Zed ​

Toad ​

ACP Registry ​

CLI 参考 ​

环境变量 ​

编程式 API ​

startServer ​

DeepAgentsServer ​

服务器选项 ​

智能体配置 ​

自定义 ​

多个智能体 ​

斜杠命令 ​

人在回路 ​

自定义工具 ​

自定义后端 ​

技能与记忆 ​

快速开始

客户端

Zed

Toad

ACP Registry

CLI 参考

环境变量

编程式 API

`startServer`

`DeepAgentsServer`

服务器选项

智能体配置

自定义

多个智能体

斜杠命令

人在回路

自定义工具

自定义后端

技能与记忆