feat(server): add ACP support

[christian-bromann]

This PR introduces the deepagents-acp package, enabling DeepAgents to integrate with IDEs like Zed, JetBrains, and other clients that support the Agent Client Protocol (ACP). This brings AI coding assistance directly into development environments through a standardized communication protocol.

Motivation

The Agent Client Protocol is emerging as a standard for how IDEs communicate with AI coding agents. By implementing ACP support, DeepAgents can now:

• Run inside IDEs: Zed, JetBrains, and other ACP-compatible editors can launch and communicate with DeepAgents
• Leverage native IDE features: File operations, terminal access, and workspace context are handled through the protocol
• Provide real-time streaming: Agent responses, tool calls, and task progress stream directly to the IDE

What's Included

New Package: deepagents-acp

A complete ACP server implementation that wraps DeepAgents:

File	Description
server.ts	Core DeepAgentsServer class implementing the ACP protocol
cli.ts	CLI entry point (npx deepagents-acp) with full option parsing
adapter.ts	Bidirectional conversion between ACP ContentBlocks and LangChain messages
types.ts	TypeScript types for agent configuration and ACP extensions
logger.ts	Flexible logging utility supporting stderr and file output
index.ts	Public API exports

ACP Protocol Implementation

Agent Methods:

• initialize - Negotiate protocol version and capabilities
• authenticate - Pass-through authentication
• session/new - Create conversation sessions with mode selection
• session/load - Resume existing sessions
• session/prompt - Process user prompts with streaming responses
• session/cancel - Cancel in-progress operations
• session/set_mode - Switch between agent/plan/ask modes

Session Updates (Streaming):

• agent_message_chunk - Stream text responses
• agent_thought_chunk - Stream agent reasoning
• tool_call / tool_call_update - Track tool execution
• plan - Send task planning updates

CLI Features

npx deepagents-acp \
  --name my-agent \
  --model claude-sonnet-4-5-20250929 \
  --skills ./skills \
  --memory ./AGENTS.md \
  --log-file ./debug.log \
  --debug

• Supports multiple argument formats for IDE compatibility (--name value, --name=value)
• Environment variable configuration (ANTHROPIC_API_KEY, DEBUG, WORKSPACE_ROOT)
• File-based logging for production debugging

Testing

Comprehensive test coverage:

Test File	Type	Tests
server.test.ts	Unit	Handler methods, configuration, error handling
server.int.test.ts	Integration	Session management, mode switching, cancellation
cli.int.test.ts	CLI Integration	Full protocol flow via spawned process
adapter.test.ts	Unit	Message format conversion
logger.test.ts	Unit	Logging behavior

Example

Added examples/acp-server/server.ts demonstrating programmatic usage with custom configuration.

Usage

With Zed

Add to ~/.config/zed/settings.json:

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

Programmatically

import { DeepAgentsServer, startServer } from "deepagents-acp";

// Quick start
await startServer({
  agents: { name: "my-agent", skills: ["./skills/"] }
});

// Or with full control
const server = new DeepAgentsServer({
  agents: [
    { name: "coder", model: "claude-sonnet-4-5-20250929" },
    { name: "reviewer", systemPrompt: "You are a code reviewer..." }
  ],
  debug: true,
  workspaceRoot: process.cwd(),
});
await server.start();

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    IDE (Zed, JetBrains)                     │
│                      ACP Client                             │
└─────────────────────┬───────────────────────────────────────┘
                      │ stdio (JSON-RPC 2.0 / NDJSON)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    deepagents-acp                           │
│   ┌─────────────────────────────────────────────────────┐   │
│   │           AgentSideConnection (ACP SDK)             │   │
│   └─────────────────────┬───────────────────────────────┘   │
│                         │                                   │
│   ┌─────────────────────▼───────────────────────────────┐   │
│   │              Message Adapter                        │   │
│   │   ACP ContentBlock ⟷ LangChain BaseMessage          │   │
│   └─────────────────────┬───────────────────────────────┘   │
│                         │                                   │
│   ┌─────────────────────▼───────────────────────────────┐   │
│   │               DeepAgent (LangGraph)                 │   │
│   │   Skills • Memory • Tools • Middleware              │   │
│   └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Future Improvements

• MCP (Model Context Protocol) server support for tool discovery
• HTTP/SSE transport (in addition to stdio)
• Session persistence to disk
• Multi-agent routing based on task type

[everywheredennise-oss]

🤖 Devin AI is starting automated code review...

[everywheredennise-oss]

🤖 Devin AI is starting automated code review...