agent_platform_oci/specs/en/SPEC-003-Agent-Gateway.md

SPEC-003 — Agent Gateway

Scope

The Agent Gateway is the platform's single entry point for channels and external consumers.

It receives messages, manages global sessions, resolves the responsible backend or agent, performs routing and cross-agent/backend handoffs, and forwards SSE events.

The Agent Gateway does not run LLM inference or embeddings. Those capabilities belong to the Runtime and Agent Framework.

---

Responsibilities

Single platform entry point

Web
WhatsApp
Voice
Teams
Slack
      |
      v
Agent Gateway
      |
      +--> Agent Backend A
      |
      +--> Agent Backend B
      |
      +--> Agent Backend C

Session management

Responsible for:

• Creation of Sessions
• Recovery of Sessions
• Update of Context global
• Persistence of metadata of Session
• correlation of requests

Example:

{
  "session_id": "default:telecom_contas:123",
  "tenant_id": "default",
  "active_backend": "telecom_contas",
  "active_agent": "telecom_contas",
  "turn_count": 12,
  "metadata": {}
}

---

Backend Routing

Resolve qual backend must processar a Message.

Example:

backends:
  telecom_contas:
    url: http://backend-contas:8000

  telecom_ofertas:
    url: http://backend-ofertas:8000

Possible criteria:

• Backend Standard
• Rules YAML
• intent detected
• Context of the Session
• Router LLM (Optional)

---

Handoff

Allows transferência between Agents or backends.

Example:

Contas
   |
   +--> Ofertas
   |
   +--> Retenção

A handoff must preserve:

• session_id
• conversation_key
• business context
• History of the conversation
• metadata of correlation

---

SSE Proxy

responsible for forward Events of streaming for clientes.

Endpoints

Method	Endpoint
POST	/gateway/message
POST	/gateway/message/sse
GET	/gateway/events/{session_id}

Supported SSE events:

• connected
• workflow.started
• message.responded
• workflow.completed
• flow.end
• error

---

Backend Discovery

Can operate with Catalog static or discovery dynamic.

Catalog static

backends:
  telecom_contas:
    url: http://contas:8000

  telecom_ofertas:
    url: http://ofertas:8000

discovery dynamic

service_discovery:
  enabled: true

Capabilities:

• Registration automatic
• Health check periodic
• Update of Catalog
• synchronization of metadata

---

Health and Operations

Endpoints

Method	Endpoint
GET	/health
GET	/ready
GET	/backends
GET	/debug/sessions

---

Contract GatewayRequest

{
  "tenant_id": "default",
  "agent_id": "telecom_contas",
  "session_id": "default:telecom_contas:123",
  "message": "Quero consultar minha fatura",
  "business_context": {
    "customer_key": "11999999999"
  },
  "metadata": {
    "request_id": "req-001",
    "trace_id": "trace-001"
  }
}

---

Contract GatewayResponse

{
  "session_id": "default:telecom_contas:123",
  "backend": "telecom_contas",
  "agent": "telecom_contas",
  "message": "Sua fatura está disponível.",
  "metadata": {
    "request_id": "req-001"
  }
}

---

Events

Evento	Description
agent.gateway.request.received	Request recebida
agent.gateway.session.created	Session criada
agent.gateway.backend.selected	Backend selected
agent.gateway.handoff.started	Handoff iniciado
agent.gateway.handoff.completed	Handoff concluído
agent.gateway.sse.connected	Cliente SSE conectado
agent.gateway.request.failed	Failure of processing

---

Metrics

metric	Dimensões
gateway_requests_total	tenant, backend, agent, status
gateway_sessions_active	tenant
gateway_backend_selection_total	backend
gateway_handoff_total	origem, destino
gateway_latency_ms	backend
gateway_sse_connections	backend

---

Security

• Authentication obrigatória when configured.
• Propagação of Identity between gateways.
• Máscara of Data sensíveis em logs.
• correlation por request_id, trace_id and session_id.
• control of acesso por tenant.

---

Requirements No Funcionais

Categoria	Requirement
Availability	Expor /health and /ready
Escalabilidade	Stateless with escala horizontal
Observability	Logs, Metrics and traces
Auditabilidade	all as Decisions of Routing rastreáveis
Security	Segredos external and mascaramento
Portabilidade	Local, Docker and Kubernetes
Configuration	YAML and variáveis of ambiente

---

Acceptance criteria

• Recebe Messages of múltiplos canais.
• Seleciona backend corretamente.
• maintains Session global.
• Encaminha SSE.
• Executa handoff.
• Preserva Business Context.
• Suporta múltiplos backends.
• Allows discovery dynamic.
• Expõe Health and readiness.
• Gera Metrics and telemetria.