Saltar a contenido

Inicio Rápido: Consumir un agente remoto mediante A2A

Soportado en ADKGoExperimental

Este inicio rápido cubre el punto de partida más común para cualquier desarrollador: "Hay un agente remoto, ¿cómo hago que mi agente ADK lo use mediante A2A?". Esto es crucial para construir sistemas complejos multi-agente donde diferentes agentes necesitan colaborar e interactuar.

Descripción General

Este ejemplo demuestra la arquitectura Agent-to-Agent (A2A) en el Agent Development Kit (ADK), mostrando cómo múltiples agentes pueden trabajar juntos para manejar tareas complejas. El ejemplo implementa un agente que puede lanzar dados y verificar si los números son primos.

┌─────────────────┐    ┌──────────────────┐    ┌────────────────────┐
│   Root Agent    │───▶│   Roll Agent     │    │   Remote Prime     │
│  (Local)        │    │   (Local)        │    │   Agent            │
│                 │    │                  │    │  (localhost:8001)  │
│                 │───▶│                  │◀───│                    │
└─────────────────┘    └──────────────────┘    └────────────────────┘

El ejemplo A2A Basic consiste en:

  • Root Agent (root_agent): El orquestador principal que delega tareas a sub-agentes especializados
  • Roll Agent (roll_agent): Un sub-agente local que maneja operaciones de lanzamiento de dados
  • Prime Agent (prime_agent): Un agente A2A remoto que verifica si los números son primos, este agente se ejecuta en un servidor A2A separado

Exponiendo Tu Agente con el Servidor ADK

En el ejemplo a2a_basic, primero necesitarás exponer el check_prime_agent mediante un servidor A2A, para que el agente raíz local pueda usarlo.

1. Obtener el Código de Ejemplo

Primero, asegúrate de tener Go instalado y tu entorno configurado.

Puedes clonar y navegar al ejemplo a2a_basic aquí:

cd examples/go/a2a_basic

Como verás, la estructura de carpetas es la siguiente:

a2a_basic/
├── remote_a2a/
│   └── check_prime_agent/
│       └── main.go
├── go.mod
├── go.sum
└── main.go # agente raíz local

Agente Principal (a2a_basic/main.go)

  • rollDieTool: Herramienta de función para lanzar dados
  • newRollAgent: Agente local especializado en lanzamiento de dados
  • newPrimeAgent: Configuración del agente A2A remoto
  • newRootAgent: Orquestador principal con lógica de delegación

Agente Prime Remoto (a2a_basic/remote_a2a/check_prime_agent/main.go)

  • checkPrimeTool: Algoritmo de verificación de números primos
  • main: Implementación del servicio de verificación de primos y servidor A2A.

2. Iniciar el servidor del Agente Prime Remoto

Para mostrar cómo tu agente ADK puede consumir un agente remoto mediante A2A, primero necesitarás iniciar un servidor de agente remoto, que alojará el agente prime (bajo check_prime_agent).

# Iniciar el servidor a2a remoto que sirve el check_prime_agent en el puerto 8001
go run remote_a2a/check_prime_agent/main.go

Una vez ejecutado, deberías ver algo como:

2025/11/06 11:00:19 Starting A2A prime checker server on port 8001
2025/11/06 11:00:19 Starting the web server: &{port:8001}
2025/11/06 11:00:19 
2025/11/06 11:00:19 Web servers starts on http://localhost:8001
2025/11/06 11:00:19        a2a:  you can access A2A using jsonrpc protocol: http://localhost:8001

3. Buscar la tarjeta de agente requerida del agente remoto

El Protocolo A2A requiere que cada agente tenga una tarjeta de agente que describa lo que hace.

En el ADK de Go, la tarjeta de agente se genera dinámicamente cuando expones un agente usando el lanzador A2A. Puedes visitar http://localhost:8001/.well-known/agent-card.json para ver la tarjeta generada.

4. Ejecutar el Agente Principal (Consumidor)

# En una terminal separada, ejecutar el agente principal
go run main.go

Cómo funciona

El agente principal usa remoteagent.New para consumir el agente remoto (prime_agent en nuestro ejemplo). Como puedes ver a continuación, requiere el Name, Description y la URL AgentCardSource.

a2a_basic/main.go
func newPrimeAgent() (agent.Agent, error) {
    remoteAgent, err := remoteagent.NewA2A(remoteagent.A2AConfig{
        Name:            "prime_agent",
        Description:     "Agent that handles checking if numbers are prime.",
        AgentCardSource: "http://localhost:8001",
    })
    if err != nil {
        return nil, fmt.Errorf("failed to create remote prime agent: %w", err)
    }
    return remoteAgent, nil
}

Luego, simplemente puedes usar el agente remoto en tu agente raíz. En este caso, primeAgent se usa como uno de los sub-agentes en el root_agent a continuación:

a2a_basic/main.go
func newRootAgent(ctx context.Context, rollAgent, primeAgent agent.Agent) (agent.Agent, error) {
    model, err := gemini.NewModel(ctx, "gemini-2.0-flash", &genai.ClientConfig{})
    if err != nil {
        return nil, err
    }
    return llmagent.New(llmagent.Config{
        Name:  "root_agent",
        Model: model,
        Instruction: `
      You are a helpful assistant that can roll dice and check if numbers are prime.
      You delegate rolling dice tasks to the roll_agent and prime checking tasks to the prime_agent.
      Follow these steps:
      1. If the user asks to roll a die, delegate to the roll_agent.
      2. If the user asks to check primes, delegate to the prime_agent.
      3. If the user asks to roll a die and then check if the result is prime, call roll_agent first, then pass the result to prime_agent.
      Always clarify the results before proceeding.
    `,
        SubAgents: []agent.Agent{rollAgent, primeAgent},
        Tools:     []tool.Tool{},
    })
}

Ejemplos de Interacciones

Una vez que tanto tu agente principal como el remoto estén ejecutándose, puedes interactuar con el agente raíz para ver cómo llama al agente remoto mediante A2A:

Lanzamiento Simple de Dados: Esta interacción usa un agente local, el Roll Agent:

User: Roll a 6-sided die
Bot calls tool: transfer_to_agent with args: map[agent_name:roll_agent]
Bot calls tool: roll_die with args: map[sides:6]
Bot: I rolled a 6-sided die and the result is 6.

Verificación de Números Primos:

Esta interacción usa un agente remoto mediante A2A, el Prime Agent:

User: Is 7 a prime number?
Bot calls tool: transfer_to_agent with args: map[agent_name:prime_agent]
Bot calls tool: prime_checking with args: map[nums:[7]]
Bot: Yes, 7 is a prime number.

Operaciones Combinadas:

Esta interacción usa tanto el Roll Agent local como el Prime Agent remoto:

User: roll a die and check if it's a prime
Bot: Okay, I will first roll a die and then check if the result is a prime number.

Bot calls tool: transfer_to_agent with args: map[agent_name:roll_agent]
Bot calls tool: roll_die with args: map[sides:6]
Bot calls tool: transfer_to_agent with args: map[agent_name:prime_agent]
Bot calls tool: prime_checking with args: map[nums:[3]]
Bot: 3 is a prime number.

Próximos Pasos

Ahora que has creado un agente que está usando un agente remoto mediante un servidor A2A, el siguiente paso es aprender cómo exponer tu propio agente.