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

SPEC-009 — Channel Gateway

Scope

O Channel Gateway normaliza payloads of canais external for GatewayRequest and traduz ChannelResponse for the formato of Response of the canal.

Modos of Operations

Modo	Description
Embedded	Normalização no próprio backend for demos and cenários simples.
External	service dedicado for 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"
  }
}

Flow External

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

Responsibilities

Responsibility	Detalhe
Auth	validate assinatura, token or origem.
Parse	Interpretar payload bruto.
Dedup	Evitar reprocessamento por message_id.
Normalize	create GatewayRequest.
Business Context	Mapear chaves canônicas.
Forward	Chamar Agent Gateway.
Translate	Converter ChannelResponse for canal.
Observe	emit logs, Metrics and traces.

Idempotência

Chave:

tenant_id:channel:user_id:message_id

Comportamentos:

Situação	Ação
Primeira Message	Processar.
Duplicada em andamento	return 202 or Response controlada.
Duplicada concluída	return Response previous.

Versionamento

Header:

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

field alternativo:

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

Security

Validations:

• assinatura of the webhook;
• origem allowed;
• tamanho máximo;
• tipo of evento allowed;
• anexos permitidos;
• sanitização of texto;
• remoção of tokens;
• máscara of Data sensíveis;
• rate limit;
• deduplicação.

Erros

Código HTTP	Uso
400	Payload invalid of the canal.
401	Authentication ausente.
403	Origem No autorizada.
422	GatewayRequest invalid.
429	Rate limit.
500	Error Internal.
503	Runtime unavailable.

Anti-patterns

• Agent lendo payload bruto.
• Workflow tratando channel == whatsapp.
• MCP recebendo payload bruto.
• Tokens of the canal em metadata.
• Gateway External executando regra of Agent.
• Frontend enviando fields outside of the Contract.

Requirements No Funcionais

Categoria	Requirement
Availability	Components deployáveis expõem /health and /ready.
Escalabilidade	Apps stateless escalam horizontalmente. State conversational fica em repositórios external.
Security	Segredos are fornecidos por secret store or Kubernetes Secrets.
Observability	Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id.
Auditabilidade	Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis.
Portabilidade	Execution suportada em local, Docker Compose and Kubernetes/OKE.
Configuration	Comportamento variável is controlado por .env and YAML versionado.

Acceptance criteria

• Payload bruto is convertido for GatewayRequest.
• GatewayRequest is validado.
• message_id Is used to idempotência.
• business_context contains chaves canônicas.
• Response of the runtime is traduzida for the canal.
• Payload bruto No chega ao Agent Runtime.
• Auth/rate limit/dedup are implementados.
• Erros are padronizados.
• Contract possui Version.
• Logs/traces usam request_id and trace_id.

Glossário

Termo	Definição
Agent Platform	Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational.
Agent Framework	Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários.
Agent Runtime	Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida.
Agent Gateway	Aplicação deployável of Input, Routing and orquestração between backends/Agents.
Channel Gateway	Aplicação or módulo of normalização of payloads of canais for GatewayRequest.
AI Gateway	Aplicação of Governance, Routing and abstração of Calls LLM/embedding.
MCP Gateway	Aplicação of Governance and Routing of tools MCP.
Evaluator	layer of Evaluation online/offline, regressão and Certification.
Business Context	Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key.