Agent Client Protocol (ACP)

在 Zed 等现代代码编辑器中直接使用基于 Deep Agents 构建的编码智能体

智能体客户端协议（Agent Client Protocol, ACP）是一套标准化的双向通信协议，用于在现代代码编辑器（如 Zed）与本地运行的自主编码智能体之间建立连接。通过 ACP，Deep Agents 可以化身为你的个人编程助手：在编辑器中读取当前打开的文件、审查光标位置的代码、执行重构，并向编辑器侧边栏实时推送对话回复。

快速起步 (Quickstart)

使用 npx 直接启动 Deep Agents ACP 服务端：

bash

npm install deepagents-acp

客户端连接指南 (Clients)

Zed 编辑器集成

Zed 原生支持 ACP 协议。只需在 Zed 的配置文件（settings.json）中注册 Deep Agents 即可：

bash

yarn add deepagents-acp

ACP 官方服务注册表 (ACP Registry)

Deep Agents 已收录进官方 ACP 注册表，编辑器支持一键自动发现与安装。

CLI 命令行参数参考 (CLI reference)

Deep Agents 提供了开箱即用的 ACP CLI 入口：

--model：指定驱动智能体的基础模型（默认为 anthropic:claude-sonnet-4-6 或对应环境变量）。
--backend：配置虚拟文件系统后端。
--skills：加载技能库路径。

核心环境变量

ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY：对应提供商凭证。
DEEPAGENTS_ACP_PORT：自定义监听端口。

编程式 API 接入 (Programmatic API)

除了直接运行 CLI 外，你还可以在 Node.js 代码中以编程方式启动 ACP 服务端，并注入深度定制的逻辑：

`startServer` 入口函数

快速启动标准服务实例：

bash

pnpm add deepagents-acp

`DeepAgentsServer` 类与细粒度配置

完全接管服务器生命周期与参数定义：

import { startServer } from "deepagents-acp";

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

深度自定义扩展 (Customization)

1. 多智能体切换 (Multiple agents)

在同一个 ACP 服务端中暴露多个具有不同人设与专长的智能体（如通用助手、重构专家、测试编写专家），供用户在编辑器中随时切换。

2. 斜杠指令支持 (Slash commands)

定义 /review、 est 等专属斜杠指令，用户在编辑器对话框输入指令即可触发预设工作流。

3. 人在回路安全确认 (Human-in-the-loop)

当智能体在编辑器中尝试执行危险的删除或终端命令前，在编辑器弹窗中提示用户点击批准或拒绝。

4. 挂载自定义工具 (Custom tools)

为编辑器中的智能体注入内部专有的代码检查工具或私有 API。

5. 自定义后端与技能记忆集成

挂载本地磁盘 FilesystemBackend 以及 AGENTS.md，使智能体严格遵循团队的代码规范。

bash

npx deepagents-acp

Deep Agents ACP on npm
The deepagents-acp package provides both a CLI and a programmatic API for exposing deep agents over ACP.

Clients

Deep agents work anywhere you can run an ACP agent server. Some notable ACP clients include:

Zed
JetBrains IDEs
Visual Studio Code (via vscode-acp)
Neovim (via ACP-compatible plugins)

Zed

Register your deep agent with Zed by adding it to your Zed settings (~/.config/zed/settings.json on Linux, ~/Library/Application Support/Zed/settings.json on macOS):

Simple setup (no code required):

json

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

With CLI options:

json

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

Custom server script:

For more control, create a TypeScript server script:

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

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

Then point Zed at it:

json

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

Open Zed's Agents panel and start a Deep Agents thread.

ACP Registry

Deep Agents is available in the ACP Agent Registry for one-click installation in Zed and JetBrains IDEs. When an ACP client supports the registry, users can discover and install Deep Agents without any manual configuration.

CLI reference

The CLI is the fastest way to start an ACP server. It requires no code—just run npx deepagents-acp and connect your editor.

bash

npx deepagents-acp [options]

Option	Short	Description
`--name <name>`	`-n`	Agent name (default: `"deepagents"`)
`--description <desc>`	`-d`	Agent description
`--model <model>`	`-m`	LLM model (default: `"claude-sonnet-4-5-20250929"`)
`--workspace <path>`	`-w`	Workspace root directory (default: cwd)
`--skills <paths>`	`-s`	Comma-separated skill paths
`--memory <paths>`		Comma-separated AGENTS.md paths
`--debug`		Enable debug logging to stderr
`--help`	`-h`	Show help message
`--version`	`-v`	Show version

Environment variables

Variable	Description
`ANTHROPIC_API_KEY`	API key for Anthropic/Claude models (required)
`OPENAI_API_KEY`	API key for OpenAI models
`DEBUG`	Set to `"true"` to enable debug logging
`WORKSPACE_ROOT`	Alternative to `--workspace` flag

