In the future, we should probably explore refactoring the docs set to
avoid these becoming out of sync going forward
This pull request updates the project documentation to align with the
v1.0 Agent2Agent (A2A) Protocol Specification defined in
specification/a2a.proto. It ensures that all conceptual guides,
summaries, and tutorials reflect the current normative definitions,
RPC method names, and wire formats.
Summary of Changes
1. RPC Method Naming Updates
Standardized all method references to use the v1.0 PascalCase naming
convention:
* `message/send` → `SendMessage`
* `message/stream` → `SendStreamingMessage`
* `tasks/get` → `GetTask`
* `tasks/list` → `ListTasks`
* `tasks/cancel` → `CancelTask`
* `tasks/pushNotificationConfig/set` →
`CreateTaskPushNotificationConfig`
* `tasks/resubscribe` → `SubscribeToTask`
* `agent/getAuthenticatedExtendedCard` → `GetExtendedAgentCard`
2. JSON Example & Wire Format Corrections
Updated examples across all "Topic" files and the Python Quickstart to
match v1.0 breaking changes:
* Removed `kind` discriminators: Examples for Message, Task, Part, and
StreamResponse now use member-based polymorphism (e.g.,
{"text": "..."} instead of {"kind": "text", "text": "..."}).
* Enum Standardization: Changed role and state enums from
kebab-case/lowercase to SCREAMING_SNAKE_CASE with type prefixes (e.g.,
`"ROLE_USER"`, `"TASK_STATE_COMPLETED"`).
* Response Wrapping: Updated examples to reflect that `SendMessage` and
`SendStreamingMessage` return a unified response object where
the message or task is nested within the result.
3. LLM Context (`docs/llms.txt`)
* Completely refreshed the protocol summary and RPC method list to
ensure LLM-based tools (like Gemini CLI) have an accurate
representation of the v1.0 API surface and error codes.
4. Link & Anchor Maintenance
* Updated internal documentation links and spans to point to the correct
sections in the specification.md (e.g., correcting the
anchor for GetExtendedAgentCard).
Why this is needed
The v1.0 release introduced significant structural improvements for
ProtoJSON compliance and architectural consistency. Documentation
examples were previously showing v0.3.0 patterns which would cause
integration errors for developers using the latest SDKs.
4.4 KiB
6. Interacting with the Server
With the Helloworld A2A server running, let's send some requests to it. The SDK includes a client (A2AClient) that simplifies these interactions.
The Helloworld Test Client
The test_client.py script demonstrates how to:
- Fetch the Agent Card from the server.
- Create an
A2AClientinstance. - Send both non-streaming (
message/send) and streaming (message/stream) requests.
Open a new terminal window, activate your virtual environment, and navigate to the a2a-samples directory.
Activate virtual environment (Be sure to do this in the same directory where you created the virtual environment):
=== "Mac/Linux"
```sh
source .venv/bin/activate
```
=== "Windows"
```powershell
.venv\Scripts\activate
```
Run the test client:
# from the a2a-samples directory
python samples/python/agents/helloworld/test_client.py
Understanding the Client Code
Let's look at key parts of test_client.py:
-
Fetching the Agent Card & Initializing the Client:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver"The
A2ACardResolverclass is a convenience. It first fetches theAgentCardfrom the server's/.well-known/agent-card.jsonendpoint (based on the provided base URL) and then initializes the client with it. -
Sending a Non-Streaming Message (
send_message):--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message"- The
send_message_payloadconstructs the data forMessageSendParams. - This is wrapped in a
SendMessageRequest. - It includes a
messageobject with theroleset to "user" and the content inparts. - The Helloworld agent's
executemethod will enqueue a single "Hello World" message. TheDefaultRequestHandlerwill retrieve this and send it as the response. - The
responsewill be aSendMessageResponseobject, which contains either aSendMessageSuccessResponse(with the agent'sMessageas the result) or aJSONRPCErrorResponse.
- The
-
Handling Task IDs (Illustrative Note for Helloworld):
The Helloworld client (
test_client.py) doesn't attemptget_taskorcancel_taskdirectly because the simple Helloworld agent'sexecutemethod, when called viamessage/send, results in theDefaultRequestHandlerreturning a directMessageresponse rather than aTaskobject. More complex agents that explicitly manage tasks (like the LangGraph example) would return aTaskobject frommessage/send, and itsidcould then be used forget_taskorcancel_task. -
Sending a Streaming Message (
send_message_streaming):--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:send_message_streaming"- This method calls the agent's
message/streamendpoint. TheDefaultRequestHandlerwill invoke theHelloWorldAgentExecutor.executemethod. - The
executemethod enqueues one "Hello World" message, and then the event queue is closed. - The client will receive this single message as one
SendStreamingMessageResponseevent, and then the stream will terminate. - The
stream_responseis anAsyncGenerator.
- This method calls the agent's
Expected Output
When you run test_client.py, you'll see JSON outputs for:
- The non-streaming response (a single "Hello World" message).
- The streaming response (a single "Hello World" message as one chunk, after which the stream ends).
The id fields in the output will vary with each run.
// Non-streaming response
{"jsonrpc":"2.0","id":"xxxxxxxx","result":{"message":{"role":"ROLE_AGENT","parts":[{"text":"Hello World"}],"messageId":"yyyyyyyy"}}}
// Streaming response (one chunk)
{"jsonrpc":"2.0","id":"zzzzzzzz","result":{"message":{"role":"ROLE_AGENT","parts":[{"text":"Hello World"}],"messageId":"wwwwwwww"}}}
(Actual IDs like xxxxxxxx, yyyyyyyy, zzzzzzzz, wwwwwwww will be different UUIDs/request IDs)
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure!
Now you can shut down the server by typing Ctrl+C in the terminal window where __main__.py is running.