A2A/docs/tutorials/python/4-agent-executor.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

57 lines
3.2 KiB
Markdown
Raw Permalink Normal View History

# 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".
```python { .no-copy }
2025-06-23 21:34:48 +02:00
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgent"
```
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
It has a simple `invoke` method that returns the string "Hello, World!".
2. **The Executor (`HelloWorldAgentExecutor`)**:
This class implements the `AgentExecutor` interface.
- **`__init__`**:
```python { .no-copy }
2025-06-23 21:34:48 +02:00
--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`**:
```python { .no-copy }
2025-06-23 21:34:48 +02:00
--8<-- "https://raw.githubusercontent.com/a2aproject/a2a-samples/refs/heads/main/samples/python/agents/helloworld/agent_executor.py:HelloWorldAgentExecutor_execute"
```
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
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.