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.

60 lines
3.4 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"
```
When a `message/send` or `message/stream` request comes in (both are handled by `execute` in this simplified executor):
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
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.
```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_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.