docs: polish docs

Author: PsiACE

README.md

@@ -1,52 +1,70 @@
-# Agent Client Protocol - Python SDK
+# Agent Client Protocol (Python)
 
-A Python implementation of the Agent Client Protocol (ACP) used by editors like Zed to talk to external agents over stdio.
+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.
 
+- Package name: `agent-client-protocol` (import as `acp`)
 - Repository: https://github.com/psiace/agent-client-protocol-python
 - Docs: https://psiace.github.io/agent-client-protocol-python/
 
-## What this provides
-
-- Typed ACP client/agent primitives (`acp` package under `src/`)
-- A runnable example: a bridge that wraps mini-swe-agent as an ACP agent
-- Reference implementations under `reference/` for learning and comparison
-
-## Quick start
-
-Install the development environment:
+## Install
 
 ```bash
-make install
+pip install agent-client-protocol
+# or
+uv add agent-client-protocol
 ```
 
-Run quality checks:
+## Development (contributors)
 
 ```bash
-make check
+make install   # set up venv
+make check     # lint + typecheck
+make test      # run tests
 ```
 
-Run tests:
+## Minimal agent example
 
-```bash
-make test
+```python
+# agent_main.py
+import asyncio
+from acp import Agent, AgentSideConnection, Client, InitializeRequest, InitializeResponse, PromptRequest, PromptResponse, SessionNotification, stdio_streams, PROTOCOL_VERSION
+from acp.schema import ContentBlock1, SessionUpdate2
+
+class EchoAgent(Agent):
+    def __init__(self, client: Client) -> None:
+        self.client = client
+
+    async def initialize(self, _p: InitializeRequest) -> InitializeResponse:
+        return InitializeResponse(protocolVersion=PROTOCOL_VERSION)
+
+    async def prompt(self, p: PromptRequest) -> PromptResponse:
+        text = "".join([getattr(b, "text", "") for b in p.prompt if getattr(b, "type", None) == "text"]) or "(empty)"
+        await self.client.sessionUpdate(SessionNotification(
+            sessionId=p.sessionId,
+            update=SessionUpdate2(sessionUpdate="agent_message_chunk", content=ContentBlock1(type="text", text=f"Echo: {text}")),
+        ))
+        return PromptResponse(stopReason="end_turn")
+
+async def main() -> None:
+    reader, writer = await stdio_streams()
+    AgentSideConnection(lambda c: EchoAgent(c), writer, reader)
+    await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
-## Example: Mini SWE Agent bridge
+Run this executable from your ACP-capable client (e.g. configure Zed to launch it). The library takes care of the stdio JSON-RPC transport.
 
-A minimal ACP bridge for mini-swe-agent is provided under [`examples/mini_swe_agent`](file:///Users/psiace/OSS/agent-client-protocol-python/examples/mini_swe_agent/README.md). It shows how to:
+## Example: Mini SWE Agent bridge
 
-- Parse a prompt from ACP content blocks
-- Stream agent output to the client with `session/update`
-- Map command execution to `tool_call` and `tool_call_update`
+A minimal ACP bridge for mini-swe-agent is provided under [`examples/mini_swe_agent`](examples/mini_swe_agent/README.md). It demonstrates:
 
-See the example’s README or the docs quickstart for Zed configuration.
+- Parsing a prompt from ACP content blocks
+- Streaming agent output via `session/update`
+- Mapping command execution to `tool_call` and `tool_call_update`
 
 ## Documentation
 
-- Getting started: [docs/index.md](docs/index.md)
 - Quickstart: [docs/quickstart.md](docs/quickstart.md)
-- Mini SWE Agent example details: [docs/mini-swe-agent.md](docs/mini-swe-agent.md)
-
-## Notes
-
-- The `reference/` directory contains educational examples and may include optional dependencies. These are not required to use the example bridge.
+- Mini SWE Agent example: [docs/mini-swe-agent.md](docs/mini-swe-agent.md)

docs/index.md

@@ -1,6 +1,31 @@
-# Agent Client Protocol - Python SDK
+# Agent Client Protocol (Python)
 
-A Python implementation of the Agent Client Protocol (ACP) used by editors like Zed to talk to external agents over stdio.
+A Python implementation of the Agent Client Protocol (ACP). Build agents that communicate with ACP-capable clients (e.g. Zed) over stdio.
+
+## Install
+
+```bash
+pip install agent-client-protocol
+```
+
+## Minimal usage
+
+```python
+from acp import Agent, AgentSideConnection, Client, stdio_streams, PROTOCOL_VERSION, InitializeRequest, InitializeResponse, PromptRequest, PromptResponse
+from acp.schema import ContentBlock1, SessionUpdate2, SessionNotification
+
+class MyAgent(Agent):
+    def __init__(self, client: Client):
+        self.client = client
+    async def initialize(self, _p: InitializeRequest) -> InitializeResponse:
+        return InitializeResponse(protocolVersion=PROTOCOL_VERSION)
+    async def prompt(self, p: PromptRequest) -> PromptResponse:
+        await self.client.sessionUpdate(SessionNotification(
+            sessionId=p.sessionId,
+            update=SessionUpdate2(sessionUpdate="agent_message_chunk", content=ContentBlock1(type="text", text="Hello from ACP")),
+        ))
+        return PromptResponse(stopReason="end_turn")
+```
 
 - Quickstart: [quickstart.md](quickstart.md)
 - Mini SWE Agent example: [mini-swe-agent.md](mini-swe-agent.md)

docs/quickstart.md

@@ -1,31 +1,49 @@
 # Quickstart
 
-This repository provides a Python implementation of the Agent Client Protocol (ACP) and a minimal example that bridges mini-swe-agent into an ACP agent.
+Use the published package to build an ACP agent, or run the included example.
 
-## Prerequisites
-
-- Python 3.10+
-- A virtual environment for this repo (`make install` will create one with uv)
-- Zed editor (for running the example agent)
-
-## Install
+## Install the SDK
 
 ```bash
-make install
+pip install agent-client-protocol
 ```
 
-Run checks:
+## Minimal agent
 
-```bash
-make check
+```python
+import asyncio
+from acp import Agent, AgentSideConnection, Client, InitializeRequest, InitializeResponse, PromptRequest, PromptResponse, SessionNotification, stdio_streams, PROTOCOL_VERSION
+from acp.schema import ContentBlock1, SessionUpdate2
+
+class EchoAgent(Agent):
+    def __init__(self, client: Client):
+        self.client = client
+    async def initialize(self, _p: InitializeRequest) -> InitializeResponse:
+        return InitializeResponse(protocolVersion=PROTOCOL_VERSION)
+    async def prompt(self, p: PromptRequest) -> PromptResponse:
+        await self.client.sessionUpdate(SessionNotification(
+            sessionId=p.sessionId,
+            update=SessionUpdate2(sessionUpdate="agent_message_chunk", content=ContentBlock1(type="text", text="Hello from ACP")),
+        ))
+        return PromptResponse(stopReason="end_turn")
+
+async def main() -> None:
+    reader, writer = await stdio_streams()
+    AgentSideConnection(lambda c: EchoAgent(c), writer, reader)
+    await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
+Run this program from your ACP-capable client.
+
 ## Run the Mini SWE Agent bridge in Zed
 
-Install mini-swe-agent into this repo’s venv.
+Install `mini-swe-agent` (or at least its core dependencies) into the same environment that will run the example:
 
 ```bash
-./.venv/bin/pip install mini-swe-agent
+pip install mini-swe-agent
 ```
 
 Add an agent server to Zed’s `settings.json`:
@@ -34,12 +52,11 @@ Add an agent server to Zed’s `settings.json`:
 {
   "agent_servers": {
     "Mini SWE Agent (Python)": {
-      "command": "/absolute/path/to/agent-client-protocol-python/.venv/bin/python",
+      "command": "/abs/path/to/python",
       "args": [
-        "/absolute/path/to/agent-client-protocol-python/examples/mini_swe_agent/agent.py"
+        "/abs/path/to/agent-client-protocol-python/examples/mini_swe_agent/agent.py"
       ],
       "env": {
-        "PYTHONPATH": "/absolute/path/to/agent-client-protocol-python/src",
         "MINI_SWE_MODEL": "openrouter/openai/gpt-4o-mini",
         "MINI_SWE_MODEL_KWARGS": "{\"api_base\":\"https://openrouter.ai/api/v1\"}",
         "OPENROUTER_API_KEY": "sk-or-..."
@@ -51,4 +68,4 @@ Add an agent server to Zed’s `settings.json`:
 
 In Zed, open the Agents panel and select "Mini SWE Agent (Python)".
 
-For details on behavior and message mapping, see [mini-swe-agent.md](mini-swe-agent.md).
+See [mini-swe-agent.md](mini-swe-agent.md) for behavior and message mapping details.

examples/mini_swe_agent/README.md

@@ -2,20 +2,19 @@
 
 A minimal Agent Client Protocol (ACP) bridge that wraps mini-swe-agent so it can be run by Zed as an external agent over stdio.
 
-## Configure in Zed (using this repo’s venv)
+## Configure in Zed
 
-Add an `agent_servers` entry to Zed’s `settings.json`. Point `command` to this repo’s venv Python and `args` to this example script:
+Add an `agent_servers` entry to Zed’s `settings.json`. Point `command` to the Python interpreter that has both `agent-client-protocol` and `mini-swe-agent` installed, and `args` to this example script:
 
 ```json
 {
   "agent_servers": {
     "Mini SWE Agent (Python)": {
-      "command": "/absolute/path/to/agent-client-protocol-python/.venv/bin/python",
+      "command": "/abs/path/to/python",
       "args": [
-        "/absolute/path/to/agent-client-protocol-python/examples/mini_swe_agent/agent.py"
+        "/abs/path/to/agent-client-protocol-python/examples/mini_swe_agent/agent.py"
       ],
       "env": {
-        "PYTHONPATH": "/absolute/path/to/agent-client-protocol-python/src",
         "MINI_SWE_MODEL": "openrouter/openai/gpt-4o-mini",
         "MINI_SWE_MODEL_KWARGS": "{\"api_base\":\"https://openrouter.ai/api/v1\"}",
         "OPENROUTER_API_KEY": "sk-or-..."
@@ -26,9 +25,7 @@ Add an `agent_servers` entry to Zed’s `settings.json`. Point `command` to this
 ```
 
 Notes
-- `command` must be the absolute path to this repository’s venv Python.
-- `args` must point to this example script.
-- `PYTHONPATH` must point to this repository’s `src` so the `acp` package can be imported.
+- If you install `agent-client-protocol` from PyPI, you do not need to set `PYTHONPATH`.
 - Using OpenRouter:
   - Set `MINI_SWE_MODEL` to a model supported by OpenRouter (e.g. `openrouter/openai/gpt-4o-mini`, `openrouter/anthropic/claude-3.5-sonnet`).
   - Set `MINI_SWE_MODEL_KWARGS` to a JSON containing `api_base`: `{ "api_base": "https://openrouter.ai/api/v1" }`.
@@ -37,10 +34,10 @@ Notes
 
 ## Requirements
 
-Install mini-swe-agent (or at least its core deps) into this repo’s venv:
+Install mini-swe-agent (or at least its core deps) into the same environment:
 
 ```bash
-/path/to/.venv/bin/pip install mini-swe-agent
+pip install agent-client-protocol mini-swe-agent
 # or: pip install litellm jinja2 tenacity
 ```