Issue: #1679 # Description [a2a-samples/python](https://github.com/a2aproject/a2a-samples/tree/main/samples/python) is being updated to use the new `v1.0`: [samples-#462](https://github.com/a2aproject/a2a-samples/issues/462). We are looking to merge [update helloworld sample to v1.0-alpha](https://github.com/a2aproject/a2a-samples/pull/474) and consequently need to update python tutorial in A2A as it references the `helloworld sample`. # Key Changes - **Agent Skills & Card** (3-agent-skills-and-card.md): Updated the docs to match the new AgentCard schema. Replaced the legacy `url` property with `icon_url`, documented the new `supported_interfaces` field for protocol bindings, and added mentions of the extended_agent_card capability. - **HelloWorldAgentExecutor logic** (4-agent-executor.md): Rewrote the walkthrough for the execute method to reflect the modern event-driven approach and to make the difference between non-streaming and streaming more clear. It now explicitly describes enqueueing Task, TaskStatusUpdateEvent (with `TASK_STATE_WORKING`), TaskArtifactUpdateEvent, and TaskStatusUpdateEvent (with `TASK_STATE_COMPLETED`) instead of single string messages. - **Server Setup** (5-start-server.md): Replaced `0.0.0.0` with `127.0.0.1` in the host binding tutorial and log examples to enforce safer local testing defaults. - **Client Interaction** (6-interact-with-server.md): - Replaced MessageSendParams dictionaries with native protobuf `Message/Part/Role` construction. - Replaced direct A2ACardResolver instantiation with the new `ClientFactory` approach. - Unified the documentation around `send_message` (which now handles streams dynamically based on `config` and agent capabilities) and updated expected log outputs.
57 lines
3.0 KiB
Markdown
57 lines
3.0 KiB
Markdown
# 5. Starting the Server
|
|
|
|
Now that we have an Agent Card and an Agent Executor, we can set up and start the A2A server.
|
|
|
|
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
|
|
|
|
Let's look at `__main__.py` again to see how the server is initialized and started.
|
|
|
|
```python { .no-copy }
|
|
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/__main__.py"
|
|
```
|
|
|
|
Let's break this down:
|
|
|
|
1. **`DefaultRequestHandler`**:
|
|
|
|
- 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.
|
|
|
|
2. **`A2AStarletteApplication`**:
|
|
|
|
- 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(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`.
|
|
|
|
## Running the Helloworld Server
|
|
|
|
Navigate to the `a2a-samples` directory in your terminal (if you're not already there) and ensure your virtual environment is activated.
|
|
|
|
To run the Helloworld server:
|
|
|
|
```bash
|
|
# from the a2a-samples directory
|
|
python samples/python/agents/helloworld/__main__.py
|
|
```
|
|
|
|
You should see output similar to this, indicating the server is running:
|
|
|
|
```console { .no-copy }
|
|
INFO: Started server process [xxxxx]
|
|
INFO: Waiting for application startup.
|
|
INFO: Application startup complete.
|
|
INFO: Uvicorn running on http://127.0.0.1:9999 (Press CTRL+C to quit)
|
|
```
|
|
|
|
Your A2A Helloworld agent is now live and listening for requests! In the next step, we'll interact with it.
|