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
The package code lives under `src/acp`, exposing the high-level Agent, transport helpers, and generated protocol schema. Generated artifacts such as `schema/` and `src/acp/schema.py` are refreshed via `scripts/gen_all.py` against the upstream ACP schema. Integration examples are in `examples/`, including `echo_agent.py` and the mini SWE bridge. Tests reside in `tests/` with async fixtures and doctests; documentation sources live in `docs/` and publish via MkDocs. Built distributions drop into `dist/` after builds.
5
+
6
+
## Build, Test, and Development Commands
7
+
Run `make install` to create a `uv` managed virtualenv and install pre-commit hooks. `make check` executes lock verification, Ruff linting, `ty` static checks, and deptry analysis. `make test` calls `uv run python -m pytest --doctest-modules`. For release prep use `make build` or `make build-and-publish`. `make gen-all` regenerates protocol models; export `ACP_SCHEMA_VERSION=<ref>` beforehand to fetch a specific upstream schema (defaults to the cached copy). `make docs` serves MkDocs locally; `make docs-test` ensures clean builds.
8
+
9
+
## Coding Style & Naming Conventions
10
+
Target Python 3.10+ with type hints and 120-character lines enforced by Ruff (`pyproject.toml`). Prefer dataclasses/pydantic models from the schema modules rather than bare dicts. Tests may ignore security lint (see per-file ignores) but still follow snake_case names. Keep public API modules under `acp/*` lean; place utilities in internal `_`-prefixed modules when needed.
11
+
12
+
## Testing Guidelines
13
+
Pytest is the main framework with `pytest-asyncio` for coroutine tests and doctests activated on modules. Name test files `test_*.py` and co-locate fixtures under `tests/conftest.py`. Aim to cover new protocol surfaces with integration-style tests using the async agent stubs. Generate coverage reports via `tox -e py310` when assessing CI parity.
14
+
15
+
## Commit & Pull Request Guidelines
16
+
Commit history follows Conventional Commits (`feat:`, `fix:`, `docs:`). Scope commits narrowly and include context on affected protocol version or tooling. PRs should describe agent behaviors exercised, link related issues, and mention schema regeneration if applicable. Attach test output (`make check` or targeted pytest) and screenshots only when UI-adjacent docs change. Update docs/examples when altering the public agent API.
17
+
18
+
## Agent Integration Tips
19
+
Leverage `examples/mini_swe_agent/` as a template when bridging other command executors. Use `AgentSideConnection` with `stdio_streams()` for ACP-compliant clients; document any extra environment variables in README updates.
- Featured: Listed as the first third-party SDK on the official ACP site — see https://agentclientprotocol.com/libraries/community
5
+
> Each release tracks the matching ACP schema version. Contributions that improve coverage or tooling are very welcome.
6
+
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
9
12
10
13
## Install
11
14
12
15
```bash
13
16
pip install agent-client-protocol
14
-
# or
17
+
# or with uv
15
18
uv add agent-client-protocol
16
19
```
17
20
18
-
## Development (contributors)
21
+
## Quickstart
19
22
20
-
```bash
21
-
make install # set up venv
22
-
make check # lint + typecheck
23
-
make test# run tests
24
-
```
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.
25
29
26
-
## 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/.
27
31
28
-
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
29
33
30
34
```python
31
35
import asyncio
32
36
33
-
from acp import (
34
-
Agent,
35
-
AgentSideConnection,
36
-
InitializeRequest,
37
-
InitializeResponse,
38
-
NewSessionRequest,
39
-
NewSessionResponse,
40
-
PromptRequest,
41
-
PromptResponse,
42
-
SessionNotification,
43
-
stdio_streams,
44
-
)
45
-
from acp.schema import ContentBlock1, SessionUpdate2
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 ContentBlock1, SessionUpdate2
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