feat: intro helpers

Chojan Shang · Chojan Shang · commit c898f59f23d3 · 2025-10-13T23:16:09.000+08:00
Signed-off-by: Chojan Shang &lt;chojan.shang@vesoft.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,6 +17,7 @@
 - Target Python 3.10+ with four-space indentation and type hints on public APIs.
 - Ruff enforces formatting and lint rules (`uv run ruff check`, `uv run ruff format`); keep both clean before publishing.
 - Prefer dataclasses or generated Pydantic models from `acp.schema` over ad-hoc dicts. Place shared utilities in `_`-prefixed internal modules.
+- When constructing ACP payloads, use the builders in `acp.helpers` (for example `text_block`, `start_tool_call`). These helpers keep the generated Pydantic models authoritative while hiding required literal fields, and the golden tests (`tests/test_golden.py`) ensure they always match the schema.
 
 ## Testing Guidelines
 - Tests live in `tests/` and must be named `test_*.py`. Use `pytest.mark.asyncio` for coroutine coverage.
diff --git a/README.md b/README.md
@@ -44,8 +44,8 @@ import asyncio
 import sys
 from pathlib import Path
 
-from acp import spawn_agent_process
-from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, TextContentBlock
+from acp import spawn_agent_process, text_block
+from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest
 
 
 async def main() -> None:
@@ -56,7 +56,7 @@ async def main() -> None:
         await conn.prompt(
             PromptRequest(
                 sessionId=session.sessionId,
-                prompt=[TextContentBlock(type="text", text="Hello!")],
+                prompt=[text_block("Hello!")],
             )
         )
 
@@ -80,10 +80,11 @@ from acp import (
     NewSessionResponse,
     PromptRequest,
     PromptResponse,
-    SessionNotification,
+    session_notification,
     stdio_streams,
+    text_block,
+    update_agent_message,
 )
-from acp.schema import TextContentBlock, AgentMessageChunk
 
 
 class EchoAgent(Agent):
