A2A/docs/tutorials/python/4-agent-executor.md
Iva Sokolaj 32a7d3a0bd
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

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 via context) and uses the event_queue to send back Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent objects.
  • 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.

  1. 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 invoke method that returns the string "Hello, World!".

  2. The Executor (HelloWorldAgentExecutor): This class implements the AgentExecutor interface.

    • __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/send or message/stream request comes in (both are handled by execute in this simplified executor):

      1. It retrieves the current task from the context or creates a new one, enqueueing it as the first event.
      2. It enqueues a TaskStatusUpdateEvent with a state of TASK_STATE_WORKING to indicate the agent has begun processing.
      3. It calls self.agent.invoke() to execute the actual business logic (which simply returns "Hello, World!").
      4. It enqueues a TaskArtifactUpdateEvent containing the result text.
      5. Finally, it enqueues a TaskStatusUpdateEvent with a state of TASK_STATE_COMPLETED to conclude the task.
    • cancel: The Hello World example's cancel method 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.