a2a.go

Overview

The a2a.go file implements an Agent-to-Agent (A2A) sublauncher that integrates A2A capabilities into the web server framework. It extends the web launcher system by adding HTTP endpoints for distributed multi-agent communication using the A2A protocol. This includes serving a static agent card describing the root agent's capabilities and exposing a JSON-RPC handler for A2A invocations.

The A2A sublauncher enables clients or other agents to invoke the local agent remotely via the A2A protocol over HTTP. It acts as a bridge between the internal agent execution framework and external distributed workflows, supporting streaming and JSON-RPC communication.

This file is part of the broader API and A2A Sublaunchers topic under the REST API and Web Launchers module, focusing on modular extensions of the web server for agent interaction protocols.

Types and Structures

a2aConfig

type a2aConfig struct {
	agentURL string // Public URL advertised in the agent card for A2A invocation endpoint
}

• Holds configuration parameters for the A2A sublauncher.

• agentURL is the externally visible URL used by clients to invoke A2A interactions. It defaults to http://localhost:8080 but can be overridden via a command-line flag.

a2aLauncher

type a2aLauncher struct {
	flags  *flag.FlagSet  // Command-line flag parser specific to this sublauncher
	config *a2aConfig     // Configuration instance with parsed flag values
}

• Implements the web.Sublauncher interface, allowing the A2A functionality to be plugged into the web server launcher.

• Manages flag parsing, configuration, router setup, and user messaging for the A2A server.

Functions and Methods

NewLauncher() web.Sublauncher

func NewLauncher() web.Sublauncher

• Factory function that creates and returns a new instance of a2aLauncher.

• Initializes an a2aConfig and sets up a flag.FlagSet for parsing the -a2a_agent_url command-line flag.

• The a2a_agent_url flag specifies the public A2A host URL advertised in the agent card.

• Usage example:

launcher := a2a.NewLauncher()

(a *a2aLauncher) CommandLineSyntax() string

func (a *a2aLauncher) CommandLineSyntax() string

• Returns a formatted string describing the command-line flags accepted by the A2A launcher.

• Used by the web server launcher to inform users about available flags.

(a *a2aLauncher) Keyword() string

func (a *a2aLauncher) Keyword() string

• Returns the keyword "a2a" which identifies this sublauncher in command-line arguments.

(a *a2aLauncher) Parse(args []string) ([]string, error)

func (a *a2aLauncher) Parse(args []string) ([]string, error)

• Parses command-line arguments specific to the A2A launcher using the internal flag.FlagSet.

• Returns the remaining unparsed arguments after flag parsing or an error if parsing fails.

• Example usage during startup:

args, err := a2aLauncher.Parse(os.Args[1:])
if err != nil {
    // handle error
}

(a *a2aLauncher) SetupSubrouters(router *mux.Router, config *launcher.Config) error

func (a *a2aLauncher) SetupSubrouters(router *mux.Router, config *launcher.Config) error

• Integrates the A2A sublauncher into the main HTTP router by registering required endpoints.

• Builds the public A2A invocation URL by joining the configured agentURL and the fixed apiPath (/a2a/invoke).

• Retrieves the root agent from the launcher config's AgentLoader.

• Constructs an AgentCard describing the root agent with:

  • Name, description

  • Supported input/output modes (text/plain)

  • URL set to the public A2A invocation endpoint

  • Preferred transport protocol (jsonrpc)

  • Agent skills built using adka2a.BuildAgentSkills

  • Streaming capability enabled

• Registers:

  • A static HTTP handler serving the agent card at /.well-known/agentcard.

  • A JSON-RPC handler at /a2a/invoke that delegates requests to an executor running the root agent.

• Returns any error encountered during URL building or setup.

This method is the core integration point where the A2A protocol is exposed over HTTP.

(a *a2aLauncher) SimpleDescription() string

func (a *a2aLauncher) SimpleDescription() string

• Returns a short description of the A2A launcher for user help messages.

• Indicates the JSON-RPC path where the A2A server listens.

(a *a2aLauncher) UserMessage(webUrl string, printer func(v ...any))

func (a *a2aLauncher) UserMessage(webUrl string, printer func(v ...any))

• Prints a user-facing message to the console or log upon server startup.

• Shows the URL where the A2A JSON-RPC protocol can be accessed.

Important Implementation Details

• Agent Card Publication: The agent card contains metadata about the root agent, including its skills and capabilities, and is served at the well-known path /.well-known/agentcard. This allows A2A clients to discover the agent and understand how to interact with it.

• JSON-RPC Handling: The /a2a/invoke endpoint accepts JSON-RPC requests, which are handled by an a2asrv.Handler backed by an adka2a.Executor. The executor runs the root agent within the ADK's runner framework, managing session, artifact, and execution state.

• Configuration via Flags: The agent URL advertised in the agent card can be customized via the -a2a_agent_url flag to support deployments behind proxies or with external addressing.

• Use of mux.Router: The sublauncher integrates seamlessly with the main HTTP router used by the web server launcher, enabling coexistence with other sublaunchers such as the REST API or Web UI.

• Streaming Support: The agent capabilities advertise streaming support (Streaming: true), enabling clients to receive incremental event updates during agent invocation.

Interaction with Other Parts of the System

• Web Server Launcher: Implements the web.Sublauncher interface, making it compatible with the main web server launcher that manages multiple sublaunchers and routes.

• Agent Loader & Runner: Uses config.AgentLoader.RootAgent() to get the root agent and adka2a.NewExecutor to create an executor that runs the agent logic for A2A requests. This ties into the core Agent Execution Runner and Agent Lifecycle and Callbacks.

• Agent Card and Skills: Leverages a2acore.AgentCard and adka2a.BuildAgentSkills to expose agent capabilities compliant with the Remote Agent Communication (A2A) protocol.

• Routing and Handlers: Uses github.com/gorilla/mux for HTTP routing and a2asrv package for serving the agent card and JSON-RPC handlers, consistent with REST API and Web Launchers.

• Session and Artifact Services: The executor is configured with session and artifact services from the launcher config, enabling stateful agent execution and artifact management as described in Session Management and Artifact Management.

Usage Example

To run the A2A sublauncher as part of the web server, the command-line might include:

./server -a2a -a2a_agent_url="https://myagent.example.com"

This configures the A2A server to advertise its public endpoint as https://myagent.example.com/a2a/invoke. Clients can then query https://myagent.example.com/.well-known/agentcard to retrieve agent capabilities and invoke agents via JSON-RPC at /a2a/invoke.

Visual Diagram: A2A Sublauncher Structure and Workflow

classDiagram
class a2aLauncher {
-flags
-config
+CommandLineSyntax()
+Keyword()
+Parse()
+SetupSubrouters()
+SimpleDescription()
+UserMessage()
}
class a2aConfig {
-agentURL
}
a2aLauncher --> a2aConfig
a2aLauncher ..> mux.Router : SetupSubrouters(router)
a2aLauncher ..> adka2a.Executor : creates executor
a2aLauncher ..> a2asrv.Handler : creates JSON-RPC handler
a2aLauncher ..> a2acore.AgentCard : builds static agent card

Summary of Key Constants and Variables

References to Related Topics

• The implementation depends on the Remote Agent Communication (A2A) topic for protocol details, agent card schema, and event translation.

• Uses REST API and Web Launchers interfaces and patterns for integration into the web server launcher framework.

• Relies on the Agent Execution Runner and Agent Lifecycle and Callbacks to execute agents invoked via A2A.

• Integrates with session and artifact services from Session Management and Artifact Management to maintain agent state and data persistence during invocation.

This file is a critical component enabling distributed, protocol-compliant remote agent invocation, enhancing the system’s ability to operate in multi-agent, networked environments.