Data plane

Streaming

Com "stream": true a resposta É text/event-stream: uma linha data: <json do chunk> por quadro e um data: [DONE] final. O x-avalon-request-id sai no primeiro byte, antes de qualquer quadro — é o que permite correlacionar um stream que termina mal. Guardrails de entrada rodam antes de qualquer byte sair: uma recusa sai como resposta HTTP comum, em JSON, e o cliente nunca chega a ver cabeçalho de stream nenhum.

Peça "stream_options": {"include_usage": true} para o quadro final de usage — sem ele o provedor normalmente não manda tokens, e a linha da trilha fica com consumo não medido.

246 e 446: os dois status que só existem aqui

Sessão

O Mcp-Session-Id vale nos dois sentidos: o que o servidor MCP emitir volta ao cliente, e o que o cliente mandar é repassado ao servidor. É isso que faz um SDK de MCP manter sessão através do gateway sem saber que ele existe. O Mcp-Protocol-Version do cliente também é repassado.

O que o gateway decide antes de repassar

• A chave precisa do escopo mcp.invoke.
• O servidor precisa estar PROVISIONADO para o workspace da chave — o gate real de alcance, mais forte que o escopo.
• A credencial do servidor é injetada por nós e nunca pode ser sobrescrita por um cabeçalho do cliente.
• Ferramenta fora da allowlist da organização é recusada no protocolo, não no HTTP: 200 com envelope de erro JSON-RPC (code: -32603, data.codigo: ferramenta_nao_permitida). Derrubar a sessão de um cliente de SDK por política seria pior do que responder o que ele sabe ler.
• Corpo de erro do upstream NUNCA é repassado (pode carregar credencial nossa) — vira 502 upstream_mcp_indisponivel.

Quickstart: apontar um agente existente para o gateway

Não há SDK novo a instalar. O cliente A2A troca a URL base do agente pela nossa e autentica com uma chave gov_ que tenha o escopo agent.invoke — o mesmo cabeçalho Authorization de sempre. O SDK resolve o card em GET /a2a/{slug}/.well-known/agent-card.json e passa a falar JSON-RPC em POST /a2a/{slug}.

# antes: o cliente fala direto com o agente
https://meu-agente.exemplo.com

# depois: mesma conversa, agora governada
https://api.avalonops.com.br/a2a/ag-meu-agente-3f8a1c

Authorization: Bearer gov_...   # chave com escopo agent.invoke

O endereço real do agente sai de supported_interfaces[] do card dele — o gateway nunca assume que a URL base é o endpoint RPC. E o card servido por nós é o do agente, como ele o publicou (com provider, signatures, ícone e extensões que nem lemos), filtrado pela política de skill do workspace da chave. A descoberta exige a MESMA chave e o MESMO escopo do POST: um card público seria um enumerador de slugs.

O que o gateway decide antes de repassar

• A chave precisa do escopo agent.invoke.
• O limite de taxa por requisições do workspace vale (com contagem própria). Orçamento não — uma chamada de agente não consome tokens.
• O agente precisa estar PROVISIONADO para o workspace da chave — o gate real de alcance, mais forte que o escopo. Slug inexistente e slug não provisionado devolvem o MESMO 404 servidor_agent_nao_encontrado, para que quem varre slugs não aprenda o que existe.
• A credencial do agente é injetada por nós e nunca vem do cliente; a chave gov_ do cliente nunca atravessa para o agente.
• Corpo de erro do upstream NUNCA é repassado (pode carregar credencial nossa) — vira 502 upstream_agent_indisponivel. Já um erro A2A do próprio agente (-32001 TaskNotFound) é resposta legítima do protocolo e volta crua, dentro de um 200.

skillId é convenção da Avalon, opt-in — não é campo do protocolo

Declarada a skill e estando ela fora da allowlist do par agente×workspace, a recusa é no protocolo, não no HTTP: 200 com envelope de erro JSON-RPC (code: -32603, data.codigo: skill_nao_permitida), com o mesmo id que o cliente mandou. Derrubar a conversa de um SDK por política seria pior do que responder o que ele sabe ler. A mesma allowlist filtra skills[] do card servido àquele workspace.

Webhooks: mediação total

tasks/pushNotificationConfig/set e tasks/pushNotificationConfig/get são os ÚNICOS métodos interceptados (não repassados crus). No set, o gateway guarda a URL que o cliente configurou e registra no agente uma URL nossa, com um token opaco por task: o agente nunca conhece a URL do cliente, e o cliente nunca vê a nossa. O get responde com a config DO CLIENTE, sem consultar o agente (que só conhece a nossa).

• URL do cliente inválida (mesma política de SSRF do resto do produto) recusa webhook_url_invalida — em envelope JSON-RPC, como a recusa de skill. A URL é validada duas vezes: ao gravar e de novo no instante da entrega (o DNS pode ter mudado).
• set sem params.taskId ou sem pushNotificationConfig.url recusa webhook_config_invalida.
• QUALQUER lote JSON-RPC (um array no corpo) que contenha uma chamada set ou get é recusado inteiro (webhook_batch_nao_suportado), mesmo que essa seja a única chamada do lote — um array de um item só ainda é um array, e a mediação de webhook não sabe reescrever metade de um corpo que o cliente mandou como uma unidade. Mande o set sozinho, fora do lote.
• Recebida a notificação em POST /a2a/webhook/{token}, a entrega ao webhook do cliente sai assinada com HMAC SHA-256 do corpo no cabeçalho x-avalon-assinatura, com retentativas em 1s, 10s e 60s. O segredo é gerado no console e exibido uma única vez.

Rotacionar o segredo substitui o atual na hora, sem período de graça: as entregas ainda não enviadas passam a assinar com o segredo novo (ele é lido na hora de assinar, uma vez por tentativa). O que já saiu não é alcançado por rotação nenhuma.