A2A/docs/tutorials/python/5-start-server.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

59 lines
3.4 KiB
Markdown
Raw Permalink Normal View History

# 5. Starting the Server
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/).
## Server Setup in Helloworld
Let's look at `__main__.py` again to see how the server is initialized and started.
```python { .no-copy }
2025-06-23 21:34:48 +02:00
--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 (`HelloWorldAgentExecutor`), a `TaskStore` (`InMemoryTaskStore`), and the public and extended `AgentCard` objects.
- 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`**:
- `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.
3. **`uvicorn.run(app, ...)`**:
- The constructed `Starlette` app is run using `uvicorn.run()`, making your agent accessible over HTTP.
docs: update python tutorial for a2a-sdk v1.0.0-alpha.0 (#1678) 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.
2026-03-26 13:50:49 +01:00
- `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.
docs: update python tutorial for a2a-sdk v1.0.0-alpha.0 (#1678) 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.
2026-03-26 13:50:49 +01:00
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.