OmniRoute A2A Server Documentation (Español)

Autenticación

Todas las solicitudes a /a2a requieren una clave de API mediante el encabezado Authorization:

Authorization: Bearer YOUR_OMNIROUTE_API_KEY

Si no hay ninguna clave de API configurada en el servidor, se omite la autenticación.

Habilitación

A2A se controla mediante el interruptor Endpoints → A2A y está deshabilitado de forma predeterminada. Cuando está deshabilitado, GET /api/a2a/status informa de status: "disabled" y online: false; las llamadas JSON-RPC a POST /a2a devuelven HTTP 503 con el código de error JSON-RPC -32000.

---

Métodos JSON-RPC 2.0

message/send — Ejecución síncrona

Envía un mensaje a una habilidad y espera la respuesta completa.

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "skill": "smart-routing",
      "messages": [{"role": "user", "content": "Write a hello world in Python"}],
      "metadata": {"model": "auto", "combo": "fast-coding"}
    }
  }'

Respuesta:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "task": { "id": "uuid", "state": "completed" },
    "artifacts": [{ "type": "text", "content": "..." }],
    "metadata": {
      "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)",
      "cost_envelope": {
        "estimated": 0.005,
        "actual": 0.003,
        "currency": "USD"
      },
      "resilience_trace": [
        {
          "event": "primary_selected",
          "provider": "anthropic",
          "timestamp": "..."
        }
      ],
      "policy_verdict": {
        "allowed": true,
        "reason": "within budget and quota limits"
      }
    }
  }
}

message/stream — Transmisión mediante SSE

Igual que message/send, pero devuelve eventos enviados por el servidor para la transmisión en tiempo real.

curl -N -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/stream",
    "params": {
      "skill": "smart-routing",
      "messages": [{"role": "user", "content": "Explain quantum computing"}]
    }
  }'

Eventos SSE:

data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}}

: heartbeat 2026-03-03T17:00:00Z

data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}}

tasks/get — Consultar el estado de una tarea

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}'

tasks/cancel — Cancelar una tarea

curl -X POST http://localhost:20128/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}'

---

Habilidades disponibles

OmniRoute expone 6 habilidades A2A conectadas en src/lib/a2a/taskExecution.ts::A2A_SKILL_HANDLERS. Cada módulo de habilidad se encuentra en src/lib/a2a/skills/.

Habilidad	ID	Descripción	Etiquetas	Ejemplos
Enrutamiento inteligente	smart-routing	Enruta un prompt a través del proveedor/combinación óptimos mediante el motor de combinaciones y el sistema de puntuación de OmniRoute	enrutamiento, proveedores	“Enruta este prompt mediante el mejor modelo”
Gestión de cuotas	quota-management	Informa del estado de las cuotas por proveedor y ayuda a quienes realizan llamadas a decidir cuándo limitar el uso o cambiar de proveedor	cuotas, proveedores	“Comprueba la cuota de anthropic”
Descubrimiento de proveedores	provider-discovery	Enumera los proveedores instalados junto con sus capacidades, indicadores de nivel gratuito y estado de OAuth	proveedores, descubrimiento	“¿Qué proveedores están disponibles?”
Análisis de costes	cost-analysis	Estima el coste de una solicitud o conversación a partir del catálogo y del uso reciente	costes, uso	“Estima el coste de esta conversación”
Informe de estado	health-report	Agrega el estado del disyuntor, el período de espera y el bloqueo de cada proveedor	estado, resiliencia	“Muestra el estado de todos los proveedores”
Enumeración de capacidades	list-capabilities	Devuelve el catálogo completo de 45 entradas de Agent Skills (23 de API + 21 de CLI + 1 de configuración) como una tabla markdown con URL de SKILL.md sin procesar para la inyección de contexto	catálogo, descubrimiento, habilidades	“Enumera todas las capacidades de OmniRoute”

La tarjeta del agente debe mantenerse sincronizada con el catálogo activo de 352 proveedores; los recuentos de proveedores y los metadatos de acceso gratuito/sin autenticación proceden del registro en tiempo de ejecución.

Detalles de la habilidad list-capabilities

La habilidad list-capabilities resulta especialmente útil para agentes externos que necesitan descubrir qué expone OmniRoute antes de enviar llamadas a la API. Devuelve un artefacto de tabla markdown estructurada:

| ID | Nombre | Categoría | Área | Endpoints/Comandos | URL sin procesar |
| --- | --- | --- | --- | --- | --- |
| omni-auth | Autenticación y sesiones | api | auth | POST /api/auth/login, ... | https://raw.githubusercontent.com/... |
...

Cada fila incluye la columna rawUrl para que los agentes puedan obtener inmediatamente el archivo SKILL.md completo. El campo metadata.totalSkills refleja el tamaño del catálogo (actualmente 45). Implementación: src/lib/a2a/skills/listCapabilities.ts. Véase también AGENT-SKILLS.md.

---

API REST (auxiliar)

El endpoint JSON-RPC /a2a es el punto de entrada canónico de A2A. Los siguientes endpoints REST proporcionan acceso auxiliar para paneles y herramientas externas:

Endpoint	Método	Descripción	Autenticación
/api/a2a/status	GET	Estado del servidor, habilidades registradas	(público)
/api/a2a/tasks	GET	Lista de tareas con filtros	administración
/api/a2a/tasks/[id]	GET	Obtener tarea por ID	administración
/api/a2a/tasks/[id]/cancel	POST	Cancelar una tarea en ejecución	administración
/.well-known/agent.json	GET	Tarjeta del agente (descubrimiento A2A)	(público, almacenado en caché durante 3600s)
/api/a2a/tasks	POST	Delegación entrante a la flota de OmniConductor (Conductor PRD RF5)	Bearer frente a OMNIROUTE_API_KEY + a2aEnabled

Delegación entrante de Conductor (POST /api/a2a/tasks): los agentes A2A externos delegan trabajo de programación a la flota de OmniConductor a través de OmniRoute. Cuerpo: { skill: "conductor" | "conductor-cli-<profile>", messages: [{role, content}], metadata: { conductor: { repo: { url, base_ref? }, mode?, cli?, model? } } } — solo se pueden delegar las habilidades de la flota de Conductor (las anunciadas en la tarjeta del agente); metadata.conductor.repo.url es obligatorio (la flota trabaja con repositorios git). La ruta se traduce al POST /v1/tasks del hub mediante el CONDUCTOR_ORCHESTRATOR_TOKEN del lado del servidor (con CONDUCTOR_HUB_TOKEN como alternativa) y devuelve 201 { conductor_task_id, state: "submitted" }; los estados de las tareas se transmiten de vuelta mediante el reflejo SSE→A2A (RF1) y son visibles a través de GET /api/a2a/tasks?skill=conductor.

---

Añadir una nueva habilidad

1. Cree el archivo de la habilidad: src/lib/a2a/skills/<your-skill>.ts

   Exporte una función asíncrona (task: A2ATask) => Promise<{ artifacts, metadata }>. Siga la estructura de habilidades existentes como smartRouting.ts.

2. Registre el controlador: en src/lib/a2a/taskExecution.ts, añada una entrada a A2A_SKILL_HANDLERS:

   export const A2A_SKILL_HANDLERS = {
     // ...habilidades existentes
     "your-skill": async (task) => {
       const skillModule = await import("./skills/yourSkill");
       return skillModule.executeYourSkill(task);
     },
   };

3. Expóngala en la tarjeta del agente: en src/app/.well-known/agent.json/route.ts, añádala al array skills:

   {
     "id": "your-skill",
     "name": "Your Skill",
     "description": "Brief, intent-focused description",
     "tags": ["routing", "quota"],
     "examples": ["Sample natural-language invocation"]
   }

4. Escriba pruebas: tests/unit/a2a-<your-skill>.test.ts. Cubra el caso exitoso y el caso de error.

5. Documente la nueva habilidad en la tabla Available Skills de este archivo.

---

TTL de las tareas

Las tareas caducan después de ttlMinutes (5 min de forma predeterminada), configurado en el constructor de A2ATaskManager en src/lib/a2a/taskManager.ts:82. Para personalizarlo, bifurque la instanciación de A2ATaskManager y pase un valor diferente (p. ej., new A2ATaskManager(15) para un TTL de 15 minutos). Un intervalo en segundo plano elimina las tareas caducadas cada 60 segundos.

---

Ciclo de vida de las tareas

submitted → working → completed
                    → failed
                    → cancelled

• Las tareas caducan después de 5 minutos de forma predeterminada (consulte TTL de las tareas)
• Estados terminales: completed, failed, cancelled
• El registro de eventos realiza un seguimiento de cada transición de estado

---

Códigos de error

Código	Significado
-32700	Error de análisis (JSON no válido)
-32600	Solicitud no válida / No autorizado
-32601	Método o skill no encontrado
-32602	Parámetros no válidos
-32603	Error interno
-32000	El endpoint A2A está deshabilitado

---

Ejemplos de integración

Python (requests)

import requests

resp = requests.post("http://localhost:20128/a2a", json={
    "jsonrpc": "2.0", "id": "1",
    "method": "message/send",
    "params": {
        "skill": "smart-routing",
        "messages": [{"role": "user", "content": "Hello"}]
    }
}, headers={"Authorization": "Bearer YOUR_KEY"})

result = resp.json()["result"]
print(result["artifacts"][0]["content"])
print(result["metadata"]["routing_explanation"])

TypeScript (fetch)

const resp = await fetch("http://localhost:20128/a2a", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_KEY",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "message/send",
    params: {
      skill: "smart-routing",
      messages: [{ role: "user", content: "Hello" }],
    },
  }),
});
const { result } = await resp.json();
console.log(result.metadata.routing_explanation);

---

Código fuente de OmniRoute (a58000c7685f)