|
| 1 | +# Migrating to ACP Python SDK 0.11 |
| 2 | + |
| 3 | +ACP Python SDK 0.11 updates the generated bindings to `schema-v1.16.0` and aligns the high-level interfaces with the new schema. Most applications only need to update method signatures and review the new unstable capabilities. Agents and clients that already pass keyword arguments are the easiest to migrate. |
| 4 | + |
| 5 | +## 1. Regenerate schema-derived code |
| 6 | + |
| 7 | +If your project vendors ACP schema files, generated models, or protocol metadata, regenerate them against the same upstream schema tag: |
| 8 | + |
| 9 | +```bash |
| 10 | +ACP_SCHEMA_VERSION=schema-v1.16.0 make gen-all |
| 11 | +``` |
| 12 | + |
| 13 | +The SDK package version is `0.11.0`, while the protocol schema tag is `schema-v1.16.0`. |
| 14 | + |
| 15 | +## 2. Update interface method signatures |
| 16 | + |
| 17 | +Several generated request models changed field order or fields. The SDK now exposes those shapes through `Agent` and `Client` protocol methods. Prefer keyword calls when invoking connection helpers; keyword calls are stable across field-order changes. |
| 18 | + |
| 19 | +### Client methods |
| 20 | + |
| 21 | +Update client implementations from the 0.10 positional order: |
| 22 | + |
| 23 | +```python |
| 24 | +async def request_permission(self, options, session_id, tool_call, **kwargs): ... |
| 25 | +async def write_text_file(self, content, path, session_id, **kwargs): ... |
| 26 | +async def read_text_file(self, path, session_id, limit=None, line=None, **kwargs): ... |
| 27 | +async def create_terminal(self, command, session_id, args=None, cwd=None, env=None, **kwargs): ... |
| 28 | +``` |
| 29 | + |
| 30 | +to the 0.11 order: |
| 31 | + |
| 32 | +```python |
| 33 | +async def request_permission(self, session_id, tool_call, options, **kwargs): ... |
| 34 | +async def write_text_file(self, session_id, path, content, **kwargs): ... |
| 35 | +async def read_text_file(self, session_id, path, line=None, limit=None, **kwargs): ... |
| 36 | +async def create_terminal(self, session_id, command, args=None, env=None, cwd=None, **kwargs): ... |
| 37 | +``` |
| 38 | + |
| 39 | +### Agent methods |
| 40 | + |
| 41 | +Update agent implementations from the 0.10 prompt and mode signatures: |
| 42 | + |
| 43 | +```python |
| 44 | +async def set_session_mode(self, mode_id, session_id, **kwargs): ... |
| 45 | +async def prompt(self, prompt, session_id, message_id=None, **kwargs): ... |
| 46 | +``` |
| 47 | + |
| 48 | +to the 0.11 signatures: |
| 49 | + |
| 50 | +```python |
| 51 | +async def set_session_mode(self, session_id, mode_id, **kwargs): ... |
| 52 | +async def prompt(self, session_id, prompt, **kwargs): ... |
| 53 | +``` |
| 54 | + |
| 55 | +The `message_id` field was removed from `PromptRequest`. If your client generated a user message ID before calling `conn.prompt(...)`, stop passing it there. Message IDs now belong to streamed content chunks such as `UserMessageChunk` and `AgentMessageChunk`. |
| 56 | + |
| 57 | +## 3. Remove `session/model` handling |
| 58 | + |
| 59 | +The generated `SetSessionModelRequest` and `SetSessionModelResponse` types are no longer exported, and the `Agent.set_session_model(...)` protocol method is gone. If your agent used this endpoint to switch models, move that behavior into session modes or configuration options exposed through `set_session_mode(...)` and `set_config_option(...)`. |
| 60 | + |
| 61 | +## 4. Handle elicitation if your agent or client advertises it |
| 62 | + |
| 63 | +0.11 adds schema and connection support for the unstable `elicitation/create` request and `elicitation/complete` notification. |
| 64 | + |
| 65 | +Clients that advertise elicitation support should implement: |
| 66 | + |
| 67 | +```python |
| 68 | +from typing import Any |
| 69 | + |
| 70 | +from acp import AcceptElicitationResponse, Client, CreateElicitationResponse, ElicitationMode |
| 71 | + |
| 72 | + |
| 73 | +class MyClient(Client): |
| 74 | + async def create_elicitation( |
| 75 | + self, |
| 76 | + message: str, |
| 77 | + mode: ElicitationMode, |
| 78 | + **kwargs: Any, |
| 79 | + ) -> CreateElicitationResponse: |
| 80 | + return AcceptElicitationResponse(action="accept", content={}) |
| 81 | + |
| 82 | + async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None: |
| 83 | + ... |
| 84 | +``` |
| 85 | + |
| 86 | +Agents can request structured input through the connected client: |
| 87 | + |
| 88 | +```python |
| 89 | +from acp import ( |
| 90 | + ElicitationFormSessionMode, |
| 91 | + ElicitationSchema, |
| 92 | + ElicitationStringPropertySchema, |
| 93 | +) |
| 94 | + |
| 95 | +response = await client_conn.create_elicitation( |
| 96 | + message="Choose a deployment target", |
| 97 | + mode=ElicitationFormSessionMode( |
| 98 | + session_id=session_id, |
| 99 | + requested_schema=ElicitationSchema( |
| 100 | + properties={"target": ElicitationStringPropertySchema(type="string")}, |
| 101 | + required=["target"], |
| 102 | + ), |
| 103 | + ), |
| 104 | +) |
| 105 | +``` |
| 106 | + |
| 107 | +For URL-based flows, use `ElicitationUrlSessionMode` or `ElicitationUrlRequestMode` and call `complete_elicitation(...)` once the external flow finishes. |
| 108 | + |
| 109 | +## 5. Review new session update variants |
| 110 | + |
| 111 | +Clients that exhaustively match `session_update` variants should add the new plan update variants: |
| 112 | + |
| 113 | +```python |
| 114 | +from acp.schema import AgentPlanContentUpdate, AgentPlanRemovedUpdate |
| 115 | + |
| 116 | +async def session_update(self, session_id, update, **kwargs): |
| 117 | + if isinstance(update, AgentPlanContentUpdate): |
| 118 | + ... |
| 119 | + elif isinstance(update, AgentPlanRemovedUpdate): |
| 120 | + ... |
| 121 | +``` |
| 122 | + |
| 123 | +The existing full-plan `AgentPlanUpdate` variant remains available. |
| 124 | + |
| 125 | +## 6. Review MCP server configuration types |
| 126 | + |
| 127 | +Session creation, loading, forking, and resuming now accept `AcpMcpServer` in addition to HTTP, SSE, and stdio MCP server definitions: |
| 128 | + |
| 129 | +```python |
| 130 | +from acp.schema import AcpMcpServer, HttpMcpServer, McpServerStdio, SseMcpServer |
| 131 | +``` |
| 132 | + |
| 133 | +If you validate `mcp_servers` with your own union, add `AcpMcpServer` to keep accepting all SDK-supported server types. |
| 134 | + |
| 135 | +## 7. Re-run examples and checks |
| 136 | + |
| 137 | +After changing signatures, run the standard gates: |
| 138 | + |
| 139 | +```bash |
| 140 | +make check |
| 141 | +make test |
| 142 | +``` |
| 143 | + |
| 144 | +Also run any example or integration that subclasses `Agent` or `Client`. Positional argument bugs usually surface there first; using keyword arguments for connection calls avoids most of them. |
0 commit comments