A2A Protocol Technical Documentation
Tutorials
Python Quickstart
5. Starting the Server

5. Starting the Server

With an Agent Card and an Agent Executor in place, you can set up and start the A2A server.

The Python SDK provides a route factory and helper functions (create_agent_card_routes, create_jsonrpc_routes, create_rest_routes) that create routes for the A2A server’s services. These routes attach natively to popular frameworks such as Starlette and FastAPI , which give you better control over authentication, logging, and other features. This tutorial uses Starlette with Uvicorn .

Server setup in Helloworld

Look at __main__.py again to see how the server is initialized and started.

First, create the request handler:

# The RequestHandler processes incoming requests and manages tasks
request_handler = DefaultRequestHandler(
    # Agent executor handles the execution of the client requests
    agent_executor=HelloWorldAgentExecutor(),
    # The task_store is used to store and manage tasks
    task_store=InMemoryTaskStore(),
    # Public agent card for unauthenticated users
    agent_card=public_agent_card,
    # Extended agent card for authenticated users
    extended_agent_card=extended_agent_card,
)

Then create the routes, build the app, and run it:

# Creating the routes for the A2A server
# These routes handle the incoming requests from the clients
# and the outgoing responses to the clients
routes = []

# Create routes for the agent card
routes.extend(create_agent_card_routes(public_agent_card))

# Create routes for the JSONRPC protocol
# Alternatively, you can choose GRPC or HTTP_JSON as protocol bindings
# based on your requirements
routes.extend(create_jsonrpc_routes(request_handler, '/'))

# Create a web app with the defined routes
# Here we are using Starlette, a lightweight ASGI web framework to serve the agent
# Alternatively, you can choose FastAPI or other ASGI frameworks
app = Starlette(routes=routes)

# Run the app
# Uvicorn is a production-ready ASGI HTTP server
uvicorn.run(app, host='127.0.0.1', port=9999)

Taking it piece by piece:

1. DefaultRequestHandler

  • The SDK provides DefaultRequestHandler. It 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 (such as execute or cancel).
  • The TaskStore is used by 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 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 through the GetExtendedAgentCard 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 with 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. It matches the endpoint defined in the AgentCard’s supported_interfaces.

Running the Helloworld server

In your terminal, go to the a2a-samples directory (if you are not already there) and make sure your virtual environment is activated, then run:

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

You should see output similar to this, indicating that 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, you will interact with it .

Source: A2A official documentation · Starting the Server

4. The Agent Executor6. Interacting with the Server