Typography

学习笔记

Deep Agents 学习09 ACP

发布于 # Deep Agents

当一个 Deep Agent 只能在终端里运行时，它的能力边界往往还停留在“脚本助手”阶段。ACP 的价值在于，它给编辑器和 Agent 之间补上了一层标准连接方式，让你已经定制好的模型、工具、记忆和审批逻辑，能够真正进入 IDE 工作流，而不是孤立在单独进程里。

为什么值得关注

一旦把 Deep Agent 暴露成 ACP 服务，编辑器就不再只是和它“聊天”，而是可以把项目上下文、会话状态和交互入口一起交给它。这意味着你不需要为了 IDE 集成重新造一套 Agent，只需要把已有能力接到一条标准协议上。

这项能力的核心价值是：

ACP 是什么

ACP 是 Agent Client Protocol，也就是“Agent 客户端协议”。

它解决的问题是：

可以把 ACP 理解成：

如果没有 ACP，不同编辑器和不同 Agent 往往需要各写各的私有集成。
有了 ACP，就可以让“兼容 ACP 的编辑器”和“兼容 ACP 的 Agent”互相接通。

ACP 和 MCP 的区别

ACP 和 MCP 经常会在同一类讨论里一起出现，所以第一次接触时很容易把它们当成一组平行替代方案。实际上它们处理的是两条完全不同的连接关系：一个负责把 Agent 接进编辑器，一个负责把工具接进 Agent。先把这层关系分清，后面做架构设计时就不容易混线。

这两个概念很容易混淆，但关注方向完全不同。

ACP

ACP 关注的是：

也就是说，ACP 解决的是“Agent 接到编辑器里”这件事。

MCP

MCP 关注的是：

也就是说，MCP 解决的是“Agent 接工具”这件事。

一句话区分

使用 ACP 能得到什么

把 Deep Agent 暴露成 ACP 服务后，通常可以获得这些能力：

如果你已经有：

那么 ACP 的价值就是把这些能力带进 IDE，而不是只能停留在 CLI 或服务端。

最小接入流程

把 Deep Agent 暴露给 ACP，最小只需要两步：

  1. 安装 deepagents-acp
  2. 用 AgentServerACP 包装你的 Deep Agent，并通过 stdio 启动 ACP server

第一步：安装依赖

pip

pip install deepagents-acp

uv

uv add deepagents-acp

这一步在做什么

你安装的是 ACP 集成层，而不是重新安装 Deep Agents 核心框架。

它的作用是：

第二步：把 Deep Agent 包装成 ACP 服务

安装完依赖之后，真正关键的动作其实只有一个：把你已经写好的 Deep Agent 变成一个“会说 ACP 协议”的服务入口。下面这段代码看起来很短，但它已经把 Agent 本体、协议适配和启动方式连到了一起。

下面是一份最小可运行示例：

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",
        system_prompt="You are a helpful coding assistant",
        checkpointer=MemorySaver(),
    )

    server = AgentServerACP(agent)
    await run_agent(server)


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

这段代码在做什么

可以把它拆成四层理解。

1. 先创建一个普通 Deep Agent

agent = create_deep_agent(...)

这里和你平时创建 Deep Agent 没有本质区别。

你仍然可以自定义：

也就是说：

2. 用 AgentServerACP 做协议适配

server = AgentServerACP(agent)

这一步相当于：

3. 用 run_agent(server) 启动协议服务

await run_agent(server)

这一步会启动 ACP server。

它默认通过：

这是一种非常典型的本地协议通信方式，尤其适合被编辑器或 IDE 当作子进程拉起。

4. 用 asyncio.run(main()) 启动整个异步服务

ACP server 是异步运行的，因此主入口也使用异步方式启动。

为什么这里是 stdio 模式

ACP 服务通常不是你手工在终端里直接操作的网络服务，而更像：

这种方式的好处是：

你可以把它理解成：

一个关键认知：ACP 只是“接入层”

很多人第一次看到 ACP，会误以为：

其实不是。

ACP 的角色只是：

因此：

哪些编辑器或客户端可以使用

只要某个客户端兼容 ACP，它就有机会接入你的 Deep Agent。

常见可用客户端包括：

这意味着：

Zed 集成思路

把 ACP server 写出来之后，下一步通常不是继续改 Python 代码，而是把它真正接进一个客户端环境里。Zed 是比较典型的例子，因为它能很好地体现“编辑器只关心怎么启动这个 Agent 服务，而不关心你的 Agent 内部怎么实现”这件事。

Zed 是一个比较典型的 ACP client。

接入流程可以理解为四步：

  1. 准备一个可运行的 ACP agent 启动命令
  2. 配置模型和环境变量
  3. 在 Zed 的 settings.json 中注册这个命令
  4. 在 Zed 里启动对应 agent thread

一个典型注册方式

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

这里的关键点

因此对于编辑器来说，最重要的是：

Toad 的定位

如果你想把 ACP agent server 作为本地开发工具运行，可以借助 Toad 这类工具管理进程。

例如：

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" .

适合什么场景

适合：

什么时候适合接入 ACP

ACP 不是所有场景都必须用，但在以下场景特别有价值。

1. 你已经有自己的 Deep Agent

例如你已经配置了：

这时 ACP 的价值是：

2. 你希望编辑器能提供更强项目上下文

编辑器通常更容易提供：

ACP 可以成为这个上下文输入的协议层。

3. 你要做团队内部的 Agent IDE 集成

如果你在做：

那 ACP 是非常自然的接入方式。

什么时候不一定要用 ACP

如果你的需求只是：

那 ACP 不是必需组件。

因为 ACP 的主要价值是：

如果没有这个需求，直接用 CLI 或 SDK 往往更简单。

实践中的架构理解

如果你准备把 ACP 真正接进团队工作流，这里最好建立一个稳定的分层视角：哪些事情属于 Agent 本体，哪些属于协议适配，哪些又属于编辑器客户端。这个边界一旦清楚，后续排错和扩展都会轻松很多。

把 ACP 放到整体系统里，可以这样看：

Deep Agents SDK

负责：

ACP 适配层

负责：

编辑器 / IDE

负责：

这个分层非常重要，因为它意味着：

设计上的几个关键点

1. 记忆与状态仍然由 Agent 自己管理

ACP 不会替你处理：

这些仍然是 Agent 构建层要负责的事情。

例如示例里加 MemorySaver()，就是为了给 Agent 提供基础状态持久化。

2. ACP server 更像“入口”而不是“业务逻辑层”

真正的业务逻辑最好仍然放在：

不要把核心工作流都堆到 ACP 启动脚本里。

3. 启动命令要稳定

既然编辑器通常通过 command 启动 ACP server，那么你的启动入口应该：

最小可用落地方式

如果你想最快把自己的 Deep Agent 接到编辑器里，建议按这个路径走：

  1. 先写一个最小版 ACP server 脚本
  2. 先在终端本地跑通这个脚本
  3. 确认模型 API key 和依赖都正常
  4. 再把这个脚本注册到你的 ACP client（如 Zed）
  5. 再逐步把自定义工具、记忆、子代理加进去

这样排查成本最低。

常见错误与排查

启动脚本能跑，但编辑器连不上

常见原因：

解决：

ACP server 启动后没有响应

常见原因：

解决：

编辑器接入了 Agent，但能力不完整

常见原因：

解决：

以为 ACP 能替代 MCP

这是理解错误。

实际情况是：

解决：

记忆或线程状态不稳定

常见原因：

解决：

验收标准

可以用下面的标准判断 ACP 集成是否真正跑通：

推荐实操顺序

建议按这个顺序落地：

  1. 先安装 deepagents-acp
  2. 写一个最小 ACP server 脚本
  3. 本地验证脚本能启动并运行
  4. 再在编辑器中注册该命令
  5. 验证编辑器与 Agent 的基本通信
  6. 再逐步叠加工具、memory、subagents 等能力
  7. 最后再做团队级或产品级的 IDE 集成封装

关键要点

写在最后

ACP 的本质，是把一个已经具备实际能力的 Deep Agent，变成一个可以被编辑器标准化接入的外部智能体服务。

可以把它理解成三层：

当这三层打通之后，你的 Deep Agent 就不再只是终端或脚本里的能力，而是可以真正进入 IDE 工作流的智能体。