deepagents-acp

ACP (Agent Client Protocol) server for DeepAgents - enables integration with IDEs like Zed, JetBrains, and other ACP-compatible clients.

Overview

This package wraps DeepAgents with the Agent Client Protocol (ACP), allowing your AI agents to communicate with code editors and development tools through a standardized protocol.

What is ACP?

The Agent Client Protocol is an open standard for communication between code editors and AI-powered coding agents — similar to what LSP did for language servers. It enables:

IDE Integration: Connect your agents to Zed, JetBrains IDEs, Neovim, Emacs, and other compatible tools
Standardized Communication: JSON-RPC 2.0 based protocol over stdio
Rich Interactions: Text, images, file operations, tool calls, terminals, diffs, and permission requests
Session Management: Persistent conversations with full history replay
No Vendor Lock-in: Use any model, switch between agents, all through one open protocol
ACP Registry: One-click agent installation from within supported IDEs

Installation

npm install deepagents-acp
# or
pnpm add deepagents-acp

Quick Start

Using the CLI (Recommended)

The easiest way to start is with the CLI:

# Run with defaults
npx deepagents-acp

# With custom options
npx deepagents-acp --name my-agent --debug

# Full options
npx deepagents-acp \
  --name coding-assistant \
  --model claude-sonnet-4-5-20250929 \
  --workspace /path/to/project \
  --skills ./skills,~/.deepagents/skills \
  --debug

CLI 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 Usage

import { startServer } from "deepagents-acp";

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

Advanced Configuration

import { DeepAgentsServer } from "deepagents-acp";
import { FilesystemBackend } from "deepagents";

const server = new DeepAgentsServer({
  // Define multiple agents
  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",
      model: "claude-sonnet-4-5-20250929",
      systemPrompt: "You are a code review expert...",
    },
  ],

  // Server options
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

Multiple Agents

When you define multiple agents, the client selects which agent to use at session creation time by passing configOptions.agent in the session/new ACP request. If not specified, the first agent in the configuration is used by default.

// Client sends session/new with configOptions to select an agent:
// { "configOptions": { "agent": "reviewer" } }  → uses the "reviewer" agent
// { "configOptions": { "agent": "code-agent" } } → uses the "code-agent" agent
// { }                                            → uses the first agent ("code-agent")

Note: Some ACP clients (like Zed) don't currently expose a UI for passing configOptions at session creation. In that case, consider running separate server instances with a single agent each, or using separate Zed profiles pointing to different server scripts.

Usage with Zed

To use with Zed, add the agent to your settings (~/.config/zed/settings.json on Linux, ~/Library/Application Support/Zed/settings.json on macOS):

Simple Setup

{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",
        "command": "npx",
        "args": ["deepagents-acp"]
      }
    }
  }
}

With Options

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

Custom Script (Advanced)

For more control, create a custom script:

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

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

Then configure Zed:

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

API Reference

DeepAgentsServer

The main server class that handles ACP communication.

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer(options);

Options

Option	Type	Description
`agents`	`DeepAgentConfig \| DeepAgentConfig[]`	Agent configuration(s)
`serverName`	`string`	Server name for ACP (default: "deepagents-acp")
`serverVersion`	`string`	Server version (default: "0.0.1")
`workspaceRoot`	`string`	Workspace root directory (default: cwd)
`debug`	`boolean`	Enable debug logging (default: false)

DeepAgentConfig

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 tools
`systemPrompt`	`string`	Custom system prompt
`middleware`	`AgentMiddleware[]`	Custom middleware
`backend`	`BackendProtocol \| BackendFactory`	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

Methods

start()

Start the ACP server. Listens on stdio by default.

await server.start();

stop()

Stop the server and cleanup.

server.stop();

startServer()

Convenience function to create and start a server.

import { startServer } from "deepagents-acp";

const server = await startServer(options);

Features

Slash Commands

The server provides built-in slash commands accessible from the IDE's prompt input. Type / to see available commands:

Command	Description
`/plan`	Switch to plan mode (read-only planning)
`/agent`	Switch to agent mode (full autonomous)
`/ask`	Switch to ask mode (Q&A, no file changes)
`/clear`	Clear conversation context and start fresh
`/status`	Show session status and loaded skills

You can also define custom slash commands per agent:

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

Modes

The server supports three operating modes, switchable via slash commands or programmatically:

Agent Mode (agent): Full autonomous agent with file access
Plan Mode (plan): Planning and discussion without changes
Ask Mode (ask): Q&A without file modifications

Thinking / Reasoning Messages

When using models with extended thinking (e.g., Claude with thinking: { type: "enabled" }), the server streams reasoning tokens to the IDE as thought_message_chunk updates. This gives users visibility into the agent's chain-of-thought process in clients that support it.

Tool Call Enhancements

The server provides rich tool call reporting to the IDE:

Tool call kinds — each tool call is categorized using ACP-standard kinds (read, edit, search, execute, think, etc.) so the IDE can display appropriate icons
File locations (follow-along) — tool calls that operate on files (e.g., read_file, edit_file, grep) report { path, line } locations, enabling IDEs to open and highlight the files the agent is working with in real time
Diff content — when the agent edits a file, the tool call update includes { type: "diff", path, oldText, newText } content so the IDE can render inline diffs
Raw input/output — tool call notifications include the raw tool arguments and results for transparency

Human-in-the-Loop (Permission Requests)

