You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Python implementation of the Agent Client Protocol (ACP). Use it to build agents that communicate with ACP-capable clients (e.g. Zed) over stdio.
3
+
Python SDK for the Agent Client Protocol (ACP). Build agents that speak ACP over stdio so tools like Zed can orchestrate them.
4
4
5
-
> This library version is compatible with the corresponding ACP version. However, we lack sufficient resources to release each version. Welcome to contribute!
5
+
> Each release tracks the matching ACP schema version. Contributions that improve coverage or tooling are very welcome.
6
6
7
-
- Package name: `agent-client-protocol` (import as `acp`)
- Featured: Listed as the first third-party SDK on the official ACP site — see https://agentclientprotocol.com/libraries/community
7
+
**Highlights**
8
+
9
+
- Typed dataclasses generated from the upstream ACP schema (`acp.schema`)
10
+
- Async agent base class plus stdio transport helpers for quick bootstrapping
11
+
- Included examples that stream content updates and tool calls end-to-end
11
12
12
13
## Install
13
14
14
15
```bash
15
16
pip install agent-client-protocol
16
-
# or
17
+
# or with uv
17
18
uv add agent-client-protocol
18
19
```
19
20
20
-
## Development (contributors)
21
+
## Quickstart
21
22
22
-
```bash
23
-
make install # set up venv
24
-
ACP_SCHEMA_VERSION=<ref> make gen-all # generate meta.py & schema.py
25
-
make check # lint + typecheck
26
-
make test# run tests
27
-
```
23
+
1. Install the package and point your ACP-capable client at the provided echo agent:
24
+
```bash
25
+
pip install agent-client-protocol
26
+
python examples/echo_agent.py
27
+
```
28
+
2. Wire it into your client (e.g. Zed → Agents panel) so stdio is connected; the SDK handles JSON-RPC framing and lifecycle messages.
28
29
29
-
## Minimal agent example
30
+
Prefer a step-by-step walkthrough? Read the [Quickstart guide](docs/quickstart.md) or the hosted docs: https://psiace.github.io/agent-client-protocol-python/.
30
31
31
-
See a complete streaming echo example in [examples/echo_agent.py](examples/echo_agent.py). It streams back each text block using `session/update` and ends the turn.
32
+
### Minimal agent sketch
32
33
33
34
```python
34
35
import asyncio
35
36
36
-
from acp import (
37
-
Agent,
38
-
AgentSideConnection,
39
-
InitializeRequest,
40
-
InitializeResponse,
41
-
NewSessionRequest,
42
-
NewSessionResponse,
43
-
PromptRequest,
44
-
PromptResponse,
45
-
SessionNotification,
46
-
stdio_streams,
47
-
)
48
-
from acp.schema import TextContentBlock, AgentMessageChunk
37
+
from acp import Agent, AgentSideConnection, PromptRequest, PromptResponse, SessionNotification, stdio_streams
38
+
from acp.schema import AgentMessageChunk, TextContentBlock
A Python implementation of the Agent Client Protocol (ACP). Build agents that communicate with ACP-capable clients (e.g. Zed) over stdio.
3
+
Welcome to the Python SDK for the Agent Client Protocol (ACP). The package ships ready-to-use transports, typed protocol models, and examples that stream messages to ACP-aware clients such as Zed.
4
4
5
-
## Install
5
+
## What you get
6
6
7
-
```bash
8
-
pip install agent-client-protocol
9
-
```
7
+
- Fully typed dataclasses generated from the upstream ACP schema (`acp.schema`)
8
+
- Async agent base class and stdio helpers to spin up an agent in a few lines
9
+
- Examples that demonstrate streaming updates and tool execution over ACP
10
10
11
-
## Minimal usage
11
+
## Getting started
12
12
13
-
```python
14
-
import asyncio
13
+
1. Install the package:
14
+
```bash
15
+
pip install agent-client-protocol
16
+
```
17
+
2. Launch the provided echo agent to verify your setup:
18
+
```bash
19
+
python examples/echo_agent.py
20
+
```
21
+
3. Point your ACP-capable client at the running process (for Zed, configure an Agent Server entry). The SDK takes care of JSON-RPC framing and lifecycle transitions.
15
22
16
-
from acp import (
17
-
Agent,
18
-
AgentSideConnection,
19
-
InitializeRequest,
20
-
InitializeResponse,
21
-
NewSessionRequest,
22
-
NewSessionResponse,
23
-
PromptRequest,
24
-
PromptResponse,
25
-
SessionNotification,
26
-
stdio_streams,
27
-
)
28
-
from acp.schema import TextContentBlock, AgentMessageChunk
23
+
Prefer a guided tour? Head to the [Quickstart](quickstart.md) for step-by-step instructions, including how to run the agent from an editor or terminal.
29
24
25
+
## Documentation map
30
26
31
-
classEchoAgent(Agent):
32
-
def__init__(self, conn):
33
-
self._conn = conn
27
+
-[Quickstart](quickstart.md): install, run, and extend the echo agent
28
+
-[Mini SWE Agent guide](mini-swe-agent.md): bridge mini-swe-agent over ACP, including duet launcher and Textual client
- Mini SWE Agent example: [mini-swe-agent.md](mini-swe-agent.md)
30
+
Source code lives under `src/acp/`, while tests and additional examples are available in `tests/` and `examples/`. If you plan to contribute, see the repository README for the development workflow.
> Just a show of the bridge in action. Not a best-effort or absolutely-correct implementation of the agent.
3
+
This example wraps mini-swe-agent behind ACP so editors such as Zed can interact with it over stdio. A duet launcher is included to run a local Textual client beside the bridge for quick experimentation.
4
4
5
-
This example wraps mini-swe-agent behind ACP so Zed can run it as an external agent over stdio. It also includes a local Textual UI client connected via a duet launcher
5
+
## Overview
6
6
7
-
## Behavior
7
+
- Accepts ACP prompts, concatenates text blocks, and forwards them to mini-swe-agent
8
+
- Streams language-model output via `session/update` → `agent_message_chunk`
9
+
- Emits `tool_call` / `tool_call_update` pairs for shell execution, including stdout and return codes
10
+
- Sends a final `agent_message_chunk` when mini-swe-agent prints `COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`
8
11
9
-
- Prompts: text blocks are concatenated into a single task string. (Resource embedding is not used in this example.)
10
-
- Streaming: only LM output is streamed via `session/update` → `agent_message_chunk`.
11
-
- Tool calls: when the agent executes a shell command, the bridge sends:
12
-
-`tool_call` with `kind=execute`, pending status, and a bash code block containing the command
13
-
-`tool_call_update` upon completion, including output and a `rawOutput` object with `output` and `returncode`
14
-
- Final result: on task submission (mini-swe-agent prints `COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the first line), a final `agent_message_chunk` with the submission content is sent.
12
+
## Requirements
15
13
16
-
## Configuration
14
+
- Python environment with `mini-swe-agent` installed (`pip install mini-swe-agent`)
15
+
- ACP-capable client (e.g. Zed) or the bundled Textual client
16
+
- Optional: `.env` file at the repo root for shared configuration when using the duet launcher
17
17
18
-
Environment variables control the model:
18
+
If `mini-swe-agent` is missing, the bridge falls back to the reference copy at `reference/mini-swe-agent/src`.
19
19
20
-
-`MINI_SWE_MODEL`: model ID (e.g. `openrouter/openai/gpt-4o-mini`)
21
-
-`OPENROUTER_API_KEY` for OpenRouter; or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` for native providers
22
-
- Optional `MINI_SWE_MODEL_KWARGS`: JSON, e.g. `{ "api_base": "https://openrouter.ai/api/v1" }` (auto-injected for OpenRouter if missing)
20
+
## Configure models and credentials
23
21
24
-
Agent behavior automatically maps the appropriate API key based on the chosen model and available environment variables.
22
+
Set environment variables before launching the bridge:
25
23
26
-
If `mini-swe-agent` is not installed in the venv, the bridge attempts to import a vendored reference copy under `reference/mini-swe-agent/src`.
24
+
-`MINI_SWE_MODEL`: model identifier such as `openrouter/openai/gpt-4o-mini`
25
+
-`OPENROUTER_API_KEY` for OpenRouter models, or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` for native providers
26
+
- Optional `MINI_SWE_MODEL_KWARGS`: JSON blob of extra keyword arguments (OpenRouter defaults are injected automatically when omitted)
27
27
28
-
## How to run
28
+
The bridge selects the correct API key based on the chosen model and available variables.
29
29
30
-
- In Zed (editor integration): configure an agent server to launch `examples/mini_swe_agent/agent.py` and set the environment variables there. Use Zed’s “Open ACP Logs” to inspect `tool_call`/`tool_call_update` and message chunks.
31
-
- In terminal (local TUI): run the duet launcher to start both the agent and the Textual client with the same environment and dedicated pipes:
30
+
## Run inside Zed
31
+
32
+
Add an Agent Server entry targeting `examples/mini_swe_agent/agent.py` and provide the environment variables there. Use Zed’s “Open ACP Logs” panel to observe streamed message chunks and tool call events in real time.
33
+
34
+
## Run locally with the duet launcher
35
+
36
+
To pair the bridge with the Textual TUI client, run:
32
37
33
38
```bash
34
39
python examples/mini_swe_agent/duet.py
35
40
```
36
41
37
-
The launcher loads `.env` from the repo root (using python-dotenv) so both processes share the same configuration.
38
-
39
-
### TUI usage
42
+
Both processes inherit settings from `.env` (thanks to `python-dotenv`) and communicate over dedicated pipes.
0 commit comments