a2a.server.agent_execution package

Submodules

Module contents

Components for executing agent logic within the A2A server.

class a2a.server.agent_execution.AgentExecutor

Bases: ABC

Agent Executor interface.

Implementations of this interface contain the core logic of the agent, executing tasks based on requests and publishing updates to an event queue.

abstractmethod async cancel(context: RequestContext, event_queue: EventQueue) → None

Request the agent to cancel an ongoing task.

The agent should attempt to stop the task identified by the task_id in the context and publish a TaskStatusUpdateEvent with state TaskState.TASK_STATE_CANCELED to the event_queue.

Parameters:

  • context – The request context containing the task ID to cancel.

  • event_queue – The queue to publish the cancellation status update to.

abstractmethod async execute(context: RequestContext, event_queue: EventQueue) → None

Execute the agent’s logic for a given request context.

The agent should read necessary information from the context and publish Task or Message events, or TaskStatusUpdateEvent / TaskArtifactUpdateEvent to the event_queue. This method should return once the agent’s execution for this request is complete or yields control (e.g., enters an input-required state).

Request Lifecycle & AgentExecutor Responsibilities: - Concurrency: The framework guarantees single execution per request;

execute() will not be called concurrently for the same request context.

  • Exception Handling: Unhandled exceptions raised by execute() will be caught by the framework and result in the task transitioning to TaskState.TASK_STATE_ERROR.

  • Post-Completion: Once execute() completes (returns or raises), the executor must not access the context or event_queue anymore.

  • Terminal States: Before completing the call normally, the executor SHOULD publish a TaskStatusUpdateEvent to transition the task to a terminal state (e.g., TASK_STATE_COMPLETED) or an interrupted state (TASK_STATE_INPUT_REQUIRED or TASK_STATE_AUTH_REQUIRED).

  • Interrupted Workflows:

    • TASK_STATE_INPUT_REQUIRED: The executor publishes a TaskStatusUpdateEvent with TaskState.TASK_STATE_INPUT_REQUIRED and returns to yield control. The request will resume once user input is provided.

    • TASK_STATE_AUTH_REQUIRED: There are in-bound and out-of-bound auth models. In both scenarios, the agent publishes a TaskStatusUpdateEvent with TaskState.TASK_STATE_AUTH_REQUIRED.

      • In-bound: The agent should return from execute(). The framework will call execute() again once the user response is received.

      • Out-of-bound: The agent should not return from execute(). It should wait for the out-of-band auth provider to complete the authentication and then continue execution.

  • Cancellation Workflow: When a cancellation request is received, the async task running execute() is cancelled (raising an asyncio.CancelledError), and cancel() is explicitly called by the framework.

Allowed Workflows: - Immediate response: Enqueue a SINGLE Message object. - Asynchronous/Long-running: Enqueue a Task object, perform work, and emit

multiple TaskStatusUpdateEvent / TaskArtifactUpdateEvent objects over time.

Note that the framework waits with response to the send_message request with return_immediately=True parameter until the first event (Message or Task) is enqueued by AgentExecutor.

Parameters:

  • context – The request context containing the message, task ID, etc.

  • event_queue – The queue to publish events to.

class a2a.server.agent_execution.RequestContext(call_context: ServerCallContext, request: SendMessageRequest | None = None, task_id: str | None = None, context_id: str | None = None, task: Task | None = None, related_tasks: list[Task] | None = None, task_id_generator: IDGenerator | None = None, context_id_generator: IDGenerator | None = None)

Bases: object

Request Context.

Holds information about the current request being processed by the server, including the incoming message, task and context identifiers, and related tasks.

Attaches a related task to the context.

This is useful for scenarios like tool execution where a new task might be spawned.

Parameters:

task – The Task object to attach.

property call_context: ServerCallContext

The server call context associated with this request.

property configuration: SendMessageConfiguration | None

The SendMessageConfiguration from the request, if available.

property context_id: str | None

The ID of the conversation context associated with this task.

property current_task: Task | None

The current Task object being processed.

get_user_input(delimiter: str = '\n') → str

Extracts text content from the user’s message parts.

Parameters:

delimiter – The string to use when joining multiple text parts.

Returns:

A single string containing all text content from the user message, joined by the specified delimiter. Returns an empty string if no user message is present or if it contains no text parts.

property message: Message | None

The incoming Message object from the request, if available.

property metadata: dict[str, Any]

Metadata associated with the request, if available.

property related_tasks: list[Task]

A list of tasks related to the current request.

property requested_extensions: set[str]

Extensions that the client requested for this interaction.

property task_id: str | None

The ID of the task associated with this context.

property tenant: str

The tenant associated with this request.

class a2a.server.agent_execution.RequestContextBuilder

Bases: ABC

Builds request context to be supplied to agent executor.

abstractmethod async build(context: ServerCallContext, params: SendMessageRequest | None = None, task_id: str | None = None, context_id: str | None = None, task: Task | None = None) → RequestContext
class a2a.server.agent_execution.SimpleRequestContextBuilder(should_populate_referred_tasks: bool = False, task_store: TaskStore | None = None, task_id_generator: IDGenerator | None = None, context_id_generator: IDGenerator | None = None)

Bases: RequestContextBuilder

Builds request context and populates referred tasks.

async build(context: ServerCallContext, params: SendMessageRequest | None = None, task_id: str | None = None, context_id: str | None = None, task: Task | None = None) → RequestContext

Builds the request context for an agent execution.

This method assembles the RequestContext object. If the builder was initialized with should_populate_referred_tasks=True, it fetches all tasks referenced in params.message.reference_task_ids from the task_store.

Parameters:

  • context – The server call context, containing metadata about the call.

  • params – The parameters of the incoming message send request.

  • task_id – The ID of the task being executed.

  • context_id – The ID of the current execution context.

  • task – The primary task object associated with the request.

Returns:

An instance of RequestContext populated with the provided information and potentially a list of related tasks.