Programmatic API

`startServer`

Convenience function to create and start a server in one call:

import { startServer } from "deepagents-acp";

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

`DeepAgentsServer`

For full control, use the DeepAgentsServer class directly:

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "google:gemini-3.6-flash",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "openai:gpt-5.5",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "anthropic:claude-sonnet-5",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "openrouter:z-ai/glm-5.2",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "fireworks:accounts/fireworks/models/glm-5p2",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "baseten:zai-org/GLM-5.2",
      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();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "ollama:north-mini-code-1.0",
      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 configuration(s)
`serverName`	`string`	`"deepagents-acp"`	Server name for ACP
`serverVersion`	`string`	`"0.0.1"`	Server version
`workspaceRoot`	`string`	`process.cwd()`	Workspace root directory
`debug`	`boolean`	`false`	Enable debug logging

Agent configuration

Option	Type	Description
`name`	`string`	Unique agent name (required)
`description`	`string`	Agent description
`model`	`string`	LLM model (default: `"claude-sonnet-4-5-20250929"`)
`tools`	`StructuredTool[]`	Custom LangChain tools
`systemPrompt`	`string`	Custom system prompt
`middleware`	`AgentMiddleware[]`	Custom middleware appended to the Deep Agents stack
`backend`	`AnyBackendProtocol`	Filesystem backend
`skills`	`string[]`	Skill source paths
`memory`	`string[]`	Memory source paths (AGENTS.md)
`interruptOn`	`Record<string, boolean \| InterruptOnConfig>`	Tools requiring user approval (HITL)
`commands`	`Array<{ name, description, input? }>`	Custom slash commands

Customization

Multiple agents

You can expose multiple agents from a single server. The ACP client selects which agent to use when creating a session:

import { DeepAgentsServer } from "deepagents-acp";

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

NOTE

Some ACP clients (like Zed) don't currently expose a UI for selecting between agents. In that case, consider running separate server instances with a single agent each.

Slash commands

The server registers built-in slash commands with the IDE: /plan, /agent, /ask, /clear, and /status. You can also define custom commands per 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)" },
      },
    ],
  },
});

Human-in-the-loop

Use interruptOn to require user approval in the IDE before the agent runs sensitive tools:

import { DeepAgentsServer } from "deepagents-acp";

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

When the agent calls a protected tool, the IDE prompts the user to allow or reject the operation, with options to remember the decision for the session.

Custom tools

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

Custom backend

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" }),
    }),
  },
});

Skills and 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(),
});

NOTE

See the upstream ACP docs for protocol details and editor support:

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

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Agent Client Protocol (ACP) ​

快速起步 (Quickstart) ​

客户端连接指南 (Clients) ​

Zed 编辑器集成 ​

ACP 官方服务注册表 (ACP Registry) ​

CLI 命令行参数参考 (CLI reference) ​

核心环境变量 ​

编程式 API 接入 (Programmatic API) ​

startServer 入口函数 ​

DeepAgentsServer 类与细粒度配置 ​

深度自定义扩展 (Customization) ​

1. 多智能体切换 (Multiple agents) ​

2. 斜杠指令支持 (Slash commands) ​

3. 人在回路安全确认 (Human-in-the-loop) ​

4. 挂载自定义工具 (Custom tools) ​

5. 自定义后端与技能记忆集成 ​

Clients ​

Zed ​

ACP Registry ​

CLI reference ​

Environment variables ​

Programmatic API ​

startServer ​

DeepAgentsServer ​

Server options ​

Agent configuration ​

Customization ​

Multiple agents ​

Slash commands ​

Human-in-the-loop ​

Custom tools ​

Custom backend ​

Skills and memory ​

Agent Client Protocol (ACP)

快速起步 (Quickstart)

客户端连接指南 (Clients)

Zed 编辑器集成

ACP 官方服务注册表 (ACP Registry)

CLI 命令行参数参考 (CLI reference)

核心环境变量

编程式 API 接入 (Programmatic API)

`startServer` 入口函数

`DeepAgentsServer` 类与细粒度配置

深度自定义扩展 (Customization)

1. 多智能体切换 (Multiple agents)

2. 斜杠指令支持 (Slash commands)

3. 人在回路安全确认 (Human-in-the-loop)

4. 挂载自定义工具 (Custom tools)

5. 自定义后端与技能记忆集成

Clients

Zed

ACP Registry

CLI reference

Environment variables

Programmatic API

`startServer`

`DeepAgentsServer`

Server options

Agent configuration

Customization

Multiple agents

Slash commands

Human-in-the-loop

Custom tools

Custom backend

Skills and memory