a2a.server.routes package

Submodules

• a2a.server.routes.agent_card_routes module
  • create_agent_card_routes()
• a2a.server.routes.common module
  • DefaultServerCallContextBuilder
    • DefaultServerCallContextBuilder.build()
    • DefaultServerCallContextBuilder.build_user()
  • ServerCallContextBuilder
    • ServerCallContextBuilder.build()
  • StarletteUser
    • StarletteUser.is_authenticated
    • StarletteUser.user_name
  • create_event_source_response()
  • serialize_list_tasks_response()
• a2a.server.routes.fastapi_routes module
  • add_a2a_routes_to_fastapi()
• a2a.server.routes.jsonrpc_dispatcher module
  • JsonRpcDispatcher
    • JsonRpcDispatcher.METHOD_TO_MODEL
    • JsonRpcDispatcher.handle_requests()
• a2a.server.routes.jsonrpc_routes module
  • create_jsonrpc_routes()
• a2a.server.routes.rest_dispatcher module
  • A2AJSONResponse
    • A2AJSONResponse.media_type
  • RestDispatcher
    • RestDispatcher.delete_push_notification()
    • RestDispatcher.get_push_notification()
    • RestDispatcher.handle_authenticated_agent_card()
    • RestDispatcher.list_push_notifications()
    • RestDispatcher.list_tasks()
    • RestDispatcher.on_cancel_task()
    • RestDispatcher.on_get_task()
    • RestDispatcher.on_message_send()
    • RestDispatcher.on_message_send_stream()
    • RestDispatcher.on_subscribe_to_task()
    • RestDispatcher.set_push_notification()
• a2a.server.routes.rest_routes module
  • create_rest_routes()

Module contents

A2A Routes.

class a2a.server.routes.DefaultServerCallContextBuilder

Bases: ServerCallContextBuilder

A default implementation of ServerCallContextBuilder.

build(request: Request) → ServerCallContext

Builds a ServerCallContext from a Starlette Request.

Parameters:

request – The incoming Starlette Request object.

Returns:

A ServerCallContext instance populated with user and state information from the request.

build_user(request: Request) → User

Builds a User from a Starlette Request.

Parameters:

request – The incoming Starlette Request object.

Returns:

A User instance populated with user information from the request.

class a2a.server.routes.ServerCallContextBuilder

Bases: ABC

A class for building ServerCallContexts using the Starlette Request.

abstractmethod build(request: Request) → ServerCallContext

Builds a ServerCallContext from a Starlette Request.

a2a.server.routes.add_a2a_routes_to_fastapi(app: FastAPI, *, agent_card_routes: Sequence[BaseRoute] | None = None, jsonrpc_routes: Sequence[BaseRoute] | None = None, rest_routes: Sequence[BaseRoute] | None = None) → None

Mounts A2A routes on a FastAPI app and enriches them for /docs.

Re-registers Starlette routes as APIRoute instances so they appear in the auto-generated OpenAPI schema, tagged and annotated with proto-derived request-body schemas.

Usage:

app = FastAPI()
add_a2a_routes_to_fastapi(
    app,
    agent_card_routes=create_agent_card_routes(agent_card),
    jsonrpc_routes=create_jsonrpc_routes(request_handler, rpc_url='/'),
    rest_routes=create_rest_routes(request_handler),
)

Parameters:

• app – The FastAPI application to mount the routes on.

• agent_card_routes – Routes returned by create_agent_card_routes.

• jsonrpc_routes – Routes returned by create_jsonrpc_routes.

• rest_routes – Routes returned by create_rest_routes.

a2a.server.routes.create_agent_card_routes(agent_card: AgentCard, card_modifier: Callable[[AgentCard], Awaitable[AgentCard]] | None = None, card_url: str = '/.well-known/agent-card.json', cache_control: str | None = None) → list[Route]

Creates the Starlette Route for the A2A protocol agent card endpoint.

Parameters:

• agent_card – The AgentCard to serve.

• card_modifier – Optional callback to adjust the card per request.

• card_url – Path the card is served from.

• cache_control – Value for the Cache-Control response header, e.g. 'public, max-age=3600'. A max-age has to suit the agent’s expected update frequency, which only the deployment knows, so there is no default. The ETag is sent either way, and revalidating against it costs one 304.

a2a.server.routes.create_jsonrpc_routes(request_handler: RequestHandler, rpc_url: str, context_builder: ServerCallContextBuilder | None = None, enable_v0_3_compat: bool = False, shutdown_grace_period: float = 0) → list[Route]

Creates the Starlette Route for the A2A protocol JSON-RPC endpoint.

Handles incoming JSON-RPC requests, routes them to the appropriate handler methods, and manages response generation including Server-Sent Events (SSE).

Parameters:

• request_handler – The handler instance responsible for processing A2A requests via http.

• rpc_url – The URL prefix for the RPC endpoints. Should start with a leading slash ‘/’.

• context_builder – The ServerCallContextBuilder used to construct the ServerCallContext passed to the request_handler. If None the DefaultServerCallContextBuilder is used.

• enable_v0_3_compat – Whether to enable v0.3 backward compatibility on the same endpoint.

• shutdown_grace_period – Seconds to allow active SSE streams to finish before force-cancellation during shutdown. This value should be less than the ASGI server’s graceful shutdown timeout. Defaults to 0, matching the sse-starlette default behavior.

a2a.server.routes.create_rest_routes(request_handler: RequestHandler, context_builder: ServerCallContextBuilder | None = None, enable_v0_3_compat: bool = False, path_prefix: str = '', shutdown_grace_period: float = 0) → list[BaseRoute]

Creates the Starlette Routes for the A2A protocol REST endpoint.

Parameters:

• request_handler – The handler instance responsible for processing A2A requests via http.

• context_builder – The ServerCallContextBuilder used to construct the ServerCallContext passed to the request_handler. If None the DefaultServerCallContextBuilder is used.

• enable_v0_3_compat – If True, mounts backward-compatible v0.3 protocol endpoints using REST03Adapter.

• path_prefix – The URL prefix for the REST endpoints.

• shutdown_grace_period – Seconds to allow active SSE streams to finish before force-cancellation during shutdown. This value should be less than the ASGI server’s graceful shutdown timeout. Defaults to 0, matching the sse-starlette default behavior.