代理客户端协议 (ACP)

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

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

快速入门

安装 ACP 集成包：

npm install deepagents-acp

然后通过 ACP 公开一个深度代理。这将启动一个 stdio 模式的 ACP 服务器（它从 stdin 读取请求并将响应写入 stdout）。在实践中，您通常将其作为由 ACP 客户端（例如您的编辑器）启动的命令运行，然后通过 stdio 与服务器通信。

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

DeepAgents ACP on npm

deepagents-acp 包提供了 CLI 和编程 API，用于通过 ACP 公开深度代理。

客户端

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

Zed
JetBrains IDE
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 的代理面板并启动一个 DeepAgents 线程。

ACP 注册表

DeepAgents 可在 ACP 代理注册表中获取，用于在 Zed 和 JetBrains IDE 中进行一键安装。当 ACP 客户端支持注册表时，用户可以发现并安装深度代理，而无需任何手动配置。

CLI 参考

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

npx deepagents-acp [options]

选项	短格式	描述
`--name <name>`	`-n`	代理名称（默认：`"deepagents"`）
`--description <desc>`	`-d`	代理描述
`--model <model>`	`-m`	LLM 模型（默认：`"claude-sonnet-4-5-20250929"`）
`--workspace <path>`	`-w`	工作区根目录（默认：当前工作目录）
`--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";

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

服务器选项

选项	类型	默认值	描述
`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 客户端在创建会话时选择要使用的代理：

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

一些 ACP 客户端（如 Zed）目前不提供用于在代理之间进行选择的 UI。在这种情况下，考虑运行具有单个代理的单独服务器实例。

斜杠命令

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

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 中用户批准后，代理才能运行敏感工具：

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({
      routes: [
        {
          prefix: "/workspace",
          backend: new FilesystemBackend({ rootDir: "./workspace" }),
        },
        { prefix: "/", backend: new StateBackend() },
      ],
    }),
  },
});

await server.start();

技能和记忆

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

在 GitHub 上编辑此页面或提交问题。

通过 MCP 将这些文档连接到 Claude、VSCode 等以获取实时答案。

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

快速入门

DeepAgents ACP on npm

客户端

Zed

ACP 注册表

CLI 参考

环境变量

编程 API

`startServer`

`DeepAgentsServer`

服务器选项

代理配置

自定义

多个代理

斜杠命令

人机回环

自定义工具

自定义后端

技能和记忆

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

​快速入门

DeepAgents ACP on npm

​客户端

​Zed

​ACP 注册表

​CLI 参考

​环境变量

​编程 API

​startServer

​DeepAgentsServer

​服务器选项

​代理配置

​自定义

​多个代理

​斜杠命令

​人机回环

​自定义工具

​自定义后端

​技能和记忆

快速入门

客户端

Zed

ACP 注册表

CLI 参考

环境变量

编程 API

`startServer`

`DeepAgentsServer`

服务器选项

代理配置

自定义

多个代理

斜杠命令

人机回环

自定义工具

自定义后端

技能和记忆