Agent Client Protocol (ACP)

Expose Deep Agents over the Agent Client Protocol (ACP) to integrate with code editors and IDEs.

Agent Client Protocol (ACP) standardizes communication between coding agents and code editors or IDEs. With the ACP protocol, you can make use of your custom deep agents with any ACP-compatible client, allowing your code editor to provide project context and receive rich updates.

ACP is designed for agent-editor integrations. If you want your agent to call tools hosted by external servers, see Model Context Protocol (MCP).

Quickstart

Install the ACP integration package:

npm

npm install deepagents-acp

yarn add deepagents-acp

pnpm add deepagents-acp

Then expose a deep agent over ACP.

This starts an ACP server in stdio mode (it reads requests from stdin and writes responses to stdout). In practice, you usually run this as a command launched by an ACP client (for example, your editor), which then communicates with the server over stdio.

import { startServer } from "deepagents-acp";

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

You can also use the CLI without writing any code:

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):

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

With CLI options:

{
  "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:

{
  "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.

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:

Google

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "google-genai:gemini-3.5-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-4-6",
      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: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 default 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" },
  ],
});

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

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 Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.