# Server

> deepagents_acp → Server

The [`ACPAgentServer`](#deepagents_acp.server.ACPAgentServer) class is the core of the Python ACP integration. It wraps DeepAgents with the [Agent Client Protocol](https://agentclientprotocol.com), enabling communication with IDEs like Zed, JetBrains, and other ACP-compatible clients.

> **Learn more:** For the ACP specification, see [agentclientprotocol.com](https://agentclientprotocol.com).

## Basic Usage

```python
import asyncio
from deepagents_acp.server import serve_acp_stdio

asyncio.run(serve_acp_stdio(root_dir="/path/to/project"))
```

The `serve_acp_stdio` convenience function creates an `ACPAgentServer` with sensible defaults and runs it over stdio.

## Server Configuration

The `ACPAgentServer` accepts the following configuration:

| Parameter      | Type           | Description                                               |
| -------------- | -------------- | --------------------------------------------------------- |
| `root_dir`     | `str`          | Root directory accessible to the agent                    |
| `checkpointer` | `Checkpointer` | LangGraph checkpointer for session persistence            |
| `mode`         | `str`          | Initial operating mode (`"ask_before_edits"` or `"auto"`) |

```python
from langgraph.checkpoint.memory import MemorySaver
from deepagents_acp.server import ACPAgentServer

server = ACPAgentServer(
    root_dir="/path/to/project",
    checkpointer=MemorySaver(),
    mode="ask_before_edits",
)
```

## Modes

The server supports two operating modes, switchable via the ACP `session/set_mode` request:

| Mode               | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `ask_before_edits` | Ask permission before file edits and writes (default)   |
| `auto`             | Auto-accept edit operations, only ask for plan approval |

Switching modes recreates the underlying DeepAgent with the appropriate interrupt configuration.

## Backends

The server configures a `CompositeBackend` that combines:

- **`FilesystemBackend`** — for real filesystem access within `root_dir` (using virtual mode)
- **`StateBackend`** — for ephemeral in-memory storage of `/memories/` and `/conversation_history/` paths

```python
from deepagents.backends import CompositeBackend, FilesystemBackend, StateBackend

def create_backend(tr):
    ephemeral = StateBackend(tr)
    return CompositeBackend(
        default=FilesystemBackend(root_dir=root_dir, virtual_mode=True),
        routes={
            "/memories/": ephemeral,
            "/conversation_history/": ephemeral,
        },
    )
```

## Human-in-the-Loop (Permission Requests)

The interrupt configuration is determined by the current mode:

**`ask_before_edits` mode** requires approval for `edit_file`, `write_file`, and `write_todos`.

**`auto` mode** only requires approval for `write_todos` (plan changes).

When a protected tool is invoked, the IDE shows a permission dialog with Approve and Reject options. For `write_todos`, rejected plans prompt the agent to ask for feedback and create an improved plan.

## Plan Management

The server tracks plan state per session and supports:

- **Auto-approval of plan updates** — when a plan is in progress (not all tasks completed), subsequent `write_todos` calls are auto-approved to allow the agent to update task status
- **Plan clearing** — rejected plans are cleared from the IDE display
- **Plan display** — approved plans are shown as both ACP `PlanEntry` updates and visible text messages

## Tool Call Reporting

Tool calls are reported to the IDE with rich metadata:

| Tool         | Kind     | Title Format   |
| ------------ | -------- | -------------- |
| `read_file`  | `read`   | Read \`path\`  |
| `edit_file`  | `edit`   | Edit \`path\`  |
| `write_file` | `edit`   | Write \`path\` |
| `ls`         | `search` | ls             |
| `glob`       | `search` | glob           |
| `grep`       | `search` | grep           |

For `edit_file` tool calls, the server sends diff content (`tool_diff_content`) so the IDE can render inline diffs.

## Streaming

The server streams agent responses using LangGraph's `astream` with `stream_mode="messages"`. Tool call chunks are accumulated and started once the arguments JSON is complete, providing real-time tool call notifications to the IDE.

## API Reference

## Classes

- [`AgentSessionContext`](https://reference.langchain.com/python/deepagents-acp/server/AgentSessionContext)
- [`AgentServerACP`](https://reference.langchain.com/python/deepagents-acp/server/AgentServerACP)

## Functions

- [`main()`](https://reference.langchain.com/python/deepagents-acp/__main__/main)
- [`convert_text_block_to_content_blocks()`](https://reference.langchain.com/python/deepagents-acp/utils/convert_text_block_to_content_blocks)
- [`convert_image_block_to_content_blocks()`](https://reference.langchain.com/python/deepagents-acp/utils/convert_image_block_to_content_blocks)
- [`convert_audio_block_to_content_blocks()`](https://reference.langchain.com/python/deepagents-acp/utils/convert_audio_block_to_content_blocks)
- [`convert_resource_block_to_content_blocks()`](https://reference.langchain.com/python/deepagents-acp/utils/convert_resource_block_to_content_blocks)
- [`convert_embedded_resource_block_to_content_blocks()`](https://reference.langchain.com/python/deepagents-acp/utils/convert_embedded_resource_block_to_content_blocks)
- [`contains_dangerous_patterns()`](https://reference.langchain.com/python/deepagents-acp/utils/contains_dangerous_patterns)
- [`extract_command_types()`](https://reference.langchain.com/python/deepagents-acp/utils/extract_command_types)
- [`truncate_execute_command_for_display()`](https://reference.langchain.com/python/deepagents-acp/utils/truncate_execute_command_for_display)
- [`format_execute_result()`](https://reference.langchain.com/python/deepagents-acp/utils/format_execute_result)

## Modules

- [`deepagents_acp`](https://reference.langchain.com/python/deepagents-acp/deepagents_acp)
- [`server`](https://reference.langchain.com/python/deepagents-acp/server)
- [`utils`](https://reference.langchain.com/python/deepagents-acp/utils)

## Types

- [`McpServer`](https://reference.langchain.com/python/deepagents-acp/server/McpServer)

## Constants

- [`SessionConfigOption`](https://reference.langchain.com/python/deepagents-acp/server/SessionConfigOption)
- [`cwd`](https://reference.langchain.com/python/deepagents-acp/server/AgentSessionContext/cwd)
- [`mode`](https://reference.langchain.com/python/deepagents-acp/server/AgentSessionContext/mode)
- [`model`](https://reference.langchain.com/python/deepagents-acp/server/AgentSessionContext/model)
- [`DANGEROUS_SHELL_PATTERNS`](https://reference.langchain.com/python/deepagents-acp/utils/DANGEROUS_SHELL_PATTERNS)