When agents are configured with interruptOn, the server bridges LangGraph's interrupt system to the ACP session/request_permission protocol. This surfaces approval prompts in the IDE before sensitive tools execute:

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 shows a permission dialog with options:

Allow once — approve this specific invocation
Reject — deny this specific invocation
Always allow — approve and remember for this session
Always reject — deny and remember for this session

Terminal Integration

When the ACP client supports the terminal capability (e.g., Zed, JetBrains), the server uses the client's terminal for execute tool calls instead of running commands locally. This provides:

Live streaming output — terminal output scrolls in real time inside the IDE's agent panel
Process control — the IDE can kill long-running commands
Embedded display — terminal output is embedded directly in the tool call UI

If the client doesn't support terminals, commands fall back to local execution (current behavior).

Session Persistence

Sessions are persisted using LangGraph's checkpointer. When loading a session with session/load, the server replays the full conversation history back to the client via ACP notifications, including:

User messages
Agent responses
Tool calls and their results
Plan entries

This ensures the IDE shows the complete conversation when resuming a session.

ACP Filesystem Backend

When the ACP client advertises fs.readTextFile and fs.writeTextFile capabilities, the server can proxy file operations through the client instead of reading/writing directly from disk. This enables:

Unsaved buffer access — the agent reads the editor's current buffer, including unsaved changes
IDE-tracked modifications — file writes go through the IDE, enabling undo, change tracking, and diff highlighting

Falls back to local filesystem operations for ls, glob, and grep which have no ACP equivalents.

ACP Protocol Support

This package implements the following ACP methods:

Agent Methods (what we implement)

Method	Description
`initialize`	Negotiate versions and capabilities
`authenticate`	Handle authentication (passthrough)
`session/new`	Create a new conversation session
`session/load`	Resume an existing session with full history replay
`session/prompt`	Process user prompts and slash commands
`session/cancel`	Cancel ongoing operations
`session/set_mode`	Switch agent modes

Client Methods (what we call on the client)

Method	Description
`session/request_permission`	Prompt user to approve/reject tool calls
`fs/read_text_file`	Read file contents (including unsaved buffers)
`fs/write_text_file`	Write file contents through the IDE
`terminal/create`	Start a command in the client's terminal
`terminal/output`	Get terminal output
`terminal/wait_for_exit`	Wait for command completion
`terminal/kill`	Kill a running command
`terminal/release`	Release terminal resources

Session Updates (what we send)

Update	Description
`agent_message_chunk`	Stream agent text responses
`thought_message_chunk`	Stream agent thinking/reasoning
`tool_call`	Notify about tool invocations with kind, locations, and input
`tool_call_update`	Update tool call status with content (text, diffs, terminals)
`plan`	Send task plan entries
`available_commands_update`	Advertise slash commands to the client

Capabilities

The server advertises these capabilities:

loadSession: Session persistence with history replay
promptCapabilities.image: Image content support
promptCapabilities.embeddedContext: Embedded context support
sessionCapabilities.modes: Agent mode switching
sessionCapabilities.commands: Slash command support

Tool Call Kinds

Tool calls are categorized with ACP-standard kinds for proper icon display:

Kind	Tools
`read`	`read_file`, `ls`
`search`	`grep`, `glob`
`edit`	`write_file`, `edit_file`
`execute`	`execute`, `shell`
`think`	`write_todos`
`other`	`task`, custom tools

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    IDE (Zed, JetBrains)                     │
│                      ACP Client                             │
└─────────────────────┬───────────────────────────────────────┘
                      │ stdio (JSON-RPC 2.0)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                  deepagents-acp                          │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              AgentSideConnection                    │   │
│   │   (from @agentclientprotocol/sdk)                   │   │
│   └─────────────────────┬───────────────────────────────┘   │
│                         │                                   │
│   ┌─────────────────────▼───────────────────────────────┐   │
│   │              Message Adapter                        │   │
│   │   ACP ContentBlock ←→ LangChain Messages            │   │
│   └─────────────────────┬───────────────────────────────┘   │
│                         │                                   │
│   ┌─────────────────────▼───────────────────────────────┐   │
│   │               DeepAgent                             │   │
│   │  (from deepagents package)                          │   │
│   └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Examples

Custom Backend

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: (config) => new StateBackend(config) },
      ],
    }),
  },
});

With Custom Tools

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

const searchTool = tool(
  async ({ query }) => {
    // Search implementation
    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],
  },
});

With Human-in-the-Loop Approval

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "safe-agent",
    description: "Agent that asks before writing or executing",
    interruptOn: {
      write_file: true,
      edit_file: true,
      execute: {
        allowedDecisions: ["approve", "edit", "reject"],
      },
    },
  },
});

When the agent tries to write a file or run a command, the IDE will prompt the user to approve, reject, or always-allow the operation.

With Custom Slash Commands

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "project-agent",
    commands: [
      { name: "test", description: "Run the project test suite" },
      { name: "build", description: "Build the project" },
      {
        name: "deploy",
        description: "Deploy to staging",
        input: { hint: "environment (staging or production)" },
      },
    ],
  },
});

ACP Registry

DeepAgents is available in the ACP Agent Registry for one-click installation in Zed and JetBrains IDEs. The registry manifest is at agent.json:

{
  "id": "deepagents",
  "name": "DeepAgents",
  "description": "Batteries-included AI coding agent powered by LangChain.",
  "distribution": {
    "npx": {
      "package": "deepagents-acp"
    }
  }
}

FilesExpand file tree

README.md

Latest commit

History