First commit

2026-10-30 22:04:44 -03:00
commit 645ecdfb07
2794 changed files with 282545 additions and 0 deletions
--- a/specs/en/SPEC-003-Agent-Gateway.md
+++ b/specs/en/SPEC-003-Agent-Gateway.md
@@ -0,0 +1,273 @@
+# 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.