google-adk-a2a

name	google-adk-a2a
description	ADK Agent-to-Agent (A2A) protocol integration. Use when building remote agent communication — exposing ADK agents as A2A servers or connecting to external A2A agents as clients.

Google ADK — Agent-to-Agent (A2A) Protocol

Overview

A2A enables remote agent-to-agent communication over HTTP. ADK agents can:

• Serve as A2A endpoints (other agents call them)
• Call remote A2A agents (as tools)

Install A2A Extension

pip install google-adk[a2a]

Exposing an ADK Agent as A2A Server

CLI Approach

# Start agent as A2A-compatible server
adk api_server my_agent/ --port 8080

Programmatic Approach (to_a2a) — Experimental

from google.adk.agents import Agent
from google.adk.a2a.utils.agent_to_a2a import to_a2a

root_agent = Agent(
    name="weather_service",
    model="gemini-2.5-flash",
    description="Provides weather information for any city.",
    instruction="Answer weather queries accurately.",
    tools=[get_weather],
)

# Convert agent to a Starlette A2A application
app = to_a2a(
    root_agent,
    host="0.0.0.0",
    port=8000,
    protocol="http",
)

# Run with: uvicorn my_agent.agent:app --host 0.0.0.0 --port 8000

to_a2a() parameters:

• agent: The ADK agent to expose
• host: Host for the A2A RPC URL (default: "localhost")
• port: Port for the A2A RPC URL (default: 8000)
• protocol: Protocol for the RPC URL (default: "http")
• agent_card: Optional AgentCard object or path to agent card JSON file
• runner: Optional pre-built Runner (default: creates one with in-memory services)
• lifespan: Optional async context manager for startup/shutdown logic

The A2A agent card is auto-served at /.well-known/agent.json.

Calling a Remote A2A Agent

Use RemoteA2aAgent to connect to an external A2A server:

from google.adk.agents import Agent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# Remote agent as a sub-agent
weather_remote = RemoteA2aAgent(
    name="weather_service",
    description="Remote weather service agent.",
    agent_card="http://weather-service:8080/.well-known/agent.json",
)

coordinator = Agent(
    name="coordinator",
    model="gemini-2.5-flash",
    instruction="Route weather questions to the weather service.",
    sub_agents=[weather_remote],
)

root_agent = coordinator

Agent Card

Every A2A agent exposes a card at /.well-known/agent.json:

{
  "name": "weather_service",
  "description": "Provides weather information for any city.",
  "url": "http://weather-service:8080",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city"
    }
  ]
}

A2A with Authentication

import httpx
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# Pass a pre-configured httpx client with auth headers
client = httpx.AsyncClient(headers={"Authorization": "Bearer your-token"})

secure_agent = RemoteA2aAgent(
    name="secure_service",
    description="A secured remote agent.",
    agent_card="https://secure-service.example.com/.well-known/agent.json",
    httpx_client=client,
)

Multi-Service Architecture

from google.adk.agents import Agent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# Multiple remote services
search_service = RemoteA2aAgent(
    name="search",
    description="Searches documents and returns results.",
    agent_card="http://search-service:8080/.well-known/agent.json",
)

analytics_service = RemoteA2aAgent(
    name="analytics",
    description="Runs analytics queries on data.",
    agent_card="http://analytics-service:8080/.well-known/agent.json",
)

# Local coordinator
root_agent = Agent(
    name="orchestrator",
    model="gemini-2.5-flash",
    instruction="""You coordinate between specialized services.
Use search for finding documents, analytics for data queries.""",
    sub_agents=[search_service, analytics_service],
)

A2A Server with Custom Runner

from google.adk.agents import Agent
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from google.adk.runners import Runner
from google.adk.sessions import DatabaseSessionService
from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService

agent = Agent(
    name="production_service",
    model="gemini-2.5-flash",
    description="Production agent with persistent sessions.",
    instruction="Handle requests reliably.",
    tools=[my_tool],
)

# Custom runner with production services
runner = Runner(
    app_name="production_service",
    agent=agent,
    session_service=DatabaseSessionService(db_url="postgresql+asyncpg://..."),
    artifact_service=InMemoryArtifactService(),
)

app = to_a2a(agent, host="0.0.0.0", port=8000, runner=runner)

A2A Server with Custom Agent Card

from a2a.types import AgentCard
from google.adk.a2a.utils.agent_to_a2a import to_a2a

# Provide a pre-built agent card or path to JSON file
app = to_a2a(agent, agent_card="./agent.json")

# Or pass an AgentCard object directly
app = to_a2a(agent, agent_card=my_agent_card)

Key Concepts

Concept	Description
Agent Card	JSON metadata at /.well-known/agent.json describing the agent
Task	A unit of work sent to an A2A agent
Artifact	Files/data produced by a task
Push Notification	Agent notifies client when async task completes

Key Rules

• A2A is for remote agent communication (HTTP-based)
• For local multi-agent, use sub_agents directly (no A2A needed)
• Agent cards are auto-generated from agent name and description
• RemoteA2aAgent behaves like any other sub-agent to the parent
• A2A supports streaming responses
• Use A2A when agents run as separate services (microservice architecture)
• Authentication via headers for secure cross-service communication

Related Skills

• google-adk-multi-agent — Local multi-agent systems (no A2A needed)
• google-adk-deploy — Deploying A2A services to Cloud Run/GKE