代理客户端协议 (ACP)

代理客户端协议 (ACP) 标准化了编码代理与代码编辑器或集成开发环境之间的通信。通过 ACP 协议，您可以在任何兼容 ACP 的客户端中使用您的自定义深度代理，让您的代码编辑器能够提供项目上下文并接收丰富的更新。

ACP 专为代理与编辑器的集成而设计。如果您希望代理调用由外部服务器托管的工具，请参阅模型上下文协议 (MCP)。

快速入门

安装 ACP 集成包：

npm install deepagents-acp

yarn add deepagents-acp

pnpm add deepagents-acp

然后，通过 ACP 暴露一个深度代理。这会以标准输入输出模式启动一个 ACP 服务器（它从标准输入读取请求，并将响应写入标准输出）。在实际应用中，您通常将其作为由 ACP 客户端（例如，您的编辑器）启动的命令运行，然后客户端通过标准输入输出与服务器进行通信。

import { startServer } from "deepagents-acp";

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

您也可以使用命令行界面，无需编写任何代码：

npx deepagents-acp

npm 上的 Deep Agents ACP

deepagents-acp 包提供了命令行界面和编程接口，用于通过 ACP 暴露深度代理。

客户端

深度代理可以在任何能运行 ACP 代理服务器的地方工作。一些值得关注的 ACP 客户端包括：

Zed
JetBrains IDEs
Visual Studio Code (通过 vscode-acp)
Neovim (通过兼容 ACP 的插件)

Zed

通过将您的深度代理添加到 Zed 设置中（Linux 系统在 ~/.config/zed/settings.json，macOS 系统在 ~/Library/Application Support/Zed/settings.json），将其注册到 Zed： 简单设置（无需代码）：

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

使用 CLI 选项：

{
  "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 指向它：

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

打开 Zed 的 Agents 面板，开始一个 Deep Agents 线程。

ACP 注册表

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

命令行界面参考

命令行界面是启动 ACP 服务器最快的方式。它无需代码——只需运行 npx deepagents-acp 并连接您的编辑器。

npx deepagents-acp [options]

选项	缩写	描述
`--name <name>`	`-n`	代理名称（默认：`"deepagents"`）
`--description <desc>`	`-d`	代理描述
`--model <model>`	`-m`	大语言模型（默认：`"claude-sonnet-4-5-20250929"`）
`--workspace <path>`	`-w`	工作区根目录（默认：当前工作目录）
`--skills <paths>`	`-s`	逗号分隔的技能路径
`--memory <paths>`		逗号分隔的 AGENTS.md 路径
`--debug`		启用调试日志输出到标准错误
`--help`	`-h`	显示帮助信息
`--version`	`-v`	显示版本号

环境变量

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

编程接口

`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: "功能齐全的编码助手",
      model: "google-genai:gemini-3.6-flash",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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: "功能齐全的编码助手",
      model: "openai:gpt-5.5",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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: "功能齐全的编码助手",
      model: "anthropic:claude-sonnet-4-6",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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: "功能齐全的编码助手",
      model: "openrouter:openrouter:z-ai/glm-5.2",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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: "功能齐全的编码助手",
      model: "fireworks:accounts/fireworks/models/glm-5p2",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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: "功能齐全的编码助手",
      model: "baseten:zai-org/GLM-5.2",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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: "功能齐全的编码助手",
      model: "ollama:north-mini-code-1.0",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "代码审查专家",
      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`	大语言模型（默认：`"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: "通用编码" },
    { name: "reviewer", description: "代码审查" },
  ],
});

一些 ACP 客户端（如 Zed）目前不提供用于选择代理的用户界面。在这种情况下，可以考虑为每个代理运行独立的服务器实例。

斜杠命令

服务器向 IDE 注册了内置的斜杠命令：/plan、/agent、/ask、/clear 和 /status。您也可以为每个代理定义自定义命令：

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "my-agent",
    commands: [
      { name: "test", description: "运行项目的测试套件" },
      { name: "lint", description: "运行代码检查器并修复问题" },
      {
        name: "deploy",
        description: "部署到预发布环境",
        input: { hint: "环境（预发布或生产）" },
      },
    ],
  },
});

人在回路 (Human-in-the-loop)

使用 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 `结果：${query}`;
  },
  {
    name: "search",
    description: "搜索代码库",
    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(),
});

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

介绍：https://agentclientprotocol.com/get-started/introduction
客户端/编辑器：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.

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

快速入门

npm 上的 Deep Agents ACP

客户端

Zed

ACP 注册表

命令行界面参考

环境变量

编程接口

`startServer`

`DeepAgentsServer`

服务器选项

代理配置

自定义

多代理

斜杠命令

人在回路 (Human-in-the-loop)

自定义工具

自定义后端

技能与记忆

​快速入门

npm 上的 Deep Agents ACP

​客户端

​Zed

​ACP 注册表

​命令行界面参考

​环境变量

​编程接口

​startServer

​DeepAgentsServer

​服务器选项

​代理配置

​自定义

​多代理

​斜杠命令

​人在回路 (Human-in-the-loop)

​自定义工具

​自定义后端

​技能与记忆

快速入门

客户端

Zed

ACP 注册表

命令行界面参考

环境变量

编程接口

`startServer`

`DeepAgentsServer`

服务器选项

代理配置

自定义

多代理

斜杠命令

人在回路 (Human-in-the-loop)

自定义工具

自定义后端

技能与记忆