a2a.plugins package¶
Submodules¶
- a2a.plugins.base module
- a2a.plugins.manager module
PluginManagerSequentialPluginManagerSequentialPluginManager.after_client_request()SequentialPluginManager.after_execution()SequentialPluginManager.after_handler_run()SequentialPluginManager.before_client_request()SequentialPluginManager.before_execution()SequentialPluginManager.before_handler_run()SequentialPluginManager.before_push_send()SequentialPluginManager.has_client_hooksSequentialPluginManager.has_execution_hooksSequentialPluginManager.has_push_hooksSequentialPluginManager.has_server_hooksSequentialPluginManager.has_task_hooksSequentialPluginManager.nameSequentialPluginManager.on_execution_event()SequentialPluginManager.on_push_sent()SequentialPluginManager.on_task_event()SequentialPluginManager.plugins
get_global()sequential()set_global()
- a2a.plugins.types module
Module contents¶
Plugins: hooks into the A2A client and DefaultRequestHandlerV2.
Example
from a2a import plugins
- class TaskAudit(plugins.TaskObserverPlugin):
name = ‘task-audit’
- async def on_task_event(self, info: plugins.TaskEventInfo) -> None:
print(info.task_id, info.from_state, ‘->’, info.to_state)
plugins.set_global(plugins.sequential(TaskAudit())) # Create DefaultRequestHandlerV2 and clients after this point.
- class a2a.plugins.ClientPlugin¶
Bases:
PluginHooks around each request made by an A2A Client.
- async after_client_request(response: ClientResponse) None¶
Called with the result, per stream event, and at the end.
- async before_client_request(request: ClientRequest) None¶
Called before the request is sent. Raise to cancel it.
- class a2a.plugins.ClientRequest(method: str, payload: Any, agent_card: AgentCard, context: ClientCallContext)¶
Bases:
objectAn outgoing call, passed to ClientPlugin.before_client_request.
- method¶
Method name, the same as on the server side and as passed to interceptors.
- Type:
str
- payload¶
The request proto. Plugins may replace it.
- Type:
Any
- context¶
The call context.
service_parametersholds the outgoing headers.- Type:
- context: ClientCallContext¶
- method: str¶
- payload: Any¶
- class a2a.plugins.ClientResponse(method: str, payload: Any, context: ClientCallContext, error: BaseException | None = None, is_stream_event: bool = False, is_final: bool = True)¶
Bases:
objectA call result, passed to ClientPlugin.after_client_request.
Follows the same
is_stream_event/is_finalrules as ServerResponse.- method¶
Method name.
- Type:
str
- payload¶
The response or stream event,
Noneon error or stream end.- Type:
Any
- context¶
The same call context passed to before_client_request.
- Type:
- error¶
The exception raised by the call, if any.
- Type:
BaseException | None
- is_stream_event¶
Whether
payloadis one event of a stream.- Type:
bool
- is_final¶
Whether this is the last call for the request.
- Type:
bool
- context: ClientCallContext¶
- error: BaseException | None = None¶
- is_final: bool = True¶
- is_stream_event: bool = False¶
- method: str¶
- payload: Any¶
- class a2a.plugins.CompletePlugin¶
Bases:
ClientPlugin,ServerPluginA plugin with both client and server hooks.
- class a2a.plugins.ExecutionPlugin¶
Bases:
PluginHooks around AgentExecutor.execute, which runs outside the request.
- async after_execution(request_context: RequestContext, error: BaseException | None) None¶
Called in the execution task after the agent returns or raises.
- async before_execution(request_context: RequestContext) None¶
Called in the execution task before the agent runs.
Raise to fail the execution without running the agent.
- async on_execution_event(request_context: RequestContext, event: Event) None¶
Called when the agent enqueues an event, before it is processed.
Observer: runs on the agent’s path, so keep it cheap.
- class a2a.plugins.Plugin¶
Bases:
objectCommon base of all plugins.
- name: str = 'unnamed'¶
Name used in logs.
- class a2a.plugins.PluginManager¶
Bases:
ServerPlugin,ClientPlugin,ExecutionPlugin,TaskObserverPlugin,PushPluginRuns registered plugins. SDK call sites depend on this type.
Since a manager implements every plugin interface, managers can be nested. The
has_*properties let call sites skip all plugin work when no plugin implements the hooks they would call.- property has_client_hooks: bool¶
Whether any plugin implements ClientPlugin.
- property has_execution_hooks: bool¶
Whether any plugin implements ExecutionPlugin.
- property has_push_hooks: bool¶
Whether any plugin implements PushPlugin.
- property has_server_hooks: bool¶
Whether any plugin implements ServerPlugin.
- property has_task_hooks: bool¶
Whether any plugin implements TaskObserverPlugin.
- name: str = 'plugin-manager'¶
Name used in logs.
- class a2a.plugins.PushPlugin¶
Bases:
PluginHooks around each push notification delivery.
- async before_push_send(request: PushRequest) None¶
Called before the webhook request.
May add headers or set
request.skip. Raising fails the delivery.
- async on_push_sent(result: PushResult) None¶
Called after the delivery attempt, or when it was skipped.
- class a2a.plugins.PushRequest(task_id: str, url: str, headers: dict[str, str], event: PushNotificationEvent, skip: bool = False, state: dict[str, Any] = <factory>)¶
Bases:
objectOne push delivery, passed to PushPlugin.before_push_send.
- task_id¶
ID of the task.
- Type:
str
- url¶
Webhook URL.
- Type:
str
- headers¶
Outgoing HTTP headers. Plugins may add or change entries.
- Type:
dict[str, str]
- event¶
The event being pushed.
- Type:
PushNotificationEvent
- skip¶
Set to
Trueto drop this delivery.- Type:
bool
- state¶
Per-delivery plugin state, available again in PushResult.
- Type:
dict[str, Any]
- event: PushNotificationEvent¶
- headers: dict[str, str]¶
- skip: bool = False¶
- state: dict[str, Any]¶
- task_id: str¶
- url: str¶
- class a2a.plugins.PushResult(request: PushRequest, duration_s: float, status_code: int | None, error: BaseException | None, skipped: bool = False)¶
Bases:
objectThe outcome of one push delivery, passed to PushPlugin.on_push_sent.
- request¶
The PushRequest for this delivery.
- duration_s¶
Duration of the HTTP request in seconds.
- Type:
float
- status_code¶
HTTP status code,
Noneif no response was received.- Type:
int | None
- error¶
The exception if delivery failed,
Noneon success.- Type:
BaseException | None
- skipped¶
Whether a plugin dropped the delivery.
- Type:
bool
- duration_s: float¶
- error: BaseException | None¶
- request: PushRequest¶
- skipped: bool = False¶
- status_code: int | None¶
- class a2a.plugins.SequentialPluginManager(*plugins: Plugin)¶
Bases:
PluginManagerRuns plugins one after another in registration order.
before_*hooks run in registration order. If one raises, plugins that already ran get theirafter_*hook with the error, and the exception propagates.after_*hooks run in reverse order. Their exceptions are logged and swallowed.Observer hooks (
on_*) run in registration order. Their exceptions are logged and swallowed.
- async after_client_request(response: ClientResponse) None¶
Called with the result, per stream event, and at the end.
- async after_execution(request_context: RequestContext, error: BaseException | None) None¶
Called in the execution task after the agent returns or raises.
- async after_handler_run(response: ServerResponse) None¶
Called with the handler result, per stream event, and at the end.
- async before_client_request(request: ClientRequest) None¶
Called before the request is sent. Raise to cancel it.
- async before_execution(request_context: RequestContext) None¶
Called in the execution task before the agent runs.
Raise to fail the execution without running the agent.
- async before_handler_run(request: ServerRequest) None¶
Called before the handler processes a request.
Raise to reject the request; the exception is returned to the caller.
- async before_push_send(request: PushRequest) None¶
Called before the webhook request.
May add headers or set
request.skip. Raising fails the delivery.
- property has_client_hooks: bool¶
Whether any plugin implements ClientPlugin.
- property has_execution_hooks: bool¶
Whether any plugin implements ExecutionPlugin.
- property has_push_hooks: bool¶
Whether any plugin implements PushPlugin.
- property has_server_hooks: bool¶
Whether any plugin implements ServerPlugin.
- property has_task_hooks: bool¶
Whether any plugin implements TaskObserverPlugin.
- name: str = 'sequential'¶
Name used in logs.
- async on_execution_event(request_context: RequestContext, event: Event) None¶
Called when the agent enqueues an event, before it is processed.
Observer: runs on the agent’s path, so keep it cheap.
- async on_push_sent(result: PushResult) None¶
Called after the delivery attempt, or when it was skipped.
- async on_task_event(info: TaskEventInfo) None¶
Called after every successful task write.
- class a2a.plugins.ServerPlugin¶
Bases:
PluginHooks around each request handled by DefaultRequestHandlerV2.
- async after_handler_run(response: ServerResponse) None¶
Called with the handler result, per stream event, and at the end.
- async before_handler_run(request: ServerRequest) None¶
Called before the handler processes a request.
Raise to reject the request; the exception is returned to the caller.
- class a2a.plugins.ServerRequest(method: str, payload: Any, context: ServerCallContext, agent_card: AgentCard | None = None)¶
Bases:
objectAn incoming request, passed to ServerPlugin.before_handler_run.
- method¶
Method name, e.g.
'send_message'or'get_task'.- Type:
str
- payload¶
The request proto, e.g.
SendMessageRequest.- Type:
Any
- context¶
The call context. For HTTP transports
state['headers']holds the request headers.- Type:
- context: ServerCallContext¶
- method: str¶
- payload: Any¶
- class a2a.plugins.ServerResponse(method: str, payload: Any, context: ServerCallContext, error: BaseException | None = None, is_stream_event: bool = False, is_final: bool = True)¶
Bases:
objectA handler result, passed to ServerPlugin.after_handler_run.
For a unary call the hook runs once with
is_final=True. For a stream it runs once per event withis_stream_event=True, is_final=Falseand once more withis_final=Trueandpayload=Nonewhen the stream ends, including on error or client disconnect.- method¶
Method name.
- Type:
str
- payload¶
The handler result or stream event,
Noneon error or stream end.- Type:
Any
- context¶
The same call context passed to before_handler_run.
- Type:
- error¶
The exception raised by the handler, if any.
- Type:
BaseException | None
- is_stream_event¶
Whether
payloadis one event of a stream.- Type:
bool
- is_final¶
Whether this is the last call for the request.
- Type:
bool
- context: ServerCallContext¶
- error: BaseException | None = None¶
- is_final: bool = True¶
- is_stream_event: bool = False¶
- method: str¶
- payload: Any¶
- class a2a.plugins.TaskEventInfo(task_id: str, from_state: TaskState | None, to_state: TaskState, event: Event | None, task: Task, context: ServerCallContext)¶
Bases:
objectA successful task write, passed to TaskObserverPlugin.on_task_event.
- task_id¶
ID of the task.
- Type:
str
- from_state¶
Persisted state before the write,
Nonewhen the write created the task.- Type:
TaskState | None
- to_state¶
State after the write. Equal to
from_statefor writes that do not change the state, such as artifact updates.- Type:
- event¶
The event that caused the write,
Nonewhen the SDK wrote the task without one.- Type:
Event | None
- task¶
The task after the write. This is the SDK’s live object; copy it if you keep it beyond the hook call.
- Type:
- context¶
Call context of the request that produced the write.
- Type:
- context: ServerCallContext¶
- task_id: str¶
- class a2a.plugins.TaskObserverPlugin¶
Bases:
PluginObserver of task writes.
- async on_task_event(info: TaskEventInfo) None¶
Called after every successful task write.
- a2a.plugins.get_global() PluginManager¶
Returns the global manager. Empty unless set_global was called.
- a2a.plugins.sequential(*plugins: Plugin) SequentialPluginManager¶
Returns a manager that runs
pluginsin the given order.
- a2a.plugins.set_global(manager: PluginManager) None¶
Sets the manager used by handlers, clients and push senders created afterwards.
DefaultRequestHandlerV2, clients and BasePushNotificationSender capture the manager when they are constructed, so call this once at startup, before creating them.