A2A/docs/tutorials/python/5-start-server.md
Iva Sokolaj c5104cec72
docs: update Python helloworld tutorial for a2a-sdk v1.0 (#1775)
# Description
Update the Python tutorial to be compliant with the newly released A2A
SDK v1.0.

`Helloworld sample` referenced in the Python tutorial was updated to use
the new `v1.0.1`: [PR
527](https://github.com/a2aproject/a2a-samples/pull/527)
2026-04-23 11:23:52 +02:00

3.4 KiB

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 and FastAPI, which give you better control over authentication, logging, and other features.

In this tutorial, we will use Starlette with Uvicorn.

Server Setup in Helloworld

Let's look at __main__.py again to see how the server is initialized and started.

--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.
    • 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:

# from the a2a-samples directory
python samples/python/agents/helloworld/__main__.py

You should see output similar to this, indicating the server is running:

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.