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

```text
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:

```json
{
  "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:

```yaml
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:

```text
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

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

  telecom_ofertas:
    url: http://ofertas:8000
```

### discovery dynamic

```yaml
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

```json
{
  "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

```json
{
  "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.