Agent Client Protocol

通信无标准

你有没有想过，为什么 AI 编程助手只能在特定的工具里使用？

什么是 ACP

Agent Client Protocol——编码 Agent 与 IDE 之间的标准化通信协议

ACP 标准化了编码 Agent 与代码编辑器/IDE 之间的通信方式。借助 ACP，你可以在任何兼容的客户端中使用自定义 Deep Agent，使编辑器能够提供项目上下文并接收丰富的更新信息。

快速开始

三步走：安装 → 启动 → 连接编辑器

# 第一步：安装 ACP 集成包
$ npm install deepagents-acp
$ yarn add deepagents-acp
$ pnpm add deepagents-acp

// 第二步：编程方式启动 ACP 服务器
import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "coding-assistant",                            // Agent 名称，在编辑器中显示
    description: "AI coding assistant with filesystem access", // Agent 描述
  },
  workspaceRoot: process.cwd(),  // 工作区根目录，Agent 自动获取项目上下文
});

# 或者用 CLI 一行搞定（无需写代码）
$ npx deepagents-acp

支持的客户端

Deep Agent 可以在任何能运行 ACP Agent 服务器的地方工作

Zed 编辑器集成

三种配置方式——从零代码到完全自定义

// 方式一：零代码配置（最简单）——Zed settings.json
{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",          // 在编辑器 Agent 面板中显示的名称
        "command": "npx",              // 启动命令
        "args": ["deepagents-acp"],    // 启动参数
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-...",   // Anthropic Claude 系列模型
          // "DEEPSEEK_API_KEY": "sk-...",     // DeepSeek V4 系列（需安装 @langchain/deepseek）
          // "OPENAI_API_KEY": "sk-..."        // OpenAI GPT 系列
        }
      }
    }
  }
}

// 方式二：带 CLI 选项——自定义 Agent 名称、技能和调试模式
{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",
        "command": "npx",
        "args": [
          "deepagents-acp",
          "--name", "my-assistant",   // 自定义 Agent 名称
          "--skills", "./skills",     // 加载技能目录
          "--debug"                   // 启用调试日志（输出到 stderr）
        ],
        "env": {
          "DEEPSEEK_API_KEY": "sk-...",         // DeepSeek V4 系列（需安装 @langchain/deepseek）
          // "ANTHROPIC_API_KEY": "sk-ant-...",  // 或使用 Anthropic
          // "OPENAI_API_KEY": "sk-..."          // 或使用 OpenAI
        }
      }
    }
  }
}

自定义服务器

需要更多控制？写一个 TypeScript 服务器脚本

// server.ts —— 自定义服务器脚本
import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "my-agent",
    description: "My custom coding agent",
    skills: ["./skills/"],                          // 加载技能目录
    memory: ["./.deepagents/AGENTS.md"],            // 加载记忆文件（长期上下文）
  },
});

// Zed 配置指向自定义脚本——用 tsx 运行 TypeScript 服务器
{
  "agent": {
    "profiles": {
      "my-agent": {
        "name": "My Agent",
        "command": "npx",
        "args": ["tsx", "./server.ts"]  // 使用 tsx 直接运行 TS 文件
      }
    }
  }
}

CLI 参考

启动 ACP 服务器最快的方式——无需写代码

$ npx deepagents-acp [options]

# 基础启动
$ npx deepagents-acp

# 指定名称和技能
$ npx deepagents-acp \
    --name my-agent \
    --skills ./skills

# 调试模式
$ DEBUG=true npx deepagents-acp \
    --debug

编程 API 概览

两种方式：便捷函数 startServer 和完全控制 DeepAgentsServer

import { startServer } from "deepagents-acp";

// startServer 一步完成创建 + 启动，适合大多数场景
const server = await startServer({
  agents: {
    name: "coding-assistant",          // Agent 唯一标识
    description: "AI coding assistant", // Agent 功能描述
  },
  workspaceRoot: process.cwd(),        // 编辑器提供的项目根目录
});

import { DeepAgentsServer } from "deepagents-acp";

// DeepAgentsServer 允许完全控制服务器生命周期
const server = new DeepAgentsServer({
  agents: [/* 多 Agent 配置数组 */],
  serverName: "my-acp",              // ACP 服务器名称，在编辑器中显示
  serverVersion: "1.0.0",            // 服务器版本号
  workspaceRoot: process.cwd(),      // 工作区根目录
  debug: true,                       // 启用调试日志输出到 stderr
});

