# Quickstart
Spin up a working ACP agent/client loop in minutes. Keep this page beside the terminal and check off each section as you go. Want inspiration? Hop to the [Use Cases](use-cases.md) list to see how teams like kimi-cli or Zed apply the SDK in production.
## Quick checklist
| Goal | Command / Link |
| ----------------------------------- | --------------------------------------------------------------------- |
| Install the SDK | `pip install agent-client-protocol` or `uv add agent-client-protocol` |
| Run the echo agent | `python examples/echo_agent.py` |
| Point Zed (or another client) at it | Update `settings.json` as shown below |
| Programmatically drive an agent | Copy the `spawn_agent_process` example |
| Run tests before hacking further | `make check && make test` |
## Before you begin
- Python 3.103.14 with `pip` or `uv`
- An ACP-capable client such as Zed (recommended for validation)
- Optional: the Gemini CLI (`gemini --acp`; use `--experimental-acp` for older versions) for the bridge example
## Step 1 Install the SDK
_Install the library from PyPI or add it to your uv workspace._
```bash
pip install agent-client-protocol
# or
uv add agent-client-protocol
```
## Step 2 Launch the Echo agent
_Run the provided streaming agent so clients have something to talk to._
Start the ready-made echo example; it streams text blocks back to any ACP client. Leave it running in a terminal:
```bash
python examples/echo_agent.py
```
## Step 3 Connect from an ACP-aware client
_Point a client at the script and confirm you can exchange streamed updates._
### Zed
Add an Agent Server entry in `settings.json` (Zed Settings Agents panel):
```json
{
"agent_servers": {
"Echo Agent (Python)": {
"type": "custom",
"command": "/abs/path/to/python",
"args": [
"/abs/path/to/agentclientprotocol/python-sdk/examples/echo_agent.py"
]
}
}
}
```
Or, if using `uv`:
```json
{
"agent_servers": {
"Echo Agent (Python)": {
"type": "custom",
"command": "uv",
"args": [
"run",
"/abs/path/to/agentclientprotocol/python-sdk/examples/echo_agent.py"
]
}
}
}
```
Open the Agents panel and start the session. Each message you send should be echoed back via streamed `session/update` notifications.
### Other clients
Any ACP client that communicates over stdio can spawn the same script; no additional transport configuration is required.
### Programmatic launch
Prefer to drive agents directly from Python? The `spawn_agent_process` helper wires stdio and lifecycle management for you:
```python
import asyncio
import sys
from pathlib import Path
from typing import Any
from acp import PROTOCOL_VERSION, spawn_agent_process, text_block
from acp.interfaces import Client
class SimpleClient(Client):
async def request_permission(
self, session_id, tool_call, options, **kwargs: Any
):
return {"outcome": {"outcome": "cancelled"}}
async def session_update(self, session_id, update, **kwargs):
print("update:", session_id, update)
async def main() -> None:
script = Path("examples/echo_agent.py")
async with spawn_agent_process(SimpleClient(), sys.executable, str(script)) as (conn, _proc):
await conn.initialize(protocol_version=PROTOCOL_VERSION)
session = await conn.new_session(cwd=str(script.parent), mcp_servers=[])
await conn.prompt(
session_id=session.session_id,
prompt=[text_block("Hello from spawn!")],
)
asyncio.run(main())
```
`spawn_agent_process` manages the child process, wires its stdio into ACP framing, and closes everything when the block exits. The mirror helper `spawn_client_process` lets you drive an ACP client from Python as well.
## Step 4 Extend the agent
_Swap the echo demo for your own `Agent` subclass._
Create your own agent by subclassing `acp.Agent`. The pattern mirrors the echo example:
```python
from acp import Agent, PromptResponse
class MyAgent(Agent):
async def prompt(self, session_id, prompt, **kwargs) -> PromptResponse:
# inspect prompt, stream updates, then finish the turn
return PromptResponse(stop_reason="end_turn")
```
Run it with `run_agent()` inside an async entrypoint and wire it to your client. Refer to:
- [`examples/echo_agent.py`](https://github.com/agentclientprotocol/python-sdk/blob/main/examples/echo_agent.py) for the smallest streaming agent
- [`examples/agent.py`](https://github.com/agentclientprotocol/python-sdk/blob/main/examples/agent.py) for an implementation that negotiates capabilities and streams richer updates
- [`examples/duet.py`](https://github.com/agentclientprotocol/python-sdk/blob/main/examples/duet.py) to see `spawn_agent_process` in action alongside the interactive client
- [`examples/gemini.py`](https://github.com/agentclientprotocol/python-sdk/blob/main/examples/gemini.py) to drive the Gemini CLI (`--acp`; use `--experimental-acp` for older versions) directly from Python
Need builders for common payloads? `acp.helpers` mirrors the Go/TS helper APIs:
```python
from acp import start_tool_call, update_tool_call, text_block, tool_content
start_update = start_tool_call("call-42", "Open file", kind="read", status="pending")
finish_update = update_tool_call(
"call-42",
status="completed",
content=[tool_content(text_block("File opened."))],
)
```
Each helper wraps the generated Pydantic models in `acp.schema`, so the right discriminator fields (`type`, `sessionUpdate`, and friends) are always populated. That keeps examples readable while maintaining the same validation guarantees as constructing the models directly. Golden fixtures in `tests/test_golden.py` ensure the helpers stay in sync with future schema revisions.
## Optional Talk to the Gemini CLI
_Have the Gemini CLI installed? Run the bridge to exercise permission flows._
If you have the Gemini CLI installed and authenticated:
```bash
python examples/gemini.py --skip-trust --yolo # auto-approve permission prompts
python examples/gemini.py --skip-trust --sandbox --model gemini-1.5-pro
```
Environment helpers:
- `ACP_GEMINI_BIN` override the CLI path (defaults to `PATH` lookup)
- `ACP_GEMINI_TEST_ARGS` extra flags forwarded during the smoke test
- `ACP_ENABLE_GEMINI_TESTS=1` opt-in toggle for `tests/test_gemini_example.py`
Authentication hiccups (e.g. missing `GOOGLE_CLOUD_PROJECT`) are surfaced but treated as skips during testing so the suite stays green on machines without credentials.
## Next steps
- Compare what you built with the real integrations listed on the [Use Cases](use-cases.md) page.
- Explore `docs/contrib.md` for higher-level utilities like session accumulators and permission brokers.
- Run `make check` / `make test` before committing changes, and regenerate schema artifacts with `make gen-all` when ACP versions advance.
- Need help? Start a thread in [GitHub Discussions](https://github.com/agentclientprotocol/python-sdk/discussions) or chat with other ACP developers at [agentclientprotocol.zulipchat.com](https://agentclientprotocol.zulipchat.com/).