docs: high level active task architecture documentation

[bartek-w]

Fixes #1032 🦕

[github-actions]

🧪 Code Coverage (vs main)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/server/events/event_queue_v2.py	91.19%	91.71%	🟢 +0.52%
src/a2a/utils/telemetry.py	90.63%	91.41%	🟢 +0.78%
Total	93.03%	93.06%	🟢 +0.02%

Generated by coverage-comment.yml

[gemini-code-assist]

Code Review

This pull request adds a comprehensive module-level docstring to active_task.py explaining the architecture and data flow of the active task execution system. A critical issue was identified in the described logic: a potential deadlock exists because the _request_lock is only released upon receiving a _RequestCompleted event, which may not be enqueued if an exception occurs during agent execution.

I am having trouble creating individual review comments. Click here to see my feedback.

src/a2a/server/agent_execution/active_task.py (22-23)

The documentation states that _request_lock is released upon receiving _RequestCompleted. However, in the current implementation, if an exception occurs during agent execution, _RequestCompleted is never enqueued (see _run_producer logic), and the EventConsumer catches the exception without releasing the lock. This leads to a deadlock where no further requests can be processed by this ActiveTask. Consider ensuring the lock is released in the exception handling path of the consumer, or allow the exception to bubble up to a higher-level cleanup block if one is provided in accordance with repository standards.

References

1. Resource acquisition before a try...finally block is acceptable if a higher-level try...finally guarantees cleanup of all task-level resources, and exceptions do not necessarily need to be caught locally if such a cleanup mechanism exists.

Resolved: Working as intended: Once task get to final state (failed in this case) no more requests are processed. subscribe() will exit due to QueueShutDown exception.