First commit

2026-07-09 14:04:19 +00:00 · 2026-06-19 22:17:09 -03:00
commit 239203ee2a
533 changed files with 75195 additions and 0 deletions
--- a/specs/SPEC-002-Agent-Runtime.md
+++ b/specs/SPEC-002-Agent-Runtime.md
@@ -0,0 +1,251 @@
+# SPEC-002 — Agent Runtime
+
+## Escopo
+
+O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
+
+## Componentes
+
+| Componente | Responsabilidade |
+|---|---|
+| Workflow Builder | Compila o grafo LangGraph. |
+| State Manager | Mantém o estado de execução. |
+| Session Manager | Resolve sessão e conversation_key. |
+| Memory Manager | Carrega e persiste histórico. |
+| Checkpoint Manager | Persiste estado LangGraph. |
+| Input Guardrail Node | Executa guardrails de entrada. |
+| Router Node | Decide rota/intent. |
+| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
+| Agent Node | Executa agente de domínio. |
+| MCP Client/Router | Executa tools por contrato. |
+| RAG Service | Recupera contexto documental. |
+| Output Supervisor | Revisa resposta antes de saída. |
+| Output Guardrail Node | Executa guardrails de saída. |
+| Judge Node | Avalia resposta. |
+| Persistence Node | Persiste mensagens, memória e checkpoint. |
+
+## State Model
+
+```python
+class AgentState(TypedDict, total=False):
+    user_text: str
+    sanitized_input: str
+    response_text: str
+    tenant_id: str
+    agent_id: str
+    channel: str
+    session_id: str
+    conversation_key: str
+    message_id: str
+    route: str
+    intent: str
+    context: dict
+    business_context: dict
+    tool_arguments: dict
+    mcp_tools: list[str]
+    mcp_results: list[dict]
+    rag_context: str
+    rag_metadata: dict
+    guardrails: list[dict]
+    judges: list[dict]
+    metadata: dict
+    errors: list[dict]
+```
+
+## Workflow
+
+```mermaid
+flowchart TD
+    A[start] --> B[input_guardrails]
+    B --> C[routing_decision]
+    C --> D[agent_execution]
+    D --> E[output_supervisor]
+    E --> F[output_guardrails]
+    F --> G[judge]
+    G --> H[persist]
+    H --> I[end]
+    C --> J[handoff]
+    J --> C
+```
+
+## Nós
+
+| Nó | Entrada | Saída |
+|---|---|---|
+| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
+| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
+| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
+| `output_supervisor` | `response_text` | `response_text` revisado |
+| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
+| `judge` | `response_text`, evidências | `judges` |
+| `persist` | `state` completo | checkpoint, memória, mensagens |
+
+## Router
+
+```yaml
+routing:
+  mode: router
+  fallback_agent: billing_agent
+  enable_llm_router: false
+  intents:
+    billing_invoice_explanation:
+      route: billing_agent
+      keywords:
+        - fatura
+        - cobrança
+        - boleto
+      mcp_tools:
+        - consultar_fatura
+        - consultar_pagamentos
+```
+
+## Supervisor
+
+```yaml
+supervisor:
+  enabled: true
+  profile: supervisor
+  max_turns: 5
+  handoff_enabled: true
+  fallback_route: support_agent
+```
+
+## Memory
+
+| Provider | Uso |
+|---|---|
+| `memory` | Execução local e testes. |
+| `sqlite` | Desenvolvimento local persistente. |
+| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
+| `autonomous` | Produção com Oracle Autonomous Database. |
+
+## Checkpoints
+
+Checkpoint contém:
+
+```json
+{
+  "conversation_key": "default:telecom_contas:session-001",
+  "checkpoint_id": "ckpt-001",
+  "state": {},
+  "pending_writes": [],
+  "created_at": "2026-06-19T12:00:00Z"
+}
+```
+
+Formato entregue ao LangGraph:
+
+```python
+pending_writes: list[tuple[str, str, object]]
+```
+
+## Business Context
+
+```yaml
+business_context:
+  customer_key: "11999999999"
+  contract_key: "3000131180"
+  interaction_key: "301953872"
+  account_key: null
+  resource_key: null
+  session_key: "session-001"
+  metadata:
+    source_channel: web
+```
+
+## Ordem de Prioridade dos Dados
+
+1. `tool_arguments`
+2. `business_context`
+3. `context`
+4. `session.metadata`
+5. `state`
+6. extração complementar do texto
+
+## MCP Integration
+
+```mermaid
+flowchart LR
+    AgentNode --> ToolList[mcp_tools]
+    ToolList --> Mapping[mcp_parameter_mapping.yaml]
+    Mapping --> MCP[MCP Gateway/Router]
+    MCP --> Result[mcp_results]
+```
+
+## RAG Integration
+
+```yaml
+rag:
+  enabled: true
+  namespace_strategy: agent_id
+  top_k: 5
+  profile_generation: rag_generation
+```
+
+## Eventos
+
+| Evento | Descrição |
+|---|---|
+| `runtime.started` | Execução iniciada. |
+| `runtime.session.loaded` | Sessão carregada. |
+| `runtime.memory.loaded` | Memória carregada. |
+| `runtime.checkpoint.loaded` | Checkpoint carregado. |
+| `runtime.route.selected` | Rota selecionada. |
+| `runtime.agent.started` | Agente iniciado. |
+| `runtime.agent.completed` | Agente concluído. |
+| `runtime.persist.completed` | Persistência concluída. |
+| `runtime.failed` | Falha controlada. |
+
+## Erros
+
+| Código | Condição | Tratamento |
+|---|---|---|
+| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
+| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
+| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
+| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
+| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
+| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
+
+
+## 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
+
+- [ ] Runtime recebe GatewayRequest validado.
+- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
+- [ ] Input guardrails executam antes do roteamento.
+- [ ] Router ou Supervisor seleciona rota.
+- [ ] Agent Node executa sem acessar payload bruto de canal.
+- [ ] MCP é acessado por contrato.
+- [ ] RAG é acessado por serviço reutilizável.
+- [ ] Output guardrails executam antes da resposta final.
+- [ ] Judges geram JudgeResult.
+- [ ] Memória e checkpoint são persistidos conforme provider.
+- [ ] Erros geram NOC e resposta controlada.
+
+
+## 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. |