API and A2A Sublaunchers

Purpose

The API and A2A Sublaunchers subtopic addresses the integration of two distinct but complementary communication protocols into the web server launcher framework: the REST API and the Agent-to-Agent (A2A) protocol. While the parent topic REST API and Web Launchers broadly implements REST API servers, HTTP routing, and embedded web UI launchers for agent interaction, this subtopic focuses specifically on the modular sublaunchers that enable the web server to serve these protocols independently or together.

This modularization allows the web server launcher to flexibly incorporate:

• A RESTful HTTP API for client applications and web UIs to communicate with agents.

• An A2A server that enables distributed multi-agent communication using JSON-RPC over HTTP, supporting remote agent invocation and inter-agent protocol compliance.

By separating these concerns into sublaunchers, the system can selectively activate or configure each protocol based on command-line arguments or deployment needs, improving maintainability and extensibility.

Functionality

REST API Sublauncher

The REST API sublauncher encapsulates the setup of the ADK REST API server at the /api/ URL path. Key functions include:

• Command-line configuration: Enables specifying the allowed CORS origin (usually the web UI address) to permit cross-origin requests securely.

• Router integration: Registers the REST API handler under /api/ on the main HTTP router, ensuring all REST endpoints for runtime, sessions, apps, artifacts, and debug APIs are exposed.

• CORS middleware: Injects CORS headers dynamically to allow safe requests from authorized frontends, handling preflight OPTIONS requests to comply with browser security.

A snippet illustrating the router setup and CORS wrapping:

apiHandler := adkrest.NewHandler(config)
corsHandler := corsWithArgs(a.config.frontendAddress)(apiHandler)
router.Methods("GET", "POST", "DELETE", "OPTIONS").PathPrefix("/api/").Handler(
	http.StripPrefix("/api", corsHandler),
)

This setup ensures the REST API is accessible under /api/, with all requests checked for proper origin.

A2A Protocol Sublauncher

The A2A sublauncher integrates the Agent-to-Agent protocol server into the web server launcher, enabling remote agent communication and distributed agent invocation workflows. Key aspects:

• Agent Card Publication: Serves a static agent card at a well-known path (/.well-known/agentcard) describing the root agent's capabilities, skills, supported transports, and invocation URL. This card is essential for A2A clients to discover and interact with the agent.

• JSON-RPC Endpoint: Registers a JSON-RPC handler at /a2a/invoke that listens for incoming A2A protocol requests, delegating them to a configured executor that runs the root agent within the ADK framework.

• Configurable Agent URL: Allows specifying the public-facing URL for the agent to advertise in its agent card, ensuring clients can locate the A2A endpoint.

Example code registering the agent card and JSON-RPC endpoint:

router.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(agentCard))
router.Handle(apiPath, a2asrv.NewJSONRPCHandler(reqHandler))

Shared Characteristics

Both sublaunchers:

• Implement the web.Sublauncher interface, allowing them to be plugged into the web server launcher command-line and runtime environment.

• Provide user feedback messages describing how to access their services.

• Support independent configuration and parsing of flags, enabling flexible deployment.

Integration with Parent Topic and Other Subtopics

The API and A2A sublaunchers extend the functionality of the parent topic REST API and Web Launchers by providing concrete implementations of sublaunchers that can be started alongside or separately from the embedded web UI launcher and routing setup subtopics.

• The REST API sublauncher relies on the REST API controllers and router setup subtopics to handle specific HTTP endpoints and routing logic.

• The A2A sublauncher depends on the remote agent communication implementations from Remote Agent Communication (A2A) to serialize and deserialize A2A events and messages.

• Both sublaunchers use the agent runner and session/artifact services to execute agents and manage session state transparently.

• They complement the Web Server Launcher subtopic by acting as modular components that the web server launcher orchestrates based on command-line arguments.

This modular design enables the web server launcher to act as a unified entry point supporting multiple interaction paradigms (REST API, A2A, Web UI), each with isolated concerns but shared underlying agent execution logic.

sequenceDiagram
participant User
participant WebServerLauncher
participant APISublauncher
participant A2ASublauncher
participant Router
participant AgentRunner
participant Agent
User->>WebServerLauncher: Launch with flags (api, a2a, webui)
WebServerLauncher->>APISublauncher: Initialize REST API sublauncher
WebServerLauncher->>A2ASublauncher: Initialize A2A sublauncher
APISublauncher->>Router: Register /api/ routes with CORS
A2ASublauncher->>Router: Register /.well-known/agentcard and /a2a/invoke
User->>Router: HTTP REST Request (/api/...)
Router->>APISublauncher: Handle REST API request
APISublauncher->>AgentRunner: Execute agent logic
User->>Router: JSON-RPC Request (/a2a/invoke)
Router->>A2ASublauncher: Handle A2A JSON-RPC request
A2ASublauncher->>AgentRunner: Execute agent logic
AgentRunner->>Agent: Invoke agent with input
Agent-->>AgentRunner: Return response/events
AgentRunner-->>APISublauncher/A2ASublauncher: Return results
APISublauncher/A2ASublauncher-->>User: Return HTTP response

This sequence diagram illustrates the lifecycle from user request through the web server launcher to the sublaunchers and ultimately the agent execution, highlighting how the API and A2A sublaunchers integrate seamlessly with routing and agent execution layers.