Modo A2A

El modo A2A ejecuta tu agente como un servidor HTTP al que otros sistemas pueden llamar utilizando el protocolo Agente a Agente (Agent-to-Agent). Esto te permite exponer tu agente como un servicio que otros agentes o aplicaciones pueden descubrir e invocar a través de la red.

Utiliza A2A cuando desees que otros sistemas puedan llamar a tu agente a través de HTTP. Para la integración con editores, consulta la integración ACP. Para usar agentes como herramientas en clientes MCP, consulta la integración MCP.

Requisitos previos

Antes de iniciar un servidor A2A, necesitas:

• Docker Agent instalado - Consulta la guía de instalación (o #installation)
• Configuración del agente - Un archivo YAML que define tu agente. Consulta el tutorial
• Claves de API configuradas - Si utilizas proveedores de modelos en la nube (consulta Proveedores de modelos)

Iniciar un servidor A2A

Uso básico:

$ docker agent serve a2a ./agent.yaml

Tu agente ya es accesible a través de HTTP. Otros sistemas A2A pueden descubrir las capacidades de tu agente y llamarlo.

Puerto personalizado:

$ docker agent serve a2a ./agent.yaml --port 8080

Agente específico en un equipo:

$ docker agent serve a2a ./agent.yaml --agent engineer

Desde un registro OCI:

$ docker agent serve a2a agentcatalog/pirate --port 9000

Endpoints HTTP

Cuando inicias un servidor A2A, este expone dos endpoints HTTP:

Tarjeta del agente: /.well-known/agent-card

La tarjeta del agente (agent card) describe las capacidades de tu agente:

$ curl http://localhost:8080/.well-known/agent-card

{
  "name": "agent",
  "description": "A helpful coding assistant",
  "skills": [
    {
      "id": "agent_root",
      "name": "root",
      "description": "A helpful coding assistant",
      "tags": ["llm", "dockeragent"]
    }
  ],
  "preferredTransport": "jsonrpc",
  "url": "http://localhost:8080/invoke",
  "capabilities": {
    "streaming": true
  },
  "version": "0.1.0"
}

Endpoint de invocación: /invoke

Llama a tu agente enviando una solicitud JSON-RPC:

$ curl -X POST http://localhost:8080/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "What is 2+2?"
          }
        ]
      }
    }
  }'

La respuesta incluye la réplica del agente:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "artifacts": [
      {
        "parts": [
          {
            "kind": "text",
            "text": "2+2 equals 4."
          }
        ]
      }
    ]
  }
}

Ejemplo: Flujo de trabajo multiagente

Aquí tienes un escenario concreto donde A2A es útil. Tienes dos agentes:

1. Un agente de propósito general que interactúa con los usuarios
2. Un agente de revisión de código especializado con acceso a tu código fuente

Ejecuta el especialista como un servidor A2A:

$ docker agent serve a2a ./code-reviewer.yaml --port 8080
Listening on 127.0.0.1:8080

Configura tu agente principal para llamarlo:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    instruction: You are a helpful assistant
    toolsets:
      - type: a2a
        url: http://localhost:8080
        name: code-reviewer

Ahora, cuando los usuarios pregunten al agente principal sobre la calidad del código, este puede delegar en el especialista. El agente principal ve a code-reviewer como una herramienta que puede llamar, y el especialista tiene acceso a las herramientas de código fuente que necesita.

Llamar a otros agentes A2A

Tus agentes pueden llamar a agentes A2A remotos como herramientas. Configura el conjunto de herramientas A2A con la URL del agente remoto:

agents:
  root:
    toolsets:
      - type: a2a
        url: http://localhost:8080
        name: specialist

La url especifica dónde se está ejecutando el agente remoto, y name es un identificador opcional para la herramienta. Tu agente ahora puede delegar tareas al agente especialista remoto.

Si el agente remoto requiere autenticación o cabeceras personalizadas:

agents:
  root:
    toolsets:
      - type: a2a
        url: http://localhost:8080
        name: specialist
        remote:
          headers:
            Authorization: Bearer token123
            X-Custom-Header: value

¿Qué sigue?

• Revisa la referencia de CLI para conocer todas las opciones de docker agent serve a2a
• Aprende sobre el modo MCP para exponer agentes como herramientas en clientes MCP
• Aprende sobre el modo ACP para la integración con editores
• Comparte tus agentes con registros OCI