agent_platform_oci/specs/SPEC-009-Channel-Gateway.md

SPEC-009 — Channel Gateway

Escopo

O Channel Gateway normaliza payloads de canais externos para GatewayRequest e traduz ChannelResponse para o formato de resposta do canal.

Modos de Operação

Modo	Descrição
Embedded	Normalização no próprio backend para demos e cenários simples.
External	Serviço dedicado para canais corporativos.

GatewayRequest

{
  "channel": "whatsapp",
  "tenant_id": "default",
  "agent_id": "telecom_contas",
  "payload": {
    "message": "Segunda via de fatura",
    "session_id": "5511999999999",
    "user_id": "5511999999999",
    "message_id": "wamid.123",
    "business_context": {
      "customer_key": "5511999999999",
      "interaction_key": "wamid.123",
      "session_key": "5511999999999"
    },
    "metadata": {
      "source_channel": "whatsapp",
      "source_message_type": "interactive"
    }
  }
}

ChannelResponse

{
  "channel": "whatsapp",
  "session_id": "default:telecom_contas:5511999999999",
  "text": "Encontrei sua fatura...",
  "metadata": {
    "tenant_id": "default",
    "agent_id": "telecom_contas",
    "route": "billing_agent",
    "intent": "billing_invoice_explanation"
  }
}

Fluxo Externo

sequenceDiagram
    participant Canal
    participant CG as Channel Gateway
    participant AG as Agent Gateway
    participant RT as Agent Runtime
    Canal->>CG: payload bruto
    CG->>CG: autenticação, parse, dedupe
    CG->>AG: GatewayRequest
    AG->>RT: execução
    RT-->>AG: ChannelResponse
    AG-->>CG: ChannelResponse
    CG-->>Canal: resposta do canal

Responsabilidades

Responsabilidade	Detalhe
Auth	Validar assinatura, token ou origem.
Parse	Interpretar payload bruto.
Dedup	Evitar reprocessamento por message_id.
Normalize	Criar GatewayRequest.
Business Context	Mapear chaves canônicas.
Forward	Chamar Agent Gateway.
Translate	Converter ChannelResponse para canal.
Observe	Emitir logs, métricas e traces.

Idempotência

Chave:

tenant_id:channel:user_id:message_id

Comportamentos:

Situação	Ação
Primeira mensagem	Processar.
Duplicada em andamento	Retornar 202 ou resposta controlada.
Duplicada concluída	Retornar resposta anterior.

Versionamento

Header:

X-Agent-Framework-Contract: gateway-request-v1

Campo alternativo:

{
  "payload": {
    "metadata": {
      "contract_version": "gateway-request-v1"
    }
  }
}

Segurança

Validações:

• assinatura do webhook;
• origem permitida;
• tamanho máximo;
• tipo de evento permitido;
• anexos permitidos;
• sanitização de texto;
• remoção de tokens;
• máscara de dados sensíveis;
• rate limit;
• deduplicação.

Erros

Código HTTP	Uso
400	Payload inválido do canal.
401	Autenticação ausente.
403	Origem não autorizada.
422	GatewayRequest inválido.
429	Rate limit.
500	Erro interno.
503	Runtime indisponível.

Anti-patterns

• Agente lendo payload bruto.
• Workflow tratando channel == whatsapp.
• MCP recebendo payload bruto.
• Tokens do canal em metadata.
• Gateway externo executando regra de agente.
• Frontend enviando campos fora do contrato.

Requisitos Não Funcionais

Categoria	Requisito
Disponibilidade	Componentes deployáveis expõem /health e /ready.
Escalabilidade	Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos.
Segurança	Segredos são fornecidos por secret store ou Kubernetes Secrets.
Observabilidade	Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id.
Auditabilidade	Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis.
Portabilidade	Execução suportada em local, Docker Compose e Kubernetes/OKE.
Configuração	Comportamento variável é controlado por .env e YAML versionado.

Critérios de Aceite

• Payload bruto é convertido para GatewayRequest.
• GatewayRequest é validado.
• message_id é usado para idempotência.
• business_context contém chaves canônicas.
• Resposta do runtime é traduzida para o canal.
• Payload bruto não chega ao Agent Runtime.
• Auth/rate limit/dedup estão implementados.
• Erros são padronizados.
• Contrato possui versão.
• Logs/traces usam request_id e trace_id.

Glossário

Termo	Definição
Agent Platform	Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais.
Agent Framework	Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários.
Agent Runtime	Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida.
Agent Gateway	Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes.
Channel Gateway	Aplicação ou módulo de normalização de payloads de canais para GatewayRequest.
AI Gateway	Aplicação de governança, roteamento e abstração de chamadas LLM/embedding.
MCP Gateway	Aplicação de governança e roteamento de tools MCP.
Evaluator	Camada de avaliação online/offline, regressão e certificação.
Business Context	Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key.