await server.start();  // 以 stdio 模式启动服务器

Agent 配置

每个 Agent 的完整配置选项——从名称到中间件

多 Agent 支持

在单个服务器中暴露多个 Agent，客户端选择使用哪个

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",                             // 通用编码助手
      description: "General 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();

操作模式与斜杠命令

三种内置操作模式 + 自定义斜杠命令——用户输入 / 触发

deepagents-acp 支持三种内置操作模式：Agent Mode（完整自主 Agent，有文件访问）、Plan Mode（协作规划，不修改文件）、Ask Mode（问答模式，不修改文件），在支持的客户端中切换。你还可以为每个 Agent 定义自定义斜杠命令：

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 让 Agent 在执行敏感工具前等待用户批准

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "careful-agent",
    // 配置需要在执行前暂停等待用户批准的工具
    interruptOn: {
      // execute：Shell 命令执行前暂停，用户可批准、编辑或拒绝
      execute: { allowedDecisions: ["approve", "edit", "reject"] },
      // write_file：写入文件前暂停，默认只允许批准或拒绝
      write_file: true,
    },
  },
});

自定义工具

用 LangChain tool 格式为 Agent 添加自定义能力

import { DeepAgentsServer } from "deepagents-acp";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 使用 LangChain tool 函数 + Zod schema 定义自定义工具
const searchTool = tool(
  async ({ query }) => {
    return `Results for: ${query}`;    // 工具的实际执行逻辑
  },
  {
    name: "search",                     // 工具名称，Agent 调用时使用
    description: "Search the codebase", // 工具描述，Agent 根据此判断何时调用
    schema: z.object({ query: z.string() }), // 使用 Zod 定义参数类型
  },
);

const deployTool = tool(
  async ({ environment }) => {
    return `Deployed to ${environment}`;
  },
  {
    name: "deploy",
    description: "Deploy the application",
    schema: z.object({
      environment: z.string().describe("staging or production"), // .describe() 为 Agent 提供参数说明
    }),
  },
);

const server = new DeepAgentsServer({
  agents: {
    name: "search-agent",
    tools: [searchTool, deployTool],    // 将自定义工具注册到 Agent
  },
});

await server.start();

后端与技能

自定义文件系统后端 + 加载技能和记忆文件

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

const server = new DeepAgentsServer({
  agents: {
    name: "custom-agent",
    // CompositeBackend 根据路径前缀路由到不同后端
    backend: new CompositeBackend({
      routes: [
        {
          prefix: "/workspace",           // /workspace 路径走磁盘文件系统
          backend: new FilesystemBackend({
            rootDir: "./workspace",       // 映射到本地目录
          }),
        },
        {
          prefix: "/",                    // 其余路径走内存状态后端
          backend: new StateBackend(),    // 适用于临时文件和状态数据
        },
      ],
    }),
  },
});

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(),            // 设置工作区根目录
});

完整示例

一个带有自定义工具、HITL 和技能的项目 Agent

import { DeepAgentsServer } from "deepagents-acp";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// 自定义工具：运行测试
const runTests = tool(
  async ({ scope }) => {
    return `Tests passed for ${scope}`;
  },
  {
    name: "run_tests",
    description: "Run project tests",
    schema: z.object({
      scope: z.string().describe("test scope, e.g. 'unit' or 'all'"),
    }),
  },
);

// 创建完整配置的 ACP 服务器——集成了自定义工具、技能、记忆和 HITL
const server = new DeepAgentsServer({
  agents: {
    name: "project-agent",
    description: "Full-featured coding assistant",
    tools: [runTests],                                // 自定义工具
    skills: ["./skills/"],                            // 技能目录
    memory: ["./.deepagents/AGENTS.md"],              // 长期记忆文件
    commands: [                                       // 自定义斜杠命令
      { name: "test", description: "Run tests" },
      { name: "review", description: "Review current changes" },
    ],
    interruptOn: {                                    // 人在环路：敏感操作需审批
      write_file: true,                               // 写文件前暂停
      execute: { allowedDecisions: ["approve", "reject"] }, // Shell 命令前暂停
    },
  },
  serverName: "my-project-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
});

await server.start();

动手练习

将你之前创建的 Deep Agent 通过 ACP 集成到编辑器中

现在轮到你了。选择一个你喜欢的编辑器，完成以下任务：

常见问题

集成过程中遇到的典型问题及解决方案

本章回顾

到这里，你已经掌握了通过 ACP 集成 Deep Agent 的完整流程

延伸阅读