A2A Agent Implementation

Purpose

Within the broader scope of enabling distributed multi-agent communication via the Agent-To-Agent (A2A) protocol (Remote Agent Communication (A2A)), the A2A Agent Implementation subtopic specifically addresses how a local agent can act as a client interface to a remote agent over the A2A protocol. This implementation abstracts the communication details and protocol handling, enabling seamless invocation of remote agents as if they were local, thus facilitating distributed AI workflows and multi-agent orchestration across different hosts or processes.

This subtopic fills the gap between the low-level protocol operations handled in other subtopics (like message translation and server execution) and the high-level agent framework, providing a concrete agent.Agent implementation that integrates with the ADK agent lifecycle and session model.

Functionality

The A2A Agent Implementation provides:

Remote Agent Interface: Implements the agent.Agent interface, presenting a local proxy that marshals session events into the A2A protocol messages and sends them over HTTP/gRPC to the remote agent.
Agent Card Resolution: Supports dynamic resolution of the remote agent's AgentCard metadata from either a provided local JSON file or an HTTP(S) URL. This allows flexible discovery and configuration of remote agents without hardcoding transport details.
Message Construction: Converts the invocation context's session events into an A2A protocol Message. It intelligently detects whether the last event corresponds to a user function call to ensure correct message framing, or it builds a message from missing parts of the remote session when starting a new interaction.
Streaming Event Handling: Sends the constructed A2A message to the remote agent using a streaming client. It yields back the sequence of session events converted from the remote A2A events, supporting incremental and asynchronous event processing.
Error Propagation: Wraps any errors encountered during card resolution, client creation, message construction, or remote invocation into session events with appropriate error metadata, allowing upstream components to handle errors gracefully.
Custom Metadata Enrichment: Enhances session events with custom metadata fields containing the original request and response A2A messages, facilitating debugging and telemetry integration.

Key Workflow Outline

Agent Card Resolution:
- If an AgentCard is directly provided in config, use it.
- Otherwise, fetch and parse the card from a URL or load from a local file.
Client Creation:
- Use a client factory or default constructor to create an A2A client based on the resolved agent card.
Message Creation:
- Examine the invocation context’s session events.
- If the last event is a user function call, convert it to an A2A message.
- Otherwise, build a message representing missing parts of the remote session.
Message Sending and Response Streaming:
- Send the message via the A2A client using a streaming API.
- For each streamed A2A event response:
  - Convert it back into an ADK session event.
  - Yield the event to the caller.
  - Attach custom metadata with request/response details.
Error Handling:
- On any failure, yield a special error event with error details embedded.

Critical Code Snippet Illustrating Message Sending Loop

for a2aEvent, err := range client.SendStreamingMessage(ctx, req) {
    if err != nil {
        yield(toErrorEvent(ctx, err), nil)
        return
    }
    event, err := adka2a.ToSessionEvent(ctx, a2aEvent)
    if err != nil {
        yield(toErrorEvent(ctx, err), nil)
        return
    }
    if event == nil {
        continue
    }
    updateCustomMetadata(event, req, a2aEvent)
    if !yield(event, nil) {
        break
    }
}

This loop continuously receives streaming responses from the remote agent, converts them into session events, and yields them to the ADK framework.

Integration

The A2A Agent Implementation acts as a bridge between:

The local agent framework (AI Agent Framework), by implementing the agent.Agent interface and participating in the invocation lifecycle with session and event context.
The A2A protocol client stack (Remote Agent Communication (A2A)), by using the a2aclient package to send and receive protocol messages.

It complements other subtopics such as:

Event Conversion and Processing: Handles conversion between ADK session events and A2A protocol events; while this subtopic uses that conversion functionality to construct and interpret protocol messages.
Executor and Server: While the executor subtopic runs agents on the server side and manages event queues, this subtopic focuses on the client side, sending requests and receiving streamed responses.
Agent Skill Building: Supplies skill descriptors for remote agents; the implementation here enables invoking those remote skills seamlessly.

By encapsulating remote communication details, this subtopic enables higher-level agents and workflows to delegate tasks transparently to remote agents, supporting distributed AI system designs.

Diagram

sequenceDiagram
participant LocalAgent as Local A2A Agent
participant Client as A2A Client
participant RemoteAgent as Remote A2A Agent Server
LocalAgent->>LocalAgent: Resolve AgentCard (URL/File)
LocalAgent->>Client: Create client from AgentCard
LocalAgent->>LocalAgent: Convert InvocationContext events to A2A Message
LocalAgent->>Client: SendStreamingMessage(Message)
Client->>RemoteAgent: Transmit A2A Message (gRPC/HTTP)
RemoteAgent->>RemoteAgent: Process message, generate events
RemoteAgent->>Client: Stream A2A Events (responses)
Client->>LocalAgent: Receive streamed events
LocalAgent->>LocalAgent: Convert A2A Events to Session Events
LocalAgent->>Caller: Yield session events (stream)

This sequence diagram visualizes how the A2A Agent Implementation resolves the remote agent card, creates a client, converts session events into protocol messages, streams requests to the remote agent, receives streaming responses, converts them back, and yields events to the caller within the local agent framework.