A2A/docs/tutorials/python/4-agent-executor.md
Iva Sokolaj ae6a562d5d
docs: rename "Stream Message" to "Send Streaming Message" and replace legacy method names (#1784)
## Summary
Standardizes the operation names used throughout the spec and Python
tutorials so they match the canonical A2A operation names (`Send
Message` / `Send Streaming Message`) instead of the older JSON-RPC-style
identifiers (`message/send`, `message/stream`) or the inconsistent short
form `Stream Message`.
## Changes
- **`docs/specification.md`**
  - Architecture diagram: `Stream Message` → `Send Streaming Message`.
  - Section 3.1.3 (Get Task): `message/send` → `Send Message`.
  - Event delivery section: `Stream Message` → `Send Streaming Message`.
- Multi-protocol functionality table: `Stream message` → `Send Streaming
Message`.
- **`docs/tutorials/python/4-agent-executor.md`**: `message/send` /
`message/stream` → `Send Message` / `Send Streaming Message`.
- **`docs/tutorials/python/6-interact-with-server.md`**: same rename in
the `test_client.py` description.
- **`docs/tutorials/python/7-streaming-and-multiturn.md`**:
`message/send` → `Send Message` in the `CurrencyAgentExecutor`
walkthrough.
## Why
The docs previously mixed three different names for the same operations
(`message/stream`, `Stream Message`, `SendStreamingMessage`), which was
confusing for readers cross-referencing the spec, tutorials, and SDK.
This change picks one human-readable form per operation and uses it
consistently in prose, while leaving the code-level identifiers
(`SendMessage`, `SendStreamingMessage`, `POST /message:stream`, etc.)
untouched in the protocol-binding tables.
2026-04-23 13:54:31 +02:00

3.2 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 Send Message or Send Streaming Message request comes in (both are handled by execute in this simplified executor), the following steps occur:

      Step 1. The A2A instance (server) retrieves the current task from the context. If there is no task in context, then it creates a new task and adds it to the EventQueue.

      Step 2. It enqueues a TaskStatusUpdateEvent with a state of TASK_STATE_WORKING to indicate the agent has begun processing.

      Step 3. It calls self.agent.invoke() to execute the actual business logic (which simply returns "Hello, World!").

      Step 4. It enqueues a TaskArtifactUpdateEvent containing the result text from the agent.

      Step 5. Finally, it enqueues a TaskStatusUpdateEvent with a state of TASK_STATE_COMPLETED to conclude the task.

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.