docs: polish docs for next release

Signed-off-by: Chojan Shang <chojan.shang@vesoft.com>

Author: Chojan Shang

README.md

@@ -6,9 +6,10 @@ Python SDK for the Agent Client Protocol (ACP). Build agents that speak ACP over
 
 **Highlights**
 
-- Typed dataclasses generated from the upstream ACP schema (`acp.schema`)
-- Async agent base class plus stdio transport helpers for quick bootstrapping
-- Included examples that stream content updates and tool calls end-to-end
+- Generated `pydantic` models that track the upstream ACP schema (`acp.schema`)
+- Async base classes and JSON-RPC plumbing that keep stdio agents tiny
+- Process helpers such as `spawn_agent_process` for embedding agents and clients directly in Python
+- Batteries-included examples that exercise streaming updates, file I/O, and permission flows
 
 ## Install
 
@@ -29,6 +30,37 @@ uv add agent-client-protocol
 
 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/.
 
+### Launching from Python
+
+Embed the agent inside another Python process without spawning your own pipes:
+
+```python
+import asyncio
+import sys
+from pathlib import Path
+
+from acp import spawn_agent_process
+from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, TextContentBlock
+
+
+async def main() -> None:
+    agent_script = Path("examples/echo_agent.py")
+    async with spawn_agent_process(lambda _agent: YourClient(), sys.executable, str(agent_script)) as (conn, _proc):
+        await conn.initialize(InitializeRequest(protocolVersion=1))
+        session = await conn.newSession(NewSessionRequest(cwd=str(agent_script.parent), mcpServers=[]))
+        await conn.prompt(
+            PromptRequest(
+                sessionId=session.sessionId,
+                prompt=[TextContentBlock(type="text", text="Hello!")],
+            )
+        )
+
+
+asyncio.run(main())
+```
+
+`spawn_client_process` mirrors this pattern for the inverse direction.
+
 ### Minimal agent sketch
 
 ```python
@@ -71,9 +103,10 @@ Full example with streaming and lifecycle hooks lives in [examples/echo_agent.py
 
 ## Examples
 
-- `examples/echo_agent.py`: self-contained streaming agent suitable for smoke tests
-- `examples/client.py`: interactive console client that can spawn any ACP agent subprocess
-- `examples/duet.py`: demo launcher that starts both the example client and agent together
+- `examples/echo_agent.py`: the canonical streaming agent with lifecycle hooks
+- `examples/client.py`: interactive console client that can launch any ACP agent via stdio
+- `examples/agent.py`: richer agent showcasing initialization, authentication, and chunked updates
+- `examples/duet.py`: launches both example agent and client using `spawn_agent_process`
 
 ## Documentation
 

docs/index.md

@@ -4,9 +4,10 @@ Welcome to the Python SDK for the Agent Client Protocol (ACP). The package ships
 
 ## What you get
 
-- Fully typed dataclasses generated from the upstream ACP schema (`acp.schema`)
-- Async agent base class and stdio helpers to spin up an agent in a few lines
-- Examples that demonstrate streaming updates and tool execution over ACP
+- Pydantic models generated from the upstream ACP schema (`acp.schema`)
+- Async agent/client wrappers with JSON-RPC task supervision built in
+- Process helpers (`spawn_agent_process`, `spawn_client_process`) for embedding ACP nodes inside Python applications
+- Examples that showcase streaming updates, file operations, and permission flows
 
 ## Getting started
 
@@ -20,10 +21,10 @@ Welcome to the Python SDK for the Agent Client Protocol (ACP). The package ships
    ```
 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.
 
-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.
+Prefer a guided tour? Head to the [Quickstart](quickstart.md) for terminal, editor, and programmatic launch walkthroughs.
 
 ## Documentation map
 
-- [Quickstart](quickstart.md): install, run, and extend the echo agent
+- [Quickstart](quickstart.md): install, run, and embed the echo agent, plus next steps for extending it
 
 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.

docs/quickstart.md

@@ -15,17 +15,17 @@ pip install agent-client-protocol
 uv add agent-client-protocol
 ```
 
-## 2. Run the echo agent
+## 2. Launch the Echo agent (terminal)
 
-Launch the ready-made echo example, which streams text blocks back over ACP:
+Start the ready-made echo example — it streams text blocks back to any ACP client:
 
 ```bash
 python examples/echo_agent.py
 ```
 
-Keep it running while you connect your client.
+Leave this process running while you connect from an editor or another program.
 
-## 3. Connect from your client
+## 3. Connect from an editor
 
 ### Zed
 
@@ -52,45 +52,27 @@ Any ACP client that communicates over stdio can spawn the same script; no additi
 
 ### Programmatic launch
 
-You can also embed the agent inside another Python process without shelling out manually. Use
-`acp.spawn_agent_process` to bootstrap the child and receive a `ClientSideConnection`:
-
 ```python
 import asyncio
 import sys
 from pathlib import Path
 
 from acp import spawn_agent_process
 from acp.interfaces import Client
-from acp.schema import (
-    DeniedOutcome,
-    InitializeRequest,
-    NewSessionRequest,
-    PromptRequest,
-    RequestPermissionRequest,
-    RequestPermissionResponse,
-    SessionNotification,
-    TextContentBlock,
-)
+from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, SessionNotification, TextContentBlock
 
 
 class SimpleClient(Client):
-    async def requestPermission(self, params: RequestPermissionRequest) -> RequestPermissionResponse:
-        return RequestPermissionResponse(outcome=DeniedOutcome(outcome="cancelled"))
-
-    async def sessionUpdate(self, params: SessionNotification) -> None:  # noqa: D401 - logging only
-        print("update:", params)
+    async def requestPermission(self, params):  # pragma: no cover - minimal stub
+        return {"outcome": {"outcome": "cancelled"}}
 
-    # Optional client methods omitted for brevity
+    async def sessionUpdate(self, params: SessionNotification) -> None:
+        print("update:", params.sessionId, params.update)
 
 
 async def main() -> None:
-    script = Path("examples/echo_agent.py").resolve()
-
-    async with spawn_agent_process(lambda agent: SimpleClient(), sys.executable, str(script)) as (
-        conn,
-        _process,
-    ):
+    script = Path("examples/echo_agent.py")
+    async with spawn_agent_process(lambda _agent: SimpleClient(), sys.executable, str(script)) as (conn, _proc):
         await conn.initialize(InitializeRequest(protocolVersion=1))
         session = await conn.newSession(NewSessionRequest(cwd=str(script.parent), mcpServers=[]))
         await conn.prompt(
@@ -103,8 +85,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Inside the context manager the subprocess is monitored, stdin/stdout are tied into ACP, and the
-connection cleans itself up on exit.
+`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.
 
 ## 4. Extend the agent
 
@@ -120,4 +101,8 @@ class MyAgent(Agent):
         return PromptResponse(stopReason="end_turn")
 ```
 
-Hook it up with `AgentSideConnection` inside an async entrypoint and wire it to your client. Refer to [examples/echo_agent.py](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/echo_agent.py) for the complete structure, including lifetime hooks (`initialize`, `newSession`) and streaming responses.
+Hook it up with `AgentSideConnection` inside an async entrypoint and wire it to your client. Refer to:
+
+- [`examples/echo_agent.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/echo_agent.py) for the smallest streaming agent
+- [`examples/agent.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/agent.py) for an implementation that negotiates capabilities and streams richer updates
+- [`examples/duet.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/duet.py) to see `spawn_agent_process` in action alongside the interactive client