@@ -100,12 +101,9 @@ class EchoAgent(Agent):
         for block in params.prompt:
             text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
             await self._conn.sessionUpdate(
-                SessionNotification(
-                    sessionId=params.sessionId,
-                    update=AgentMessageChunk(
-                        sessionUpdate="agent_message_chunk",
-                        content=TextContentBlock(type="text", text=text),
-                    ),
+                session_notification(
+                    params.sessionId,
+                    update_agent_message(text_block(text)),
                 )
             )
         return PromptResponse(stopReason="end_turn")
@@ -131,6 +129,23 @@ Full example with streaming and lifecycle hooks lives in [examples/echo_agent.py
 - `examples/duet.py`: launches both example agent and client using `spawn_agent_process`
 - `examples/gemini.py`: connects to the Gemini CLI in `--experimental-acp` mode, with optional auto-approval and sandbox flags
 
+## Helper APIs
+
+Use `acp.helpers` to build protocol payloads without manually shaping dictionaries:
+
+```python
+from acp import start_tool_call, text_block, tool_content, update_tool_call
+
+start = start_tool_call("call-1", "Inspect config", kind="read", status="pending")
+update = update_tool_call(
+    "call-1",
+    status="completed",
+    content=[tool_content(text_block("Inspection finished."))],
+)
+```
+
+Helpers cover content blocks (`text_block`, `resource_link_block`), embedded resources, tool calls (`start_edit_tool_call`, `update_tool_call`), and session updates (`update_agent_message_text`, `session_notification`).
+
 ## Documentation
 
 - Project docs (MkDocs): https://psiace.github.io/agent-client-protocol-python/
diff --git a/docs/index.md b/docs/index.md
@@ -11,6 +11,7 @@ Welcome to the Python SDK for the Agent Client Protocol (ACP). The package ships
 - 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
+- Helper APIs in `acp.helpers` that mirror the Go/TS SDK builders for content blocks, tool calls, and session updates
 - Examples that showcase streaming updates, file operations, permission flows, and even a Gemini CLI bridge (`examples/gemini.py`)
 
 ## Getting started
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -57,9 +57,9 @@ import asyncio
 import sys
 from pathlib import Path
 
-from acp import spawn_agent_process
+from acp import spawn_agent_process, text_block
 from acp.interfaces import Client
-from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, SessionNotification, TextContentBlock
+from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, SessionNotification
 
 
 class SimpleClient(Client):
@@ -78,7 +78,7 @@ async def main() -> None:
         await conn.prompt(
             PromptRequest(
                 sessionId=session.sessionId,
-                prompt=[TextContentBlock(type="text", text="Hello from spawn!")],
+                prompt=[text_block("Hello from spawn!")],
             )
         )
 
@@ -108,6 +108,19 @@ Hook it up with `AgentSideConnection` inside an async entrypoint and wire it to
 - [`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
 - [`examples/gemini.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/gemini.py) to drive the Gemini CLI (`--experimental-acp`) 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."))],
+)
+```
+
 ## 5. Optional: Talk to the Gemini CLI
 
 If you have the Gemini CLI installed and authenticated:
diff --git a/examples/agent.py b/examples/agent.py
@@ -18,17 +18,13 @@
     PromptResponse,
     SetSessionModeRequest,
     SetSessionModeResponse,
+    session_notification,
     stdio_streams,
+    text_block,
+    update_agent_message,
     PROTOCOL_VERSION,
 )
-from acp.schema import (
-    AgentCapabilities,
-    AgentMessageChunk,
-    McpCapabilities,
-    PromptCapabilities,
-    SessionNotification,
-    TextContentBlock,
-)
+from acp.schema import AgentCapabilities, McpCapabilities, PromptCapabilities
 
 
 class ExampleAgent(Agent):
@@ -38,12 +34,9 @@ def __init__(self, conn: AgentSideConnection) -> None:
 
     async def _send_chunk(self, session_id: str, content: Any) -> None:
         await self._conn.sessionUpdate(
-            SessionNotification(
-                sessionId=session_id,
-                update=AgentMessageChunk(
-                    sessionUpdate="agent_message_chunk",
-                    content=content,
-                ),
+            session_notification(
+                session_id,
+                update_agent_message(content),
             )
         )
 
@@ -85,7 +78,7 @@ async def prompt(self, params: PromptRequest) -> PromptResponse:
         # Notify the client what it just sent and then echo each content block back.
         await self._send_chunk(
             params.sessionId,
-            TextContentBlock(type="text", text="Client sent:"),
+            text_block("Client sent:"),
         )
         for block in params.prompt:
             await self._send_chunk(params.sessionId, block)
diff --git a/examples/client.py b/examples/client.py
@@ -14,9 +14,9 @@
     PromptRequest,
     RequestError,
     SessionNotification,
+    text_block,
     PROTOCOL_VERSION,
 )
-from acp.schema import TextContentBlock
 
 
 class ExampleClient(Client):
@@ -91,7 +91,7 @@ async def interactive_loop(conn: ClientSideConnection, session_id: str) -> None:
             await conn.prompt(
                 PromptRequest(
                     sessionId=session_id,
-                    prompt=[TextContentBlock(type="text", text=line)],
+                    prompt=[text_block(line)],
                 )
             )
         except Exception as exc:  # noqa: BLE001
diff --git a/examples/echo_agent.py b/examples/echo_agent.py
@@ -10,10 +10,11 @@
     NewSessionResponse,
     PromptRequest,
     PromptResponse,
-    SessionNotification,
+    session_notification,
     stdio_streams,
+    text_block,
+    update_agent_message,
 )
-from acp.schema import AgentMessageChunk, TextContentBlock
 
 
 class EchoAgent(Agent):
@@ -30,12 +31,9 @@ async def prompt(self, params: PromptRequest) -> PromptResponse:
         for block in params.prompt:
             text = getattr(block, "text", "")
             await self._conn.sessionUpdate(
-                SessionNotification(
-                    sessionId=params.sessionId,
-                    update=AgentMessageChunk(
-                        sessionUpdate="agent_message_chunk",
-                        content=TextContentBlock(type="text", text=text),
-                    ),
+                session_notification(
+                    params.sessionId,
+                    update_agent_message(text_block(text)),
                 )
             )
         return PromptResponse(stopReason="end_turn")
diff --git a/examples/gemini.py b/examples/gemini.py
@@ -16,6 +16,7 @@
     ClientSideConnection,
     PROTOCOL_VERSION,
     RequestError,
+    text_block,
 )
 from acp.schema import (
     AgentMessageChunk,
@@ -252,7 +253,7 @@ async def interactive_loop(conn: ClientSideConnection, session_id: str) -> None:
             await conn.prompt(
                 PromptRequest(
                     sessionId=session_id,
-                    prompt=[TextContentBlock(type="text", text=line)],
+                    prompt=[text_block(line)],
                 )
             )
         except RequestError as err:
diff --git a/src/acp/__init__.py b/src/acp/__init__.py
@@ -6,6 +6,31 @@
     RequestError,
     TerminalHandle,
 )
+from .helpers import (
+    audio_block,
+    embedded_blob_resource,
+    embedded_text_resource,
+    image_block,
+    plan_entry,
+    resource_block,
+    resource_link_block,
+    session_notification,
+    start_edit_tool_call,
+    start_read_tool_call,
+    start_tool_call,
+    text_block,
+    tool_content,
+    tool_diff_content,
+    tool_terminal_ref,
+    update_agent_message,
+    update_agent_message_text,
+    update_agent_thought,
+    update_agent_thought_text,
+    update_plan,
+    update_tool_call,
+    update_user_message,
+    update_user_message_text,
+)
 from .meta import (
     AGENT_METHODS,
     CLIENT_METHODS,
@@ -101,4 +126,28 @@
     "spawn_client_process",
     "default_environment",
     "spawn_stdio_transport",
+    # helpers
+    "text_block",
+    "image_block",
+    "audio_block",
+    "resource_link_block",
+    "embedded_text_resource",
+    "embedded_blob_resource",
+    "resource_block",
+    "tool_content",
+    "tool_diff_content",
+    "tool_terminal_ref",
+    "plan_entry",
+    "update_plan",
+    "update_user_message",
+    "update_user_message_text",
+    "update_agent_message",
+    "update_agent_message_text",
+    "update_agent_thought",
+    "update_agent_thought_text",
+    "session_notification",
+    "start_tool_call",
+    "start_read_tool_call",
+    "start_edit_tool_call",
+    "update_tool_call",
 ]
diff --git a/src/acp/helpers.py b/src/acp/helpers.py
diff --git a/tests/test_golden.py b/tests/test_golden.py
diff --git a/tests/test_rpc.py b/tests/test_rpc.py

Original file line number	Diff line number	Diff line change
`@@ -14,9 +14,9 @@`
`14`	`14`	`PromptRequest,`
`15`	`15`	`RequestError,`
`16`	`16`	`SessionNotification,`
	`17`	`+ text_block,`
`17`	`18`	`PROTOCOL_VERSION,`
`18`	`19`	`)`
`19`		`-from acp.schema import TextContentBlock`
`20`	`20`
`21`	`21`
`22`	`22`	`class ExampleClient(Client):`
`@@ -91,7 +91,7 @@ async def interactive_loop(conn: ClientSideConnection, session_id: str) -> None:`
`91`	`91`	`await conn.prompt(`
`92`	`92`	`PromptRequest(`
`93`	`93`	`sessionId=session_id,`
`94`		`- prompt=[TextContentBlock(type="text", text=line)],`
	`94`	`+ prompt=[text_block(line)],`
`95`	`95`	`)`
`96`	`96`	`)`
`97`	`97`	`except Exception as exc: # noqa: BLE001`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@`
`16`	`16`	`ClientSideConnection,`
`17`	`17`	`PROTOCOL_VERSION,`
`18`	`18`	`RequestError,`
	`19`	`+ text_block,`
`19`	`20`	`)`
`20`	`21`	`from acp.schema import (`
`21`	`22`	`AgentMessageChunk,`
`@@ -252,7 +253,7 @@ async def interactive_loop(conn: ClientSideConnection, session_id: str) -> None:`
`252`	`253`	`await conn.prompt(`
`253`	`254`	`PromptRequest(`
`254`	`255`	`sessionId=session_id,`
`255`		`- prompt=[TextContentBlock(type="text", text=line)],`
	`256`	`+ prompt=[text_block(line)],`
`256`	`257`	`)`
`257`	`258`	`)`
`258`	`259`	`except RequestError as err:`