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.
3.0 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.
The A2A Python SDK provides an A2AStarletteApplication class that simplifies running an A2A-compliant HTTP server. It uses Starlette for the web framework and is typically run with an ASGI server like 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:
-
DefaultRequestHandler:- The SDK provides
DefaultRequestHandler. This handler takes yourAgentExecutorimplementation (here,HelloWorldAgentExecutor) and aTaskStore(here,InMemoryTaskStore). - It routes incoming A2A RPC calls to the appropriate methods on your executor (like
executeorcancel). - The
TaskStoreis used by theDefaultRequestHandlerto 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.
- The SDK provides
-
A2AStarletteApplication:- The
A2AStarletteApplicationclass is instantiated with theagent_card,request_handler(referred to ashttp_handlerin its constructor), and an optionalextended_agent_card. - The
agent_cardis exposed at the/.well-known/agent-card.jsonendpoint for public discovery. - The
request_handlerprocesses all incoming A2A method calls by interacting with yourAgentExecutor. - The
extended_agent_cardprovides additional capabilities and skills for authenticated users and is exposed via theGetExtendedAgentCardRPC method.
- The
-
uvicorn.run(server_app_builder.build(), ...):- The
A2AStarletteApplicationhas abuild()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=9999specifies the port to listen on. This matches the endpoints defined in theAgentCard'ssupported_interfaces.
- The
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.