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.4 KiB
4. The Agent Executor
The core logic of how an A2A agent processes requests and generates responses/events is handled by an Agent Executor. The A2A Python SDK provides an abstract base class a2a.server.agent_execution.AgentExecutor that you implement.
AgentExecutor Interface
The AgentExecutor class defines two primary methods:
async def execute(self, context: RequestContext, event_queue: EventQueue): Handles incoming requests that expect a response or a stream of events. It processes the user's input (available viacontext) and uses theevent_queueto send backMessage,Task,TaskStatusUpdateEvent, orTaskArtifactUpdateEventobjects.async def cancel(self, context: RequestContext, event_queue: EventQueue): Handles requests to cancel an ongoing task.
The RequestContext provides information about the incoming request, such as the user's message and any existing task details. The EventQueue is used by the executor to send events back to the client.
Helloworld Agent Executor
Let's look at agent_executor.py. It defines HelloWorldAgentExecutor.
-
The Agent (
HelloWorldAgent): This is a simple helper class that encapsulates the actual "business logic".--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent"It has a simple
invokemethod that returns the string "Hello, World!". -
The Executor (
HelloWorldAgentExecutor): This class implements theAgentExecutorinterface.-
__init__:--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_init"It instantiates the
HelloWorldAgent. -
execute:--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute"When a
message/sendormessage/streamrequest comes in (both are handled byexecutein this simplified executor):- It retrieves the current task from the context or creates a new one, enqueueing it as the first event.
- It enqueues a
TaskStatusUpdateEventwith a state ofTASK_STATE_WORKINGto indicate the agent has begun processing. - It calls
self.agent.invoke()to execute the actual business logic (which simply returns "Hello, World!"). - It enqueues a
TaskArtifactUpdateEventcontaining the result text. - Finally, it enqueues a
TaskStatusUpdateEventwith a state ofTASK_STATE_COMPLETEDto conclude the task.
-
cancel: The Hello World example'scancelmethod simply raises an exception, indicating that cancellation is not supported for this basic agent.--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_cancel"
-
The AgentExecutor acts as the bridge between the A2A protocol (managed by the request handler and server application) and your agent's specific logic. It receives context about the request and uses an event queue to communicate results or updates back.