Tasks & Push
A2A models every conversation as a Task with a server-side lifecycle. ag2.a2a.tasks exposes helpers for inspecting and aborting tasks; ag2.a2a.push manages webhook subscriptions for asynchronous delivery of task updates. All helpers accept an A2AConfig and work over any transport the server's card declares.
Tasks#
Listing#
list_tasks returns a ListedTasks dataclass — the page's tasks plus the server-reported pagination metadata (next_page_token, page_size, total_size). Pagination is handled by the caller — pass page_token from a prior response back in to advance.
| Argument | Purpose |
|---|---|
tenant | Scope the call to a specific tenant on a shared backend |
context_id | Filter to a single conversation context |
status | Filter by TaskState enum value (e.g. TaskState.TASK_STATE_WORKING) |
page_size / page_token | Caller-driven pagination |
history_length | Server-side hint to truncate echoed Task.history |
include_artifacts | Include task artifacts in the response (default: False) |
status_timestamp_after | Filter to tasks whose status timestamp is after this datetime |
Fetching a Single Task#
history_length is a hint — some server versions ignore it and return the full history. Don't rely on it for security boundaries.
Cancelling#
metadata is forwarded to the server's cancel handler — useful for auditing who cancelled what and why. Already-terminal tasks (COMPLETED, FAILED, etc.) are refused with TaskNotCancelableError, and an AG2 server refuses the same way when the task finishes on its own while the cancel is in flight; surface the exception, don't paper over it.
Push Notifications#
A2A push notifications let the server POST task updates to a webhook the client registered ahead of time — useful when the client doesn't want to hold an open SSE stream for the whole task lifetime.
Note
The server must be constructed with a push_config_store for push CRUD to work. The default A2AServer(agent) does not enable push. See Server → What A2AServer Holds.
Warning
Push configs live in the push store, not the task store. With several server replicas the default in-memory push store is per-replica, so a webhook registered on one replica is not seen by another. See Server → Running on Several Replicas.
Webhooks Across Server Replicas#
The push config store decides where registered webhooks live. The default InMemoryPushNotificationConfigStore keeps them in one process, so with several replicas a task that finishes on a replica that never saw the registration sends nothing and raises no error. To share them, pass the SDK's database store (built on the same engine as the task store) and a sender that reads it:
task_store and event_stream come from Server → Running on Several Replicas.
Registering a Webhook#
A2APushAuthentication round-trips scheme / credentials through the wire format without loss. Receiving handlers verify these against the inbound request.
Reading and Deleting#
| Helper | Purpose |
|---|---|
create_push_notification_config | Register a webhook for a task |
get_push_notification_config | Fetch a single config by id |
list_push_notification_configs | List configs registered for a task (paginated) |
delete_push_notification_config | Remove a registered config |
Multi-tenant Scoping#
Both modules accept a per-call tenant=... kwarg that overrides the tenant baked into A2AConfig for that single request. Per-call overrides are also available via context.variables["a2a:tenant"] — useful when a single client serves multiple tenants on the same shared backend.