Agent Client Protocol (ACP) - Docs by LangChain中文

Agent Client Protocol (ACP) 标准化了 coding agents 与代码编辑器或 IDE 之间的通信。借助 ACP protocol，你可以在任何兼容 ACP 的 client 中使用自定义 deep agents，让代码编辑器提供项目上下文并接收丰富更新。

ACP 专为 agent-editor 集成而设计。如果你希望 agent 调用外部服务器托管的工具，请参阅 Model Context Protocol (MCP)。

快速开始

安装 ACP 集成包：

npm install deepagents-acp

然后通过 ACP 暴露 deep agent。这会以 stdio 模式启动 ACP server，也就是从 stdin 读取请求，并向 stdout 写入响应。实践中，你通常会把它作为 ACP client（例如编辑器）启动的命令运行，然后 client 通过 stdio 与 server 通信。

import { startServer } from "deepagents-acp";

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

你也可以不写任何代码，直接使用 CLI：

npx deepagents-acp

Deep Agents ACP on npm

deepagents-acp 包同时提供 CLI 和编程式 API，用于通过 ACP 暴露 deep agents。

Clients

只要能运行 ACP agent server，就可以使用 deep agents。一些值得注意的 ACP clients 包括：

Zed
JetBrains IDEs
Visual Studio Code（通过 vscode-acp）
Neovim（通过 ACP-compatible plugins）

Zed

将 deep agent 添加到 Zed settings，即可注册到 Zed。Linux 路径为 ~/.config/zed/settings.json，macOS 路径为 ~/Library/Application Support/Zed/settings.json： 简单设置（无需代码）：

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

使用 CLI options：

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

自定义 server script： 如需更多控制，可以创建 TypeScript server script：

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

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

然后让 Zed 指向它：

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

打开 Zed 的 Agents panel，并启动一个 Deep Agents thread。

ACP Registry

Deep Agents 已在 ACP Agent Registry 中提供，可在 Zed 和 JetBrains IDEs 中一键安装。当 ACP client 支持 registry 时，用户无需任何手动配置即可发现并安装 Deep Agents。

CLI reference

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

npx deepagents-acp [options]

Option	Short	Description
`--name <name>`	`-n`	Agent 名称（默认：`"deepagents"`）
`--description <desc>`	`-d`	Agent 描述
`--model <model>`	`-m`	LLM 模型（默认：`"claude-sonnet-4-5-20250929"`）
`--workspace <path>`	`-w`	Workspace 根目录（默认：cwd）
`--skills <paths>`	`-s`	逗号分隔的 skill 路径
`--memory <paths>`		逗号分隔的 AGENTS.md 路径
`--debug`		启用 debug logging 到 stderr
`--help`	`-h`	显示帮助消息
`--version`	`-v`	显示版本

环境变量

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic/Claude 模型的 API key（必需）
`OPENAI_API_KEY`	OpenAI 模型的 API key
`DEBUG`	设置为 `"true"` 以启用 debug logging
`WORKSPACE_ROOT`	`--workspace` flag 的替代项

编程式 API

`startServer`

用于一次性创建并启动 server 的便利函数：

import { startServer } from "deepagents-acp";

const server = 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: "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 配置
`serverName`	`string`	`"deepagents-acp"`	ACP 使用的 server 名称
`serverVersion`	`string`	`"0.0.1"`	Server 版本
`workspaceRoot`	`string`	`process.cwd()`	Workspace 根目录
`debug`	`boolean`	`false`	启用 debug logging

Agent configuration

Option	Type	Description
`name`	`string`	唯一 agent 名称（必需）
`description`	`string`	Agent 描述
`model`	`string`	LLM 模型（默认：`"claude-sonnet-4-5-20250929"`）
`tools`	`StructuredTool[]`	自定义 LangChain tools
`systemPrompt`	`string`	自定义 system prompt
`middleware`	`AgentMiddleware[]`	自定义 middleware
`backend`	`AnyBackendProtocol`	Filesystem backend
`skills`	`string[]`	Skill source paths
`memory`	`string[]`	Memory source paths（AGENTS.md）
`interruptOn`	`Record<string, boolean \| InterruptOnConfig>`	需要用户批准的工具（HITL）
`commands`	`Array<{ name, description, input? }>`	自定义 slash commands

自定义

多个 agents

可以从单个 server 暴露多个 agents。创建 session 时，ACP client 会选择使用哪个 agent：

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

某些 ACP clients（例如 Zed）目前没有暴露用于在 agents 之间选择的 UI。在这种情况下，可以考虑分别运行多个 server 实例，每个实例只包含一个 agent。

Slash commands

Server 会向 IDE 注册内置 slash commands：/plan、/agent、/ask、/clear 和 /status。你也可以为每个 agent 定义自定义 commands：

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

使用 interruptOn 要求 agent 在运行敏感工具前先在 IDE 中获得用户批准：

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

当 agent 调用受保护工具时，IDE 会提示用户允许或拒绝该操作，并提供在当前 session 中记住该决定的选项。

自定义工具

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

自定义 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 和 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(),
});

协议详情和编辑器支持请参阅上游 ACP 文档：

Introduction: https://agentclientprotocol.com/get-started/introduction
Clients/editors: https://agentclientprotocol.com/get-started/clients

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​快速开始

Deep Agents ACP on npm

​Clients

​Zed

​ACP Registry

​CLI reference

​环境变量

​编程式 API

​startServer

​DeepAgentsServer

​Server options

​Agent configuration

​自定义

​多个 agents

​Slash commands

​Human-in-the-loop

​自定义工具

​自定义 backend

​Skills 和 memory

快速开始

Clients

Zed

ACP Registry

CLI reference

环境变量

编程式 API

`startServer`

`DeepAgentsServer`

Server options

Agent configuration

自定义

多个 agents

Slash commands

Human-in-the-loop

自定义工具

自定义 backend

Skills 和 memory