Remote Agent Communication (A2A)

Overview

The Remote Agent Communication (A2A) module enables distributed multi-agent communication through the Agent-To-Agent (A2A) protocol. It provides a standardized mechanism for agents running in different processes or on different hosts to interact seamlessly using gRPC or HTTP transports. This module facilitates remote agent invocation, event translation between the internal Agent Development Kit (ADK) session event model and the A2A protocol message format, and resolution of remote agent metadata (agent cards).

The A2A protocol enables:

Remote creation and invocation of agents.
Streaming of session events and responses across network boundaries.
Translation between ADK session events and A2A events/messages.
Agent capability discovery via agent cards and skill descriptions.

This module plays a crucial role in enabling scalable, distributed AI agent architectures where agents may delegate work, escalate interactions, or collaborate remotely.

Core Concepts

Agent-To-Agent (A2A) Protocol

The A2A protocol defines a message and event format for communication between AI agents. It supports:

Messages: Contain roles (user or agent) and multiple content parts (text, files, function calls, code, etc.).
Tasks: Represent units of work with states (submitted, working, completed, failed, input required, canceled).
Artifacts: Chunked content associated with tasks (e.g., streaming partial outputs).
Status Updates: Communicate task progress and final states.

The protocol supports streaming responses and incremental updates, allowing agents to communicate asynchronously and handle long-running tasks.

Agent Cards

An Agent Card describes an agent's metadata, including:

Communication endpoint (URL, preferred transport).
Capabilities and supported transports.
Agent skills, derived from the agent's tools, instructions, and workflow structure.

Agent cards enable dynamic discovery and resolution of remote agents before communication.

Session Events and A2A Events

The ADK internally represents agent interactions as session events (session.Event), which include user inputs, model responses, function calls, and other actions.

The A2A protocol uses its own event types (a2a.Event, a2a.Message, etc.).

This module handles bidirectional conversion between these two event representations:

ADK session events → A2A messages and events (for sending to remote agents).
A2A events → ADK session events (for consumption by local agents).

Functional Components

1. A2A Agent Implementation (agent/remoteagent/a2a_agent.go)

This component provides the NewA2A function to create a remote agent proxy that communicates using the A2A protocol. It implements the agent.Agent interface by:

Resolving the remote agent's agent card (from a URL or local file) if not directly provided.
Creating an A2A client for communication using the agent card.
Converting the current invocation context’s session events into an A2A message.
Sending the message to the remote agent via the client, using streaming RPC.
Receiving A2A events from the remote agent, converting them back into ADK session events.
Yielding session events back to the caller, preserving streaming semantics and error handling.

Important points:

On no input events, it yields a single "empty" remote agent event.
Converts function call events specially to maintain correct context and task IDs.
Enhances events with custom metadata containing original A2A request and response for traceability.
Handles errors by yielding error events with descriptive messages.

This allows local agents to delegate requests transparently to remote agents over the network.

2. Event Conversion and Processing (server/adka2a/events.go, server/adka2a/parts.go, server/adka2a/processor.go)

This set of utilities and processors performs the crucial task of translating between ADK session events and A2A protocol events:

EventToMessage converts a session event into an A2A message, preserving roles, content parts, and attaching escalation or transfer actions as metadata.
ToSessionEvent converts an incoming A2A event (task, message, artifact update, status update) into an ADK session event, handling partial updates and marking them accordingly.
Content Part Conversions translate individual pieces of content such as text, function calls, function responses, executable code, files, and code execution results between the genai.Part and a2a.Part representations.
eventProcessor is an executor-side utility that processes ADK session events generated by running an agent, converts them into A2A events, and manages terminal task status updates (completed, failed, input required).
It supports chunked artifact updates with append and last chunk flags.
Tracks escalation or transfer actions and embeds them in final events.

This conversion layer ensures consistent, lossless communication between local and remote agent representations.

3. Executor and Server (server/adka2a/executor.go)

The Executor implements the a2asrv.AgentExecutor interface to run an ADK agent in response to A2A requests:

It receives an A2A message from the network as input.
Converts the message to ADK content.
Creates a new runner.Runner to execute the configured agent.
Manages session creation or retrieval to maintain state.
Streams session events as A2A artifact update events back to the caller.
Sends appropriate terminal task status updates based on success, failure, or input requirements.
Supports cancellation requests by sending a canceled task status update.

This executor is the server-side bridge that wraps local ADK agents behind A2A protocol endpoints.

4. Agent Skill Building (server/adka2a/agent_card.go)

This component constructs agent skill descriptions to be included in agent cards:

Extracts primary skills from the agent, including LLM instruction descriptions and tools.
Recursively gathers skills for sub-agents (workflow agents like loop, parallel, sequential).
Builds human-readable descriptions for these skills, replacing pronouns for natural language clarity.
Tags skills by agent type (llm_agent, workflow, custom_agent).
Provides metadata that clients use to understand agent capabilities when discovering agents dynamically.

This supports rich discovery and delegation scenarios where agents can advertise their abilities over A2A.

Interaction Between Components

The flow of communication and transformation in A2A remote agent communication is as follows:

Local Agent Invocation:
The local ADK agent invokes the remote agent using the a2aAgent implementation (NewA2A).
Agent Card Resolution:
The remote agent's metadata (agent card) is fetched or loaded to configure the A2A client.
Session Events to A2A Message:
The local invocation context's session events (user messages, function calls) are converted into an A2A message payload.
Message Sent Over Network:
The A2A client sends the message to the remote agent's gRPC or HTTP endpoint.
Remote Agent Executor:
The remote server receives the A2A message, converts it to ADK content, and executes the configured agent using the Executor.
Session Events Produced:
The agent produces session events (responses, function calls, outputs).
Session Events to A2A Events:
The eventProcessor converts these session events into A2A events, including chunked artifact updates and status updates.
Streaming Response:
The remote server streams these A2A events back to the client.
Client Converts to Session Events:
The a2aAgent client converts incoming A2A events into ADK session events.
Returning Results:
The local invocation receives these events as a stream, integrating them seamlessly.

Key Design Patterns and Approaches

Streaming Bidirectional Communication: Supports asynchronous, incremental event streaming for scalability and responsiveness.
Event Translation Layer: Abstracts differences between ADK’s session event model and A2A protocol messages, ensuring interoperability.
Agent Card Metadata: Decouples agent discovery from invocation, allowing dynamic resolution and flexible deployment.
Composable Agent Skill Extraction: Provides detailed capability metadata for agents including nested sub-agents.
Error Propagation as Events: Errors in communication or execution are surfaced as special session events, preserving the event stream contract.
Contextual Event Presentation: Events from other agents are rephrased as user context messages to maintain clarity in conversations.
Long-Running Tool Identification: Tracks function calls that represent long-running operations for proper input-required signaling.

Visualizing Remote Agent Communication Flow

sequenceDiagram
participant LocalAgent as Local Agent (ADK)
participant A2AClient as A2A Client (a2aclient)
participant RemoteServer as Remote Agent Server (A2A Executor)
participant RemoteAgent as Remote Agent (ADK)
LocalAgent->>A2AClient: Resolve Agent Card
LocalAgent->>A2AClient: Convert Session Events to A2A Message
A2AClient->>RemoteServer: Send A2A Message (gRPC/HTTP)
RemoteServer->>RemoteAgent: Convert A2A Message to ADK Content
RemoteAgent->>RemoteAgent: Run Agent with Content
RemoteAgent->>RemoteServer: Produce Session Events
RemoteServer->>RemoteServer: Convert Session Events to A2A Events
RemoteServer-->>A2AClient: Stream A2A Events (Artifact Updates, Status)
A2AClient->>LocalAgent: Convert A2A Events to Session Events
LocalAgent->>LocalAgent: Process Remote Agent Events

Summary of Relevant Files and Their Roles

File	Role
agent/remoteagent/a2a_agent.go	Implements the remote agent proxy using the A2A protocol, handling invocation, messaging, and event translation.
agent/remoteagent/utils.go	Utility functions for event inspection, session event conversion, and contextual presentation of remote agent messages.
server/adka2a/events.go	Conversion functions between ADK session events and A2A protocol events; manages metadata and action flags.
server/adka2a/parts.go	Converts message content parts between ADK genai.Part and A2A parts, including text, code, function calls, and files.
server/adka2a/processor.go	Processes ADK session events during agent execution, translates to A2A artifact updates and status events, manages terminal event logic.
server/adka2a/executor.go	Implements the A2A server executor that receives A2A requests, runs the configured ADK agent, and streams back A2A events.
server/adka2a/agent_card.go	Builds detailed agent skill metadata for agent cards, enabling capability discovery and dynamic resolution.

Interaction with Other Topics

The A2A Agent Implementation interacts closely with the Executor and Server components to send and receive messages over the network.
The Event Conversion and Processing subtopic provides the backbone for translating events bidirectionally, supporting the A2A Agent Implementation and Executor.
Agent Skill Building enhances agent metadata exposed by the A2A protocol, enabling clients to understand remote agent capabilities.
This module integrates with the core Agent Framework for session and invocation context management.
It supports distributed workflows and remote delegation, complementing Agent Workflow Management and Session Management.
The remote protocol enables agents to interact over the network, facilitating scenarios implemented in REST API and Web Launchers.

Refer to [A2A Agent Implementation](/agent/remoteagent/a2a_agent.go), [Event Conversion and Processing](/server/adka2a/events.go), [Executor and Server](/server/adka2a/executor.go), and [Agent Skill Building](/server/adka2a/agent_card.go) for detailed explanations of their implementation and interactions.

This detailed explanation covers the purpose, functionality, and interaction of components within the Remote Agent Communication (A2A) module, illustrating its role in enabling distributed multi-agent communication within the system.