OmniRoute A2A Server Documentation (Português (Brasil))

Autenticação

Todas as solicitações para /a2a exigem uma chave de API por meio do cabeçalho Authorization:

Authorization: Bearer YOUR_OMNIROUTE_API_KEY

Se nenhuma chave de API estiver configurada no servidor, a autenticação será ignorada.

Habilitação

O A2A é controlado pela opção Endpoints → A2A e fica desabilitado por padrão. Quando desabilitado, GET /api/a2a/status informa status: "disabled" e online: false; as chamadas JSON-RPC para POST /a2a retornam HTTP 503 com o código de erro JSON-RPC -32000.

---

Métodos JSON-RPC 2.0

message/send — Execução síncrona

Envia uma mensagem para uma habilidade e aguarda a resposta 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"}
    }
  }'

Resposta:

{
  "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 — Streaming via SSE

Funciona da mesma forma que message/send, mas retorna Server-Sent Events para streaming em tempo 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 o status da tarefa

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 uma tarefa

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 disponíveis

O OmniRoute expõe 6 habilidades A2A conectadas em src/lib/a2a/taskExecution.ts::A2A_SKILL_HANDLERS. Cada módulo de habilidade está localizado em src/lib/a2a/skills/.

Habilidade	ID	Descrição	Tags	Exemplos
Roteamento inteligente	smart-routing	Encaminha um prompt pelo provedor/combo ideal usando o mecanismo de combos e a pontuação do OmniRoute	roteamento, provedores	“Encaminhe este prompt pelo melhor modelo”
Gerenciamento de cotas	quota-management	Informa o estado da cota por provedor e ajuda os clientes a decidir quando limitar ou trocar	cota, provedores	“Verifique a cota da anthropic”
Descoberta de provedores	provider-discovery	Lista os provedores instalados com funcionalidades, indicadores de camada gratuita e status do OAuth	provedores, descoberta	“Quais provedores estão disponíveis?”
Análise de custos	cost-analysis	Estima o custo de uma solicitação/conversa com base no catálogo e no uso recente	custo, uso	“Estime o custo desta conversa”
Relatório de integridade	health-report	Agrega o estado do disjuntor, do período de espera e do bloqueio por provedor	integridade, resiliência	“Mostre o status de integridade dos provedores”
Listar funcionalidades	list-capabilities	Retorna o catálogo completo de 45 entradas de Habilidades do Agente (23 de API + 21 de CLI + 1 de configuração) como uma tabela markdown com URLs brutas de SKILL.md para injeção de contexto	catálogo, descoberta, habilidades	“Liste todas as funcionalidades do OmniRoute”

O Cartão do Agente deve ser mantido alinhado ao catálogo ativo de 352 provedores; as contagens de provedores e os metadados de gratuidade/ausência de autenticação são obtidos do registro em tempo de execução.

Detalhes da habilidade list-capabilities

A habilidade list-capabilities é particularmente útil para agentes externos que precisam descobrir o que o OmniRoute expõe antes de enviar chamadas de API. Ela retorna um artefato de tabela markdown estruturada:

| ID | Nome | Categoria | Área | Endpoints/Comandos | URL bruta |
| --- | --- | --- | --- | --- | --- |
| omni-auth | Autenticação e sessões | api | autenticação | POST /api/auth/login, ... | https://raw.githubusercontent.com/... |
...

Cada linha inclui a coluna rawUrl para que os agentes possam buscar imediatamente o SKILL.md completo. O campo metadata.totalSkills reflete o tamanho do catálogo (45 atualmente). Implementação: src/lib/a2a/skills/listCapabilities.ts. Consulte também AGENT-SKILLS.md.

---

API REST (auxiliar)

O endpoint JSON-RPC /a2a é o ponto de entrada A2A canônico. Os endpoints REST abaixo fornecem acesso auxiliar para painéis e ferramentas externas:

Endpoint	Método	Descrição	Autenticação
/api/a2a/status	GET	Status do servidor, skills registradas	(público)
/api/a2a/tasks	GET	Lista tarefas com filtros	gerenciamento
/api/a2a/tasks/[id]	GET	Obtém uma tarefa por ID	gerenciamento
/api/a2a/tasks/[id]/cancel	POST	Cancela uma tarefa em execução	gerenciamento
/.well-known/agent.json	GET	Agent Card (descoberta A2A)	(público, armazenado em cache por 3600s)
/api/a2a/tasks	POST	Delegação de entrada para a frota OmniConductor (Conductor PRD RF5)	Bearer em relação a OMNIROUTE_API_KEY + a2aEnabled

Delegação de entrada do Conductor (POST /api/a2a/tasks): agentes A2A externos delegam trabalhos de programação à frota OmniConductor por meio do OmniRoute. Corpo: { skill: "conductor" | "conductor-cli-<profile>", messages: [{role, content}], metadata: { conductor: { repo: { url, base_ref? }, mode?, cli?, model? } } } — somente as skills da frota Conductor (aquelas anunciadas no Agent Card) podem receber delegações; metadata.conductor.repo.url é obrigatório (a frota trabalha em repositórios git). A rota é convertida em POST /v1/tasks do hub usando o CONDUCTOR_ORCHESTRATOR_TOKEN do servidor (com fallback para CONDUCTOR_HUB_TOKEN) e retorna 201 { conductor_task_id, state: "submitted" }; os estados das tarefas retornam pelo espelho SSE→A2A (RF1) e ficam visíveis por meio de GET /api/a2a/tasks?skill=conductor.

---

Adicionando uma nova skill

1. Crie o arquivo da skill: src/lib/a2a/skills/<your-skill>.ts

   Exporte uma função assíncrona (task: A2ATask) => Promise<{ artifacts, metadata }>. Siga a estrutura das skills existentes, como smartRouting.ts.

2. Registre o handler: em src/lib/a2a/taskExecution.ts, adicione uma entrada a A2A_SKILL_HANDLERS:

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

3. Exponha no Agent Card: em src/app/.well-known/agent.json/route.ts, acrescente ao array skills:

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

4. Escreva testes: tests/unit/a2a-<your-skill>.test.ts. Cubra o caminho de sucesso e o caminho de erro.

5. Documente a nova skill na tabela Available Skills deste arquivo.

---

TTL da tarefa

As tarefas expiram após ttlMinutes (5 min por padrão) — configurado no construtor A2ATaskManager em src/lib/a2a/taskManager.ts:82. Para personalizar, faça um fork da instanciação de A2ATaskManager e passe um valor diferente (por exemplo, new A2ATaskManager(15) para um TTL de 15 minutos). Um intervalo em segundo plano remove as tarefas expiradas a cada 60 segundos.

---

Ciclo de vida da tarefa

submitted → working → completed
                    → failed
                    → cancelled

• As tarefas expiram após 5 minutos por padrão (consulte TTL da tarefa)
• Estados terminais: completed, failed, cancelled
• O log de eventos registra cada transição de estado

---

Códigos de erro

Código	Significado
-32700	Erro de análise (JSON inválido)
-32600	Solicitação inválida / Não autorizado
-32601	Método ou skill não encontrado
-32602	Parâmetros inválidos
-32603	Erro interno
-32000	O endpoint A2A está desabilitado

---

Exemplos de integração

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-fonte do OmniRoute (a58000c7685f)