Compare commits

..

4 Commits

Author SHA1 Message Date
Sampath Kumar
4f81c788ad refactor(docs): fix markdown formatting bugs 2026-04-16 12:29:50 +02:00
Sampath Kumar
7a873c805a refactor(docs): Update cross references for specification sections 3 & 4; 2026-04-16 12:01:37 +02:00
Sampath Kumar
44f7d70735 refactor(docs): Update cross references for swapping section 4 with section 3. 2026-04-16 11:57:44 +02:00
Sampath Kumar
2993cac381 refactor(docs): Move Section 4 (Protocol Data Model), to become the new Section 3.
Right now, Section 3 (Operations) describes how to do things (Send Message, Get Task) using objects that aren't defined until Section 4 (Data Model). This change is aims to fix this by swapping the sections.
2026-04-16 11:34:20 +02:00
10 changed files with 776 additions and 838 deletions

View File

@ -354,7 +354,6 @@ taskstate
taskstatus
textpart
threadsafe
tiangolo
toctree
tok
tolgaki

File diff suppressed because it is too large Load Diff

View File

@ -81,7 +81,7 @@ Agent Cards include sensitive information, such as:
To mitigate risks, the following protection mechanisms should be considered:
- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#3111-get-extended-agent-card) for sensitive information or for serving a more detailed version of the card.
- **Authenticated Agent Cards:** We recommend the use of [authenticated extended agent cards](../specification.md#4111-get-extended-agent-card) for sensitive information or for serving a more detailed version of the card.
- **Secure Endpoints:** Implement access controls on the HTTP endpoint serving the Agent Card (e.g., `/.well-known/agent-card.json` or registry API). The methods include:
- Mutual TLS (mTLS)
- Network restrictions (e.g., IP ranges)

View File

@ -52,7 +52,7 @@ The following key features detail how push notifications are implemented and man
- Separately, using the `CreateTaskPushNotificationConfig` RPC method for an existing task.
The `PushNotificationConfig` includes a `url` (the HTTPS webhook URL), an optional `token` (for client-side validation), and optional `authentication` details (for the A2A Server to authenticate to the webhook).
- **Notification Trigger:** The A2A Server decides when to send a push notification, typically when a task reaches a significant state change (for example, terminal state, `input-required`, or `auth-required`).
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#323-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#pushnotificationpayload) for detailed structure.
- **Notification Payload:** The A2A protocol defines the HTTP body payload as a [`StreamResponse`](../specification.md#423-stream-response) object, matching the format used in streaming operations. The payload contains one of: `task`, `message`, `statusUpdate`, or `artifactUpdate`. See [Push Notification Payload](../specification.md#pushnotificationpayload) for detailed structure.
- **Client Action:** Upon receiving a push notification (and successfully verifying its authenticity), the client typically uses the `GetTask` RPC method with the `taskId` from the notification to retrieve the complete, updated `Task` object, including any new artifacts.
### When to Use Push Notifications
@ -67,7 +67,7 @@ Push notifications are ideal for:
Refer to the Protocol Specification for detailed structures:
- [`CreateTaskPushNotificationConfig`](../specification.md#317-create-push-notification-config)
- [`CreateTaskPushNotificationConfig`](../specification.md#417-create-push-notification-config)
- [`GetTask`](../specification.md#76-taskspushnotificationconfigget)
### Client-Side Push Notification Service

View File

@ -1,4 +1,4 @@
# 2. Set Up Your Environment
# 2. Setup Your Environment
## Prerequisites
@ -38,7 +38,7 @@ We recommend using a virtual environment for Python projects. The A2A Python SDK
.venv\Scripts\activate
```
2. **Install the A2A SDK and its required Python dependencies:**
2. **Install needed Python dependencies along with the A2A SDK and its dependencies:**
```bash
pip install -r samples/python/requirements.txt

View File

@ -33,6 +33,7 @@ The **Agent Card** is a JSON document that an A2A Server makes available, typica
Key attributes of an `AgentCard` (defined in `a2a.types`):
- `name`, `description`, `version`: Basic identity information.
- `icon_url`: A URL to an icon representing the agent.
- `supported_interfaces`: Ordered list of endpoints and protocols where the A2A service can be reached.
- `capabilities`: Supported A2A features like `streaming` or `extended_agent_card`.
- `default_input_modes` / `default_output_modes`: Default Media Types for the agent.
@ -44,4 +45,6 @@ The `helloworld` example defines its Agent Card like this:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py:AgentCard"
```
This card tells us the agent is named "Hello World Agent", can be run at `http://127.0.0.1:9999/`, supports text interactions, and has the `hello_world` skill.
This card tells us the agent is named "Hello World Agent", runs at `http://localhost:9999` using `JSONRPC`, supports text interactions, and has the `hello_world` skill. Its capabilities also indicate support for streaming and an extended authenticated configuration.
Understanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it.

View File

@ -41,16 +41,19 @@ Let's look at `agent_executor.py`. It defines `HelloWorldAgentExecutor`.
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute"
```
When a `Send Message` or `Send Streaming Message` request comes in (both are handled by `execute` in this simplified executor), the following steps occur:
When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor):
**Step 1.** The `A2A instance` (server) retrieves the current task from the context. If there is no task in context, then it creates a new task and adds it to the `EventQueue`.
1. It retrieves the current task from the context or creates a new one, enqueueing it as the first event.
2. It enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_WORKING` to indicate the agent has begun processing.
3. It calls `self.agent.invoke()` to execute the actual business logic (which simply returns "Hello, World!").
4. It enqueues a `TaskArtifactUpdateEvent` containing the result text.
5. Finally, it enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_COMPLETED` to conclude the task.
**Step 2.** It enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_WORKING` to indicate the agent has begun processing.
- **`cancel`**:
The Hello World example's `cancel` method simply raises an exception, indicating that cancellation is not supported for this basic agent.
**Step 3.** It calls `self.agent.invoke()` to execute the actual business logic (which simply returns "Hello, World!").
**Step 4.** It enqueues a `TaskArtifactUpdateEvent` containing the result text from the agent.
**Step 5.** Finally, it enqueues a `TaskStatusUpdateEvent` with a state of `TASK_STATE_COMPLETED` to conclude the task.
```python { .no-copy }
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel"
```
The `AgentExecutor` acts as the bridge between the A2A protocol (managed by the request handler and server application) and your agent's specific logic. It receives context about the request and uses an event queue to communicate results or updates back.

View File

@ -2,9 +2,7 @@
Now that we have an Agent Card and an Agent Executor, we can set up and start the A2A server.
To set up an A2A server, the Python SDK provides a route factory and helper functions (`create_agent_card_routes`, `create_jsonrpc_routes`, `create_rest_routes`). Use the route factory to create routes for the A2A server's services. These routes can be attached natively to popular frameworks like [Starlette](https://www.starlette.io/) and [FastAPI](https://fastapi.tiangolo.com/), which give you better control over authentication, logging, and other features.
In this tutorial, we will use Starlette with [Uvicorn](https://www.uvicorn.org/).
The A2A Python SDK provides an `A2AStarletteApplication` class that simplifies running an A2A-compliant HTTP server. It uses [Starlette](https://www.starlette.io/) for the web framework and is typically run with an ASGI server like [Uvicorn](https://www.uvicorn.org/).
## Server Setup in Helloworld
@ -18,20 +16,20 @@ Let's break this down:
1. **`DefaultRequestHandler`**:
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (`HelloWorldAgentExecutor`), a `TaskStore` (`InMemoryTaskStore`), and the public and extended `AgentCard` objects.
- The SDK provides `DefaultRequestHandler`. This handler takes your `AgentExecutor` implementation (here, `HelloWorldAgentExecutor`) and a `TaskStore` (here, `InMemoryTaskStore`).
- It routes incoming A2A RPC calls to the appropriate methods on your executor (like `execute` or `cancel`).
- The `TaskStore` is used by the `DefaultRequestHandler` to manage the lifecycle of tasks, especially for stateful interactions, streaming, and resubscription. Even if your agent executor is simple, the handler needs a task store.
- `agent_card` is passed to the handler so it can verify the agent's declared capabilities when processing incoming requests. For example, it checks whether streaming or push notifications are supported before handling those request types.
- `extended_agent_card` is passed so the handler can serve it via the `GetExtendedAgentCard` RPC method to authenticated clients.
2. **`create_agent_card_routes` and `create_jsonrpc_routes`**:
2. **`A2AStarletteApplication`**:
- `create_agent_card_routes(public_agent_card)` returns Starlette routes that expose the Agent Card at the `/.well-known/agent-card.json` endpoint for public discovery.
- `create_jsonrpc_routes(request_handler, '/')` returns Starlette routes that handle all incoming A2A JSON-RPC method calls by delegating to the `request_handler`.
- These route lists are combined and passed to a standard `Starlette` application.
- The `A2AStarletteApplication` class is instantiated with the `agent_card`, `request_handler` (referred to as `http_handler` in its constructor), and an optional `extended_agent_card`.
- The `agent_card` is exposed at the `/.well-known/agent-card.json` endpoint for public discovery.
- The `request_handler` processes all incoming A2A method calls by interacting with your `AgentExecutor`.
- The `extended_agent_card` provides additional capabilities and skills for authenticated users and is exposed via the `GetExtendedAgentCard` RPC method.
3. **`uvicorn.run(app, ...)`**:
- The constructed `Starlette` app is run using `uvicorn.run()`, making your agent accessible over HTTP.
3. **`uvicorn.run(server_app_builder.build(), ...)`**:
- The `A2AStarletteApplication` has a `build()` method that constructs the actual Starlette application.
- This application is then run using `uvicorn.run()`, making your agent accessible over HTTP.
- `host='127.0.0.1'` makes the server accessible only from your local machine.
- `port=9999` specifies the port to listen on. This matches the endpoints defined in the `AgentCard`'s `supported_interfaces`.

View File

@ -1,18 +1,18 @@
# 6. Interacting with the Server
With the Helloworld A2A server running, let's send some requests to it.
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:
1. Fetch the Agent Card from the server.
2. Create a client using `create_client`.
3. Send both `Send Message` and `Send Streaming Message` requests.
2. Create an `A2AClient` instance.
3. 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 the virtual environment (be sure to do this in the same directory where you created it):
Activate virtual environment (Be sure to do this in the same directory where you created the virtual environment):
=== "Mac/Linux"
@ -43,7 +43,7 @@ Let's look at key parts of `test_client.py`:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:A2ACardResolver"
```
The `A2ACardResolver` class is a convenience. When `get_agent_card()` is called, it fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL), which is then used to initialize the client.
The `A2ACardResolver` class is a convenience. It first fetches the `AgentCard` from the server's `/.well-known/agent-card.json` endpoint (based on the provided base URL) which is then used to initialize the client.
2. **Initializing the Client & Sending a Non-Streaming Message**:
@ -51,9 +51,10 @@ Let's look at key parts of `test_client.py`:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_send"
```
- The `create_client` function creates a `Client` based on the information provided by the `AgentCard` and a `ClientConfig`.
- We construct a `Message` using the `new_text_message` helper (passing `role=Role.ROLE_USER`), then wrap it in a `SendMessageRequest`.
- The client's `send_message` method returns an async iterator that yields a single final `Task` or `Message` response from the agent. In this example, it is a `Task`.
- A `ClientFactory` creates a non-streaming client based on the fetched card.
- We construct a `Message` object using `Role.ROLE_USER` and `Part` for the content.
- This is wrapped in a `SendMessageRequest`.
- The client's `send_message` method returns an async generator that yields a sequence of `Task` events from the agent.
3. **Initializing the Client & Sending a Streaming Message**:
@ -61,53 +62,20 @@ Let's look at key parts of `test_client.py`:
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/test_client.py:message_stream"
```
- A separate streaming client is created via `create_client` with `streaming=True` in its `ClientConfig`.
- We again call `send_message`, which now streams events: each iteration of the loop prints a discrete chunk as it arrives over the network.
- Call `await streaming_client.close()` after the loop to release the underlying HTTP connection.
- A new streaming client is created via `ClientFactory` configured with `streaming=True`.
- We again call `send_message` (which now handles both streaming and non-streaming under the same method name, based on the `ClientConfig` and agent `capabilities`).
- The response dynamically yields `Task` events as they are streamed over the network.
## Expected Output
When you run `test_client.py`, you'll see output for:
When you run `test_client.py`, you'll see in protobuf text format outputs for:
- The public agent card, displayed in a formatted summary.
- The non-streaming response: a single `task` in protobuf text format containing the completed status, the generated artifact with "Hello, World!", and the agent's intermediate status message in history.
- The streaming response: four chunks — the initial `task`, a `status_update` for WORKING, an `artifact_update` with the result, and a final `status_update` for COMPLETED.
- The extended agent card, displayed in a formatted summary (with an additional `super_hello_world` skill).
- The non-streaming response (a single final `task` log detailing the history, status, and the generated artifact containing the "Hello, World!" text).
- The streaming response (multiple discrete events including the initial `task`, a `status_update`, and a final `artifact_update` containing the "Hello, World!" text).
The `id` fields in the output will vary with each run.
```console { .no-copy }
AgentCard
--- General ---
Name : Hello World Agent
Description : Just a hello world agent
Version : 0.0.1
--- Interfaces ---
[0] http://127.0.0.1:9999 (JSONRPC)
--- Capabilities ---
Streaming : True
Push notifications : False
Extended agent card : True
--- I/O Modes ---
Input : text/plain
Output : text/plain
--- Skills ---
----------------------------------------------------
ID : hello_world
Name : Returns hello world
Description : just returns hello world
Tags : hello world
Example : hi
Example : hello world
--- Non-Streaming Call ---
Non-streaming Client initialized.
Response:
// Non-streaming response
task {
id: "xxxxxxxx"
@ -195,43 +163,10 @@ status_update {
state: TASK_STATE_COMPLETED
}
}
AgentCard
--- General ---
Name : Hello World Agent - Extended Edition
Description : The full-featured hello world agent for authenticated users.
Version : 0.0.2
--- Interfaces ---
[0] http://127.0.0.1:9999 (JSONRPC)
--- Capabilities ---
Streaming : True
Push notifications : False
Extended agent card : True
--- I/O Modes ---
Input : text/plain
Output : text/plain
--- Skills ---
----------------------------------------------------
ID : hello_world
Name : Returns hello world
Description : just returns hello world
Tags : hello world
Example : hi
Example : hello world
----------------------------------------------------
ID : super_hello_world
Name : Returns a SUPER Hello World
Description : A more enthusiastic greeting, only for authenticated users.
Tags : hello world, super, extended
Example : super hi
Example : give me a super hello
```
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `wwwwwwww`, and `vvvvvvvv` will be different UUIDs in each run.)_
_(Actual IDs like `xxxxxxxx`, `yyyyyyyy`, `zzzzzzzz`, `vvvvvvvv`, `wwwwwwww` will be different UUIDs/request IDs)_
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure.
This confirms your server is correctly handling basic A2A interactions with the updated SDK structure!
You can now shut down the server by pressing Ctrl+C in the terminal window where `__main__.py` is running.
Now you can shut down the server by typing Ctrl+C in the terminal window where `__main__.py` is running.

View File

@ -6,7 +6,7 @@ This example features a "Currency Agent" that uses the Gemini model via LangChai
## Setting up the LangGraph Example
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key) if you don't already have one.
1. Create a [Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key), if you don't already have one.
2. **Environment Variable:**
@ -64,14 +64,14 @@ The `langgraph` example showcases several important A2A concepts:
```
- The `CurrencyAgentExecutor` (in `samples/langgraph/agent_executor.py`), when its `execute` method is called by the `DefaultRequestHandler`, interacts with the `RequestContext` which contains the current task (if any).
- For `Send Message`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `Send Message` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
- For `message/send`, the `DefaultRequestHandler` uses the `TaskStore` to persist and retrieve task state across interactions. The response to `message/send` will be a full `Task` object if the agent's execution flow involves multiple steps or results in a persistent task.
- The `test_client.py`'s `run_single_turn_test` demonstrates getting a `Task` object back and then querying it using `get_task`.
3. **Streaming with `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`**:
- The `execute` method in `CurrencyAgentExecutor` is responsible for handling both non-streaming and streaming requests, orchestrated by the `DefaultRequestHandler`.
- As the LangGraph agent processes the request (which might involve calling tools like `get_exchange_rate`), the `CurrencyAgentExecutor` enqueues different types of events onto the `EventQueue`:
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates...").
- `TaskStatusUpdateEvent`: For intermediate updates (e.g., "Looking up exchange rates...", "Processing the exchange rates..").
- `TaskArtifactUpdateEvent`: When the final answer is ready, it's enqueued as an artifact. The `lastChunk` flag is `True`.
- A final `TaskStatusUpdateEvent` with `state=TaskState.completed` is sent to signify the end of the task, closing the stream.
- The `test_client.py`'s `run_streaming_test` function will print these individual event chunks as they are received from the server.