Skip to content

Commit 09a2221

Browse files
authored
docs: high level active task architecture documentation (a2aproject#1056)
Fixes a2aproject#1032 🦕
1 parent 02a686c commit 09a2221

1 file changed

Lines changed: 34 additions & 0 deletions

File tree

‎src/a2a/server/agent_execution/active_task.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,38 @@
11
# ruff: noqa: TRY301, SLF001
2+
"""Active Task execution and data flow architecture.
3+
4+
This module manages the lifecycle, execution, and data flow of an active A2A task.
5+
6+
High-Level Architecture:
7+
- `AgentExecutor`: An interface with two main methods, `execute(...)` and `cancel(...)`,
8+
responsible for running the core agent logic.
9+
- `ActiveTask`: Coordinates the execution. It runs a main agent loop in `ActiveTask._run_producer()`.
10+
11+
Data Flow and Event Handling:
12+
1. Producer (`ActiveTask._run_producer`):
13+
- Listens for incoming requests from `ActiveTask._request_queue`.
14+
- Acquires `ActiveTask._request_lock` to ensure requests are processed sequentially.
15+
- Calls `AgentExecutor.execute()` passing `ActiveTask._event_queue_agent` as the primary communication channel.
16+
- Enqueues internal lifecycle events (e.g., `_RequestStarted`, `_RequestCompleted`) and
17+
exceptions to the same `ActiveTask._event_queue_agent`.
18+
19+
2. Consumer (`EventConsumer`):
20+
- Consumes events from `ActiveTask._event_queue_agent`.
21+
- Processes all events, updating task state and the database (`TaskManager`).
22+
- Upon receiving `_RequestCompleted`, it releases `ActiveTask._request_lock`, making the producer
23+
ready to process the next queued request.
24+
- Propagates relevant agent updates and state changes to `ActiveTask._event_queue_subscribers`.
25+
- Exception Handling: Re-raises exceptions dequeued from the agent queue, or raises its own validation
26+
errors (e.g., 'Received Message object in task mode.'). In case of failure, it updates the task
27+
state to failed and propagates the exception to `ActiveTask._event_queue_subscribers`.
28+
29+
3. Subscribers (`ActiveTask.subscribe`):
30+
- `ActiveTask._event_queue_subscribers` is not consumed directly. Instead, it is consumed by tapped
31+
queues created within the `ActiveTask.subscribe()` method.
32+
- The `ActiveTask.subscribe()` method is also used to actively run requests, creating a temporary
33+
subscription that yields events and automatically finishes once the request is completed.
34+
"""
35+
236
from __future__ import annotations
337

438
import asyncio

0 commit comments

Comments
 (0)