oracle/agent_framework_oci
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First commit

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-10-30 22:04:44 -03:00
commit 645ecdfb07
2794 changed files with 282545 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
specs/Disclaimer Auth and Security_PT.md Normal file
View File

@@ -0,0 +1,40 @@
### Recomendações de segurança, autenticação e autorização
Os componentes e templates deste framework podem ser adaptados a diferentes arquiteturas e requisitos de segurança. Para ambientes produtivos, recomenda-se que a solução seja avaliada de acordo com as políticas corporativas, os requisitos regulatórios aplicáveis e as melhores práticas de segurança da Oracle Cloud Infrastructure.
Como orientação geral, recomenda-se considerar autenticação e autorização em todas as interfaces acessíveis por usuários, canais, sistemas externos ou outros serviços. Na OCI, uma opção é utilizar o OCI API Gateway, ou uma camada equivalente, em conjunto com OAuth 2.0/OpenID Connect, validação de tokens e políticas de autorização por rota, scope, papel e tenant.
Métodos como HTTP Basic e API keys podem ser adequados para determinados cenários de integração, especialmente ambientes controlados ou sistemas legados. Nesses casos, recomenda-se utilizá-los sobre TLS, manter as credenciais em um serviço seguro de gerenciamento de segredos e adotar mecanismos de expiração e rotação.
A avaliação de segurança deve considerar, conforme os componentes utilizados pela solução:
- Agent Gateway, Channel Gateway e MCP Gateway;
- backends de agentes e comunicação entre gateways e backends;
- aplicações frontend e APIs consumidas pelo navegador;
- callbacks e webhooks provenientes de canais externos;
- conexões SSE, WebSocket ou outros mecanismos de streaming;
- histórico, memória, checkpoints e dados de sessão;
- endpoints administrativos, de debug, documentação, health e métricas;
- integrações com LLMs, bancos de dados, caches, mensageria e plataformas de observabilidade.
Recomenda-se tratar identificadores recebidos em payloads ou headers — como `tenant_id`, `agent_id`, `user_id`, `customer_id` e `session_id` — como informações de contexto, e não como evidência suficiente da identidade do solicitante. Quando aplicável, esses identificadores podem ser derivados de claims validadas ou relacionados à identidade autenticada antes da execução da operação.
Além da autenticação, recomenda-se avaliar a autorização sobre cada recurso acessado. Essa verificação pode considerar se o usuário ou serviço autenticado possui permissão para acessar o tenant, agente, sessão, histórico, checkpoint, backend ou ferramenta MCP solicitado.
Para comunicação entre serviços, podem ser consideradas identidades específicas por workload e mecanismos como OAuth 2.0 client credentials, OCI IAM, OKE Workload Identity, Instance Principals, Resource Principals ou mTLS. A escolha deve considerar a plataforma de execução e o modelo de confiança definido para a solução.
Para callbacks e webhooks, recomenda-se avaliar os mecanismos disponibilizados pelo provedor do canal, como assinatura digital ou HMAC, JWT, timestamp, identificador de mensagem, proteção contra replay e idempotência.
Em relação aos endpoints operacionais, é recomendável avaliar separadamente:
- endpoints de liveness, com resposta mínima sobre o estado do processo;
- endpoints de readiness, preferencialmente acessíveis apenas pela infraestrutura;
- endpoints de métricas, destinados aos coletores autorizados;
- endpoints de debug e teste, normalmente restritos a ambientes não produtivos;
- documentação OpenAPI, que pode ser desabilitada ou protegida em produção.
Também é recomendável utilizar TLS nas comunicações, restringir a exposição de serviços por meio de redes privadas, sub-redes, NSGs e allowlists, e considerar rate limiting, auditoria, rastreabilidade e monitoramento de acessos negados.
Segredos, tokens, senhas, certificados e chaves podem ser mantidos no OCI Secret Management ou em solução corporativa equivalente, evitando seu armazenamento em código-fonte ou arquivos de configuração versionados. Recomenda-se estabelecer políticas de acesso de menor privilégio, expiração e rotação compatíveis com a criticidade de cada credencial.
Estas recomendações representam uma referência inicial de melhores práticas. A definição final dos mecanismos de autenticação, autorização, proteção de rede e gestão de segredos permanece sob responsabilidade da equipe responsável pela arquitetura e pelo deployment, considerando o contexto, os riscos e os requisitos específicos de cada implementação.

40
specs/Disclaimer_Auth_and_Security_EN.md Normal file
View File

@@ -0,0 +1,40 @@
### Security, Authentication, and Authorization Recommendations
The components and templates in this framework can be adapted to different architectures and security requirements. For production environments, it is recommended that the solution be assessed in accordance with corporate policies, applicable regulatory requirements, and Oracle Cloud Infrastructure security best practices.
As general guidance, authentication and authorization should be considered for all interfaces accessible by users, channels, external systems, or other services. In OCI, one option is to use OCI API Gateway, or an equivalent layer, together with OAuth 2.0/OpenID Connect, token validation, and authorization policies based on route, scope, role, and tenant.
Methods such as HTTP Basic authentication and API keys may be suitable for certain integration scenarios, particularly in controlled environments or with legacy systems. In such cases, it is recommended that they be used over TLS, that credentials be stored in a secure secrets management service, and that expiration and rotation mechanisms be adopted.
The security assessment should consider, according to the components used by the solution:
- Agent Gateway, Channel Gateway, and MCP Gateway;
- agent backends and communication between gateways and backends;
- frontend applications and APIs consumed by the browser;
- callbacks and webhooks originating from external channels;
- SSE, WebSocket, or other streaming connections;
- history, memory, checkpoints, and session data;
- administrative, debug, documentation, health, and metrics endpoints;
- integrations with LLMs, databases, caches, messaging systems, and observability platforms.
Identifiers received in payloads or headers—such as `tenant_id`, `agent_id`, `user_id`, `customer_id`, and `session_id`—should be treated as contextual information rather than sufficient proof of the requester's identity. When applicable, these identifiers may be derived from validated claims or associated with the authenticated identity before the operation is executed.
In addition to authentication, authorization should be evaluated for each accessed resource. This verification may consider whether the authenticated user or service has permission to access the requested tenant, agent, session, history, checkpoint, backend, or MCP tool.
For service-to-service communication, dedicated workload identities and mechanisms such as OAuth 2.0 client credentials, OCI IAM, OKE Workload Identity, Instance Principals, Resource Principals, or mTLS may be considered. The choice should take into account the execution platform and the trust model defined for the solution.
For callbacks and webhooks, the mechanisms provided by the channel provider should be evaluated, such as digital signatures or HMAC, JWT, timestamps, message identifiers, replay protection, and idempotency.
Operational endpoints should also be evaluated separately:
- liveness endpoints, with a minimal response regarding the process status;
- readiness endpoints, preferably accessible only by the infrastructure;
- metrics endpoints, intended for authorized collectors;
- debug and test endpoints, typically restricted to non-production environments;
- OpenAPI documentation, which may be disabled or protected in production.
It is also recommended to use TLS for communications, restrict service exposure through private networks, subnets, NSGs, and allowlists, and consider rate limiting, auditing, traceability, and monitoring of denied access attempts.
Secrets, tokens, passwords, certificates, and keys may be stored in OCI Secret Management or an equivalent corporate solution, avoiding storage in source code or version-controlled configuration files. Least-privilege access policies, expiration, and rotation practices appropriate to the criticality of each credential should be established.
These recommendations provide an initial reference for best practices. The final definition of authentication, authorization, network protection, and secrets management mechanisms remains the responsibility of the team accountable for the architecture and deployment, taking into consideration the context, risks, and specific requirements of each implementation.

27
specs/README.md Normal file
View File

@@ -0,0 +1,27 @@
# Agent Platform OCI — SDD Clean V3
Pacote de SPECs técnicas em formato SDD.
## Arquivos
| Arquivo | Tema |
|---|---|
| SPEC-001-Architecture.md | Arquitetura da plataforma |
| SPEC-002-Agent-Runtime.md | Runtime LangGraph |
| SPEC-003-AI-Gateway.md | AI Gateway |
| SPEC-004-MCP-Gateway.md | MCP Gateway |
| SPEC-005-Guardrails.md | Guardrails |
| SPEC-006-Evals.md | Evals e certificação |
| SPEC-007-Observability.md | Observabilidade |
| SPEC-008-Deployment.md | CI/CD e deployment |
| SPEC-009-Channel-Gateway.md | Channel Gateway |
| SPEC-010-Agent-Development.md | Desenvolvimento de agentes |
## Padrão de escrita
- Especificação direta.
- Sem justificativas.
- Sem histórico.
- Sem defesa arquitetural.
- Sem comentários políticos.
- Com contratos, fluxos, configurações, eventos, métricas e critérios de aceite.

239
specs/SPEC-001-Architecture.md Normal file
View File

@@ -0,0 +1,239 @@
# SPEC-001 — Architecture
## Escopo
A Agent Platform OCI é composta por componentes reutilizáveis, aplicações deployáveis, contratos de integração, templates de agentes, camada de avaliação e artefatos de operação.
## Componentes
| Componente | Tipo | Responsabilidade |
|---|---|---|
| `libs/agent_framework` | Lib | Core reutilizável do framework. |
| `runtimes/langgraph_runtime` | Runtime | Execução de agentes baseada em LangGraph. |
| `apps/agent_gateway` | App | Entrada padronizada e roteamento de agentes/backends. |
| `apps/channel_gateway` | App | Normalização de canais externos. |
| `apps/ai_gateway` | App | Abstração, governança e roteamento de modelos. |
| `apps/mcp_gateway` | App | Governança, catálogo e execução de tools MCP. |
| `mcp/servers` | Apps | MCP servers de domínio. |
| `evals/offline` | App/Lib | Avaliação offline/batch. |
| `evals/certification` | Suite | Certificação técnica e funcional. |
| `templates/agent_template_backend` | Template | Scaffold para novos agentes. |
| `specs` | Documentação | Contratos SDD versionados. |
| `deploy` | Operação | Docker, Kubernetes e Helm. |
## Estrutura de Repositório
```text
agent_platform_oci/
├── libs/
│ └── agent_framework/
├── runtimes/
│ └── langgraph_runtime/
├── apps/
│ ├── agent_gateway/
│ ├── channel_gateway/
│ ├── ai_gateway/
│ └── mcp_gateway/
├── mcp/
│ └── servers/
├── evals/
│ ├── offline/
│ └── certification/
├── templates/
│ ├── agent_template_backend/
│ └── agent_template_backend_day_zero/
├── specs/
├── deploy/
│ ├── docker/
│ ├── k8s/
│ └── helm/
├── tests/
└── docs/
```
## Arquitetura Lógica
```mermaid
flowchart LR
C[Canal] --> CG[Channel Gateway]
CG --> AG[Agent Gateway]
AG --> RT[Agent Runtime]
RT --> FW[Agent Framework Core]
RT --> AIG[AI Gateway]
RT --> MCPG[MCP Gateway]
MCPG --> MCPS[MCP Servers]
RT --> OBS[Observability]
RT --> MEM[Memory/Checkpoint]
OBS --> LF[Langfuse/OTEL]
LF --> EV[Evaluator]
```
## Arquitetura Física
| Serviço | Porta Padrão | Deploy | Escala |
|---|---:|---|---|
| Agent Gateway | 9000 | Kubernetes Deployment | Horizontal |
| Agent Backend / Runtime | 8000 | Kubernetes Deployment | Horizontal com storage externo |
| Channel Gateway | 7000 | Kubernetes Deployment | Horizontal |
| AI Gateway | 9100 | Kubernetes Deployment | Horizontal |
| MCP Gateway | 8300 | Kubernetes Deployment | Horizontal |
| MCP Servers | 8001+ | Kubernetes Deployment | Por domínio |
| Evaluator API | 9300 | Deployment/CronJob | Por carga batch |
| Frontend Demo | 5173 | Opcional | Não crítico |
## Contratos Principais
| Contrato | Produtor | Consumidor |
|---|---|---|
| GatewayRequest | Channel Gateway / Agent Gateway | Agent Runtime |
| ChannelResponse | Agent Runtime | Channel Gateway / Cliente |
| BusinessContext | Channel Gateway / Identity Resolver | Runtime / Agents / MCP |
| LLMRequest | Agent Runtime | AI Gateway |
| LLMResponse | AI Gateway | Agent Runtime |
| ToolInvocation | Agent Runtime / MCP Gateway | MCP Server |
| ToolResult | MCP Server / MCP Gateway | Agent Runtime |
| GuardrailResult | Guardrail Engine | Runtime / Observability |
| JudgeResult | Judge Engine / Evaluator | Runtime / Evaluator |
| EvaluationRun | Evaluator | Persistence / Dashboards |
## GatewayRequest
```json
{
"channel": "web",
"tenant_id": "default",
"agent_id": "telecom_contas",
"payload": {
"message": "Quero consultar minha fatura",
"session_id": "session-001",
"user_id": "user-001",
"message_id": "msg-001",
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"interaction_key": "301953872",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001"
}
}
}
```
## ChannelResponse
```json
{
"channel": "web",
"session_id": "default:telecom_contas:session-001",
"text": "Resposta final do agente.",
"metadata": {
"tenant_id": "default",
"agent_id": "telecom_contas",
"route": "billing_agent",
"intent": "billing_invoice_explanation"
}
}
```
## Fluxo Principal
```mermaid
sequenceDiagram
participant Canal
participant ChannelGateway
participant AgentGateway
participant Runtime
participant AIGateway
participant MCPGateway
participant Store
Canal->>ChannelGateway: Payload bruto
ChannelGateway->>AgentGateway: GatewayRequest
AgentGateway->>Runtime: GatewayRequest normalizado
Runtime->>Store: Sessão, memória e checkpoint
Runtime->>Runtime: Guardrails de entrada
Runtime->>Runtime: Router/Supervisor
Runtime->>MCPGateway: ToolInvocation
MCPGateway-->>Runtime: ToolResult
Runtime->>AIGateway: LLMRequest
AIGateway-->>Runtime: LLMResponse
Runtime->>Runtime: Guardrails de saída e Judges
Runtime->>Store: Persistência
Runtime-->>AgentGateway: ChannelResponse
AgentGateway-->>ChannelGateway: ChannelResponse
ChannelGateway-->>Canal: Resposta do canal
```
## Configuração
| Arquivo | Uso |
|---|---|
| `.env` | Provider, autenticação, flags e endpoints por ambiente. |
| `agents.yaml` | Registro de agentes. |
| `routing.yaml` | Intents, rotas, políticas e fallback. |
| `guardrails.yaml` | Guardrails globais. |
| `judges.yaml` | Judges globais. |
| `llm_profiles.yaml` | Profiles de modelos por componente. |
| `mcp_servers.yaml` | MCP servers disponíveis. |
| `tools.yaml` | Catálogo de tools. |
| `mcp_parameter_mapping.yaml` | Mapeamento BusinessContext → argumentos MCP. |
| `identity.yaml` | Resolução de identidade de negócio. |
| `observability.yaml` | Logs, métricas, traces e exporters. |
| `evals.yaml` | Datasets, métricas e configuração do evaluator. |
## Eventos
| Evento | Origem | Descrição |
|---|---|---|
| `gateway.request.received` | Agent Gateway | Requisição recebida. |
| `channel.normalized` | Channel Gateway | Payload convertido em GatewayRequest. |
| `runtime.started` | Runtime | Execução iniciada. |
| `guardrail.input.completed` | Guardrails | Guardrails de entrada concluídos. |
| `route.selected` | Router/Supervisor | Rota definida. |
| `mcp.tool.completed` | MCP Gateway | Tool executada. |
| `llm.completed` | AI Gateway | Chamada LLM concluída. |
| `judge.completed` | Judge Engine | Avaliação concluída. |
| `runtime.completed` | Runtime | Execução finalizada. |
## 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
- [ ] Estrutura de repositório separa libs, runtimes, apps, mcp, evals, templates, specs e deploy.
- [ ] Cada app deployável possui contrato de entrada/saída documentado.
- [ ] GatewayRequest e ChannelResponse estão versionados.
- [ ] BusinessContext é usado como contrato canônico.
- [ ] Runtime não recebe payload bruto de canal.
- [ ] AI Gateway e MCP Gateway possuem fronteiras explícitas.
- [ ] Evaluator é componente padronizado de avaliação.
- [ ] Todos os serviços possuem health check.
- [ ] Telemetria fim-a-fim correlaciona request_id, trace_id e session_id.
- [ ] Configurações críticas possuem YAML dedicado.
## 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. |

331
specs/SPEC-002-Agent-Runtime.md Normal file
View File

@@ -0,0 +1,331 @@
# SPEC-002 — Agent Runtime
## 1. Visão geral
O Agent Runtime coordena a execução conversacional dos agentes da plataforma OCI. O runtime combina grafos LangGraph, estado por conversa, roteamento de intenções, agentes de domínio, guardrails, judges, memória de longo prazo e persistência. A biblioteca reutilizável do framework fornece serviços e contratos consumidos pelos backends; o backend de referência `agent_template_backend` compõe esses serviços em um workflow executável.
## 2. Organização da implementação
| Elemento | Localização | Função |
|---|---|---|
| Runtime compartilhado | `libs/agent_framework/src/agent_framework/runtime/` | Capacidades reutilizáveis para execução dos agentes. |
| Workflow de referência | `templates/agent_template_backend/app/workflows/agent_graph.py` | Construção do grafo e implementação dos nós do workflow. |
| Estado do workflow | `templates/agent_template_backend/app/state.py` | Definição tipada dos dados transportados entre nós. |
| Configuração dos agentes | `templates/agent_template_backend/config/agents.yaml` | Cadastro de agentes e caminhos de políticas/configurações. |
| Configuração de roteamento | `templates/agent_template_backend/config/routing.yaml` | Modo do roteador, fallback, limiar e catálogo de intenções. |
| Configuração das ferramentas | `templates/agent_template_backend/config/tools.yaml` | Definições de ferramentas utilizadas pelos agentes. |
## 3. Estado de execução
O workflow utiliza o `AgentState` abaixo. A declaração `TypedDict(total=False)` permite que os nós adicionem os campos pertinentes a cada etapa sem exigir a presença de todos os campos em cada estado.
```python
from typing import Any, TypedDict
class AgentState(TypedDict, total=False):
tenant_id: str
agent_id: str
session_id: str
conversation_key: str
workflow_id: str
agent_profile: dict[str, Any]
user_text: str
sanitized_input: str
route: str
intent: str
route_decision: dict[str, Any]
answer: str
final_answer: str
history: list[dict[str, Any]]
context: dict[str, Any]
guardrail_decisions: list[dict[str, Any]]
judge_results: list[dict[str, Any]]
next_state: str
domain: str
mcp_tools: list[str]
mcp_results: list[dict[str, Any]]
rag_results: list[dict[str, Any]]
available_mcp_tools: list[str]
selected_tool_call: dict[str, Any]
pending_tool_call: dict[str, Any]
active_transaction: dict[str, Any]
last_transaction: dict[str, Any]
transaction_status: str
transaction_pre_validation: dict[str, Any]
transaction_evidence: list[dict[str, Any]]
last_transaction_evidence: dict[str, Any]
relevant_transaction_evidence: list[dict[str, Any]]
confirmation_required: bool
confirmation_received: bool
tool_policy_result: dict[str, Any]
missing_parameters: list[str]
supervisor_plan: dict[str, Any]
supervisor_results: list[dict[str, Any]]
agent_responses: list[dict[str, Any]]
pending_topics: list[dict[str, Any]]
handled_topics: list[dict[str, Any]]
operation_results: dict[str, dict[str, Any]]
multi_intent_plan: dict[str, Any]
active_agent: str
route_bypassed: bool
continuity_signal: dict[str, Any]
session_control: str
session_ended: bool
human_handoff_requested: bool
blocked: bool
supervisor_action: str
supervisor_guidance: str
supervisor_attempt: int
supervisor_handover_reason: str
output_supervisor_results: list[dict[str, Any]]
output_guardrails_already_applied: bool
long_term_memories: list[dict[str, Any]]
long_term_memory_context: str
long_term_memory_write_result: dict[str, Any]
long_term_memory_subject_key: str
long_term_memory_load_error: str
```
## 4. Fluxo de execução
O workflow é compilado com `FrameworkStateGraph(AgentState)` e utiliza um checkpointer criado por `create_langgraph_checkpointer(self.settings)`.
```mermaid
flowchart TD
START([START]) --> input_guardrails
input_guardrails -->|continue| load_long_term_memory
input_guardrails -->|blocked| output_guardrails
load_long_term_memory --> routing_decision
routing_decision --> billing_agent
routing_decision --> product_agent
routing_decision --> orders_agent
routing_decision --> support_agent
routing_decision --> handoff
routing_decision --> human_handoff
routing_decision --> end_session
routing_decision --> supervisor_agent
billing_agent --> output_supervisor
product_agent --> output_supervisor
orders_agent --> output_supervisor
support_agent --> output_supervisor
handoff --> output_supervisor
human_handoff --> output_supervisor
end_session --> output_supervisor
supervisor_agent --> output_supervisor
output_supervisor --> output_guardrails
output_guardrails -->|continue| judge
output_guardrails -->|blocked| persist
judge --> supervisor_review
supervisor_review --> persist_long_term_memory
persist_long_term_memory --> persist
persist --> END([END])
```
O roteamento após `input_guardrails` depende de `state['blocked']`. Após `routing_decision`, a rota em `state['route']` seleciona um dos nós registrados, com valor padrão `billing_agent` quando a chave não está presente. O roteamento após `output_guardrails` também consulta `state['blocked']`.
## 5. Nós do workflow
| Nó | Responsabilidade |
|---|---|
| `input_guardrails` | Avalia e processa a entrada antes do roteamento. |
| `load_long_term_memory` | Carrega contexto de memória de longo prazo. |
| `routing_decision` | Determina o destino de execução da conversa. |
| `billing_agent` | Executa o agente de faturamento. |
| `product_agent` | Executa o agente de produtos e serviços. |
| `orders_agent` | Executa o agente de pedidos. |
| `support_agent` | Executa o agente de suporte. |
| `handoff` | Processa o fluxo de transferência previsto pelo workflow. |
| `human_handoff` | Processa a solicitação de transferência para atendimento humano. |
| `end_session` | Processa o encerramento de sessão. |
| `supervisor_agent` | Executa o fluxo associado ao supervisor. |
| `output_supervisor` | Processa a etapa de supervisão da resposta. |
| `output_guardrails` | Aplica as políticas de saída. |
| `judge` | Realiza a avaliação da resposta. |
| `supervisor_review` | Processa a revisão após o judge. |
| `persist_long_term_memory` | Executa a etapa de escrita de memória de longo prazo. |
| `persist` | Executa a etapa final de persistência do workflow. |
Os nós são encapsulados pelo método `_node`, que os executa no contexto `self.langgraph_telemetry.node(name, state)`.
## 6. Roteamento
O arquivo `config/routing.yaml` define as opções principais sob a chave `router`:
```yaml
# Roteamento enterprise configurável com MCP-aware intents.
router:
# mode também pode ser definido por variável de ambiente ROUTING_MODE.
# Valores: router | supervisor
mode: router
fallback_agent: billing_agent
confidence_threshold: 0.65
allow_handoff: true
```
A configuração contém também `state_policies` para manter determinadas etapas de confirmação ou coleta vinculadas ao agente correspondente, além do catálogo `intents` com atributos como `name`, `domain`, `agent`, `priority`, `mcp_tools`, `keywords` e `examples`.
O catálogo de agentes em `config/agents.yaml` declara os agentes `telecom_contas` e `retail_orders`. Cada registro aponta para arquivos de política de prompts, roteamento, guardrails, judges, servidores MCP e ferramentas, além de metadados do domínio.
## 7. Execução dos agentes e ferramentas
Os nós de domínio encaminham a solicitação para as instâncias dos agentes de faturamento, produtos, pedidos e suporte. A integração com ferramentas MCP é disponibilizada aos agentes por meio da configuração de ferramentas e dos componentes de roteamento de tools. Os resultados de ferramentas podem ser transportados no estado pelo campo `mcp_results`; os nomes selecionados ficam em `mcp_tools`.
O estado também comporta `selected_tool_call`, `pending_tool_call`, `tool_policy_result`, `missing_parameters` e os campos de evidências transacionais. Esses elementos permitem que etapas de preparação, validação, confirmação e execução compartilhem informações ao longo da conversa.
## 8. Estado transacional
O `AgentState` mantém em `active_transaction` os dados da transação em andamento e em `last_transaction` o registro da última transação encerrada. Os campos `transaction_status`, `transaction_pre_validation`, `transaction_evidence`, `last_transaction_evidence`, `relevant_transaction_evidence`, `confirmation_required` e `confirmation_received` transportam as informações necessárias ao processamento transacional.
A configuração de roteamento inclui políticas de estado para as etapas `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION`, `WAITING_ORDER_CONFIRMATION`, `WAITING_SUPPORT_CONFIRMATION`, `COLLECTING_BILLING_PARAMETERS`, `COLLECTING_PRODUCT_PARAMETERS`, `COLLECTING_ORDER_PARAMETERS` e `COLLECTING_SUPPORT_PARAMETERS`.
A documentação de referência dos fluxos transacionais encontra-se em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
## 9. Memória e checkpoints
O workflow integra duas etapas explícitas de memória de longo prazo: `load_long_term_memory`, anterior ao roteamento, e `persist_long_term_memory`, anterior à persistência final. Os campos `long_term_memories`, `long_term_memory_context`, `long_term_memory_write_result`, `long_term_memory_subject_key` e `long_term_memory_load_error` compõem a interface de estado dessa capacidade.
A construção do grafo fornece o resultado de `create_langgraph_checkpointer(self.settings)` ao método `compile`. O armazenamento e a recuperação dos checkpoints são executados pelo checkpointer configurado, preservando a continuidade do estado entre interações conforme o backend selecionado.
## 10. Guardrails, supervisão e judges
A entrada é submetida a `input_guardrails` antes da carga de memória e do roteamento. Quando a entrada é bloqueada, o fluxo segue diretamente para `output_guardrails`.
As respostas dos agentes passam por `output_supervisor` e `output_guardrails`. Uma resposta não bloqueada segue para `judge` e `supervisor_review`; uma resposta bloqueada segue para `persist`. Os resultados são transportados nos campos `guardrail_decisions`, `output_supervisor_results`, `judge_results`, `supervisor_action`, `supervisor_guidance` e campos correlatos do estado.
## 11. Observabilidade
O workflow envolve cada nó com a instrumentação `langgraph_telemetry.node`. Essa instrumentação associa a execução à identificação do nó e ao estado da conversa. A rastreabilidade das decisões e etapas de execução é tratada pelos mecanismos de telemetria e observabilidade do framework.
## 12. Tratamento de erros e recuperação por componente
### 12.1. Princípios de propagação de falhas
O runtime distingue falhas absorvidas pela própria etapa, resultados negativos de políticas/ferramentas e exceções que impedem a execução do grafo. O contrato de cada componente determina se o processamento continua, se a resposta é alterada ou se a exceção é devolvida ao chamador. O campo `blocked` indica uma decisão de política no estado, e não equivale genericamente a uma exceção Python.
| Área | Representação utilizada | Efeito na execução |
|---|---|---|
| Guardrails | Decisões com `allowed`, `code` e `reason`; decisões da supervisão com `action` | Pode interromper roteamento, substituir/sanitizar a resposta ou continuar. |
| MCP | Resultado de ferramenta com `ok`, `error`, `tool_name` e informações de execução conforme a origem | O agente utiliza o resultado para controlar a continuação da operação. |
| Memória de longo prazo | Campos `long_term_memory_load_error` e `long_term_memory_write_result` | Uma falha de leitura ou escrita capturada no nó não encerra o grafo. |
| RAG | Resultado de recuperação ou objeto de erro técnico | A falha pode ser incorporada ao contexto de execução do agente. |
| Checkpoints | Exceções do repositório, verificação de integridade e recuperação de versões | A leitura pode selecionar checkpoint válido anterior ou iniciar estado limpo; falhas de armazenamento esgotadas são propagadas. |
| Workflow | Exceções emitidas pelos nós ou por `graph.ainvoke` | A execução é marcada como falha na telemetria; a exceção é relançada. |
### 12.2. Entrada, sessão e guardrails de entrada
O nó `input_guardrails` verifica primeiro `session_ended`. Caso a sessão já esteja encerrada, define `blocked=True`, `session_control="END_SESSION"`, `session_ended=True` e `next_state="SESSION_ENDED"`, compõe a mensagem configurada em `SESSION_ALREADY_ENDED_MESSAGE` e registra `session.message.rejected_after_end`. Essa condição impede que a mensagem prossiga para roteamento e agentes.
Para mensagens de sessões ativas, o pipeline avalia os guardrails e guarda as decisões em `guardrail_decisions`. Se alguma decisão possuir `allowed=False`, o nó produz uma resposta segura, estabelece `route="blocked"`, `intent="input_guardrail_blocked"`, limpa as listas de ferramentas e resultados MCP daquele turno e segue pelo ramo de saída. A função `_input_guardrail_user_message` contém respostas específicas para `COER`, `INPUT_SIZE`, `DLEX_IN`, `PINJ`, `TOX` e `CMP`, além de uma resposta padrão para os demais códigos. O motivo detalhado permanece nas decisões e na telemetria; a mensagem ao usuário é controlada pelo runtime.
A avaliação registra `guardrails.input.completed`, decisões individuais na telemetria de guardrails e eventos GRL por meio do observer. No bloqueio de entrada, não são executados o nó de memória anterior ao roteamento, o roteador nem ferramentas do agente. O ramo segue para `output_guardrails` e, conforme as condições do grafo, termina em `persist`.
**Referência:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`input_guardrails`, `_input_guardrail_user_message`, `_after_input_guardrails`).
### 12.3. Roteamento, classificação e continuidade
A configuração do roteamento é carregada por `routing/config_loader.py`; a ausência do arquivo resulta em `FileNotFoundError`. O `EnterpriseRouter` contém tratamento localizado para erros de chamadas de classificação e de interpretação das saídas do modelo. No classificador semântico de entradas esperadas, uma falha de `llm.ainvoke` é registrada com `logger.warning` e a função retorna `(None, None)`, permitindo o uso dos caminhos subsequentes do roteamento em vez de transformar essa falha em uma classificação válida.
O fluxo utiliza as configurações `fallback_agent` e `confidence_threshold`, assim como políticas de estado em `routing.yaml`. A seleção de fallback é uma decisão de roteamento; não constitui, por si só, um código de erro. As estruturas `route_decision`, `continuity_signal`, `pending_topics` e `multi_intent_plan` preservam informações para retomada e roteamento de turnos correlatos.
A recuperação de falhas deve ser interpretada conforme o método efetivamente invocado: nem todo erro interno de roteamento é absorvido pelo mesmo `except`; exceções que escapem do nó alcançam o tratamento de falha do workflow em `ainvoke`.
**Referências:** `libs/agent_framework/src/agent_framework/routing/config_loader.py`, `routing/enterprise_router.py`, `routing/continuity.py`; `templates/agent_template_backend/app/workflows/agent_graph.py` (`routing_decision`, `ainvoke`).
### 12.4. Execução de agentes, argumentos e ferramentas MCP
A preparação das ferramentas é realizada pelo runtime reutilizável em `runtime/agent_runtime.py`. O método `_prepare_mcp_call` consulta o roteador MCP e devolve o erro de preparação como resultado estruturado quando `prepare_call` o retorna. Se o roteador de ferramentas não estiver disponível, o runtime produz um resultado negativo com `ok=False`, `tool_name` e a descrição `MCP Tool Router indisponível`.
No mapeamento de parâmetros, erros de expressão regular (`re.error`, `IndexError`, `ValueError`) são capturados e registrados como `mcp.parameter.regex_extract_failed`. Na extração por LLM, indisponibilidade do modelo ou da mensagem e exceções de inferência são registradas como `mcp.parameter.llm_extract_failed`. O processamento dos argumentos e o retorno da chamada continuam sujeitos à validação da ferramenta e às políticas do agente; não se assume sucesso pela simples ausência de exceção.
Resultados MCP podem expor `ok=False` e um campo `error`, inclusive para falhas de validação e execução. A implementação emite `NOC.MCP_TOOL_FAILED` em um dos caminhos que agregam resultados negativos de ferramentas. O tratamento de transações, confirmações, evidências e resultados parciais é realizado sobre os dados de execução, incluindo `active_transaction`, `transaction_pre_validation`, `transaction_evidence` e `operation_results`, conforme o tipo de operação.
**Referência:** `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py` (`_prepare_mcp_call`, processamento de parâmetros, execução e agregação de resultados das ferramentas).
### 12.5. RAG e recuperação de conhecimento
O runtime encapsula falhas de recuperação de conhecimento em um resultado técnico que inclui `technical_error=True`, `technical_error_in_rag=True`, `status="error"` e a descrição em `error`. Essa representação permite que o agente diferencie falha de recuperação de uma busca concluída sem evidência útil.
O serviço RAG também valida pré-condições: `RagService.generate_answer` lança `RuntimeError` quando utilizado sem LLM, e o `kbdb_service.py` possui verificações de configuração/assinatura e impede operações de ingestão/publicação quando o provider KBDB está configurado exclusivamente para serving. Na ingestão, diretório inexistente pode produzir `FileNotFoundError` e `chunk_overlap >= chunk_size` produz `ValueError`. Esses erros de inicialização e administração não devem ser confundidos com um resultado de busca vazio em atendimento.
**Referências:** `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py` (tratamento técnico RAG); `rag/rag_service.py`, `rag/kbdb_service.py`, `rag/ingest.py`.
### 12.6. Memória de longo prazo
O nó `load_long_term_memory` captura exceções do `long_term_memory_manager.load(state)`. Quando a leitura falha, publica `long_term_memory.load.failed`, retorna `long_term_memories=[]`, `long_term_memory_context=""` e registra a exceção textual em `long_term_memory_load_error`. A conversa continua sem o contexto de memória recuperado naquele turno.
O nó `persist_long_term_memory` captura exceções do `long_term_memory_manager.persist_turn(state)`. Uma gravação concluída publica `long_term_memory.persist.completed` e armazena seu retorno em `long_term_memory_write_result`; uma falha publica `long_term_memory.persist.failed` e retorna `{"saved": 0, "error": str(exc)}` no mesmo campo. A falha de persistência de memória de longo prazo é, portanto, isolada no nó e não provoca automaticamente o encerramento excepcional do grafo.
Esses campos descrevem a memória de longo prazo do workflow e são distintos da persistência de checkpoints LangGraph.
**Referência:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`load_long_term_memory`, `persist_long_term_memory`).
### 12.7. Checkpoints, tentativas e integridade
O grafo é compilado com o checkpointer criado por `create_langgraph_checkpointer(self.settings)` e utiliza `conversation_key` ou `session_id` como `thread_id` em `ainvoke`. A camada de repositório em `checkpoints/checkpoint_repository.py` implementa tentativas para operações protegidas por `_with_retry`: após uma exceção, calcula espera exponencial limitada com jitter, registra `checkpoint.<operation>.retry` e tenta novamente até `retry_policy.max_attempts`. Esgotadas as tentativas, relança a última exceção.
Na recuperação, `recover_latest` examina registros recentes, desconsidera registros que não satisfazem `is_valid_checkpoint` e ignora checkpoints com `CheckpointIntegrityError`, registrando `checkpoint.recovery.skip_corrupt`. Quando não resta checkpoint válido após falhas de integridade, a recuperação retorna `None` para permitir início sem estado restaurado. A compactação executada após uma gravação é isolada: uma falha registra `checkpoint.compaction.failed` e não desfaz a gravação já concluída.
A estratégia de recuperação de integridade não garante preservação do histórico se nenhum checkpoint válido puder ser recuperado. Falhas de comunicação com o armazenamento que excedam a política de retry seguem o caminho de exceção do componente que invocou a operação.
**Referências:** `libs/agent_framework/src/agent_framework/checkpoints/checkpoint_repository.py`, `checkpoints/langgraph_saver.py`; `templates/agent_template_backend/app/workflows/agent_graph.py` (`ainvoke`).
### 12.8. Supervisão de saída e guardrails de saída
O `output_supervisor` avalia a resposta e interpreta `RailAction`. Para `ALLOW`, `SANITIZE` e `OBSERVE`, utiliza `decision.candidate`; para `HANDOVER`, entrega uma mensagem de encaminhamento ao especialista; para as demais ações, utiliza `decision.fallback_message`. A ação, orientação e resultados são gravados em `supervisor_action`, `supervisor_guidance` e `output_supervisor_results`.
O nó marca `output_guardrails_already_applied=True`. Quando `output_guardrails` recebe esse sinal, retorna a resposta já preparada sem executar novamente o pipeline. Caso contrário, executa `guardrails.run_output`, registra as decisões, os bloqueios e a conclusão GRL, e devolve `final_answer`.
O executor paralelo de rails (`guardrails/parallel_executor.py`) converte falhas inesperadas de tarefas em `RailResult`: escolhe `RailAction.BLOCK` quando `fail_closed` está ativo e `RailAction.OBSERVE` no outro caso. Esse comportamento é uma política do executor e não implica que todo guardrail falhe fechado. O executor também administra cancelamentos e término antecipado quando uma ação terminal é produzida.
**Referências:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`output_supervisor`, `output_guardrails`); `libs/agent_framework/src/agent_framework/guardrails/parallel_executor.py`.
### 12.9. Judges e revisão do supervisor
O nó `judge` constrói o contexto de avaliação com resultados MCP, RAG e evidências transacionais relevantes, executa a avaliação e grava os resultados em `judge_results`. A revisão posterior utiliza `self.supervisor.review` e registra `supervisor.review.completed`. Uma reprovação ou recomendação de um judge integra o mecanismo de avaliação e revisão; não é, por definição, uma exceção de infraestrutura.
A camada de judges contém validação de configuração e de resposta estruturada. O cliente do judge calibrado lança `ValueError` para tarefas não suportadas e quando a saída estruturada é inválida. A construção do LLM e a leitura de configurações de judges também podem produzir `RuntimeError` ou `ValueError` nas condições verificadas em `judges/judge.py`. As exceções não capturadas pelo nó propagam-se para `ainvoke`.
**Referências:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`judge`, `supervisor_review`); `libs/agent_framework/src/agent_framework/judges/judge.py`, `judges/calibrated/llm_client.py`.
### 12.10. Persistência final e falha global do workflow
O nó `persist` produz a observabilidade de conclusão do atendimento, incluindo o evento IC `AGENT_COMPLETED`. A execução pública do grafo acontece em `ainvoke`, que cria a configuração de thread, inicia a telemetria de workflow e emite os eventos de início `NOC.001` e `AGENT_STARTED` antes de invocar `self.graph.ainvoke`.
Se `graph.ainvoke` conclui, o workflow é marcado como concluído e seu estado final é retornado. Se uma exceção escapa do grafo, o `except Exception` de `ainvoke` chama `workflow_telemetry.failed("agent_workflow", exc)`, emite `NOC.005` com `error` e `exception_type` e relança a mesma exceção. Nesse caminho, o método não converte automaticamente o erro em uma resposta conversacional de sucesso.
Falhas absorvidas por nós como memória de longo prazo não acionam esse `except` global. Já erros não tratados durante roteamento, execução dos agentes, salvamento de checkpoints ou outras etapas podem alcançar esse limite e produzir a falha geral do workflow.
**Referência:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`persist`, `ainvoke`).
### 12.11. Eventos e rastreamento operacional
A instrumentação `_node` envolve a execução de cada nó em `self.langgraph_telemetry.node(name, state)`. Os mecanismos complementares usam spans de workflow, eventos semânticos e o observer para GRL, IC e NOC. Entre os registros concretos presentes no fluxo estão `session.message.rejected_after_end`, `guardrails.input.completed`, `guardrails.output.completed`, `output_supervisor.completed`, `supervisor.review.completed`, `long_term_memory.load.failed`, `long_term_memory.persist.failed`, `long_term_memory.persist.completed` e `workflow_telemetry.failed` na falha global.
Erros operacionais devem ser correlacionados por `conversation_key` ou `session_id`, juntamente com `tenant_id` e `agent_id` quando disponíveis. A ocorrência de um evento de falha de memória ou de ferramenta não implica necessariamente falha global do workflow; a determinação depende de o componente ter retornado um estado/resultado ou propagado uma exceção.
**Referências:** `templates/agent_template_backend/app/workflows/agent_graph.py`; `libs/agent_framework/src/agent_framework/observability/`.
## 13. Interfaces de integração
| Interface | Integração no runtime |
|---|---|
| LangGraph | Construção, compilação e execução do grafo de estado. |
| Agentes de domínio | Nós especializados para faturamento, produtos, pedidos e suporte. |
| MCP | Seleção, parametrização e execução de ferramentas pelos agentes. |
| RAG | Recuperação de informações incorporada à execução dos agentes. |
| Guardrails | Avaliação da entrada e da saída. |
| Judges | Avaliação posterior à geração da resposta. |
| Memória | Leitura e escrita de informações de longo prazo. |
| Checkpointer | Persistência do estado do grafo. |
| Observabilidade | Telemetria por nó e rastreamento do processamento. |
## 14. Referências de implementação
- `libs/agent_framework/src/agent_framework/runtime/`
- `templates/agent_template_backend/app/state.py`
- `templates/agent_template_backend/app/workflows/agent_graph.py`
- `templates/agent_template_backend/config/agents.yaml`
- `templates/agent_template_backend/config/routing.yaml`
- `templates/agent_template_backend/config/tools.yaml`
- [`SPEC-004 — MCP Gateway`](SPEC-004-MCP-Gateway.md)
- [`SPEC-005 — Guardrails`](SPEC-005-Guardrails.md)
- [`SPEC-007 — Observability`](SPEC-007-Observability.md)
- [`SPEC-012 — Canonical Contracts`](SPEC-012-Canonical-Contracts.md)

273
specs/SPEC-003-Agent-Gateway.md Normal file
View File

@@ -0,0 +1,273 @@
# SPEC-003 — Agent Gateway
## Escopo
O Agent Gateway é o ponto único de entrada da plataforma para canais e consumidores externos.
Sua responsabilidade é receber mensagens, gerenciar sessões globais, resolver o backend/agente responsável, executar roteamento, realizar handoff entre agentes/backends e encaminhar eventos SSE.
O Agent Gateway não executa inferência LLM nem embeddings. Essas capacidades pertencem ao Runtime e ao Agent Framework.
---
## Responsabilidades
### Entrada Única da Plataforma
```text
Web
WhatsApp
Voice
Teams
Slack
|
v
Agent Gateway
|
+--> Agent Backend A
|
+--> Agent Backend B
|
+--> Agent Backend C
```
### Gerenciamento de Sessões
Responsável por:
- Criação de sessões
- Recuperação de sessões
- Atualização de contexto global
- Persistência de metadados de sessão
- Correlação de requisições
Exemplo:
```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 deve processar a mensagem.
Exemplo:
```yaml
backends:
telecom_contas:
url: http://backend-contas:8000
telecom_ofertas:
url: http://backend-ofertas:8000
```
Critérios possíveis:
- Backend padrão
- Regras YAML
- Intenção detectada
- Contexto da sessão
- Router LLM (opcional)
---
## Handoff
Permite transferência entre agentes ou backends.
Exemplo:
```text
Contas
|
+--> Ofertas
|
+--> Retenção
```
O handoff deve preservar:
- session_id
- conversation_key
- business context
- histórico da conversa
- metadados de correlação
---
## SSE Proxy
Responsável por encaminhar eventos de streaming para clientes.
### Endpoints
| Método | Endpoint |
|----------|----------|
| POST | /gateway/message |
| POST | /gateway/message/sse |
| GET | /gateway/events/{session_id} |
Eventos SSE suportados:
- connected
- workflow.started
- message.responded
- workflow.completed
- flow.end
- error
---
## Backend Discovery
Pode operar com catálogo estático ou descoberta dinâmica.
### Catálogo Estático
```yaml
backends:
telecom_contas:
url: http://contas:8000
telecom_ofertas:
url: http://ofertas:8000
```
### Descoberta Dinâmica
```yaml
service_discovery:
enabled: true
```
Capacidades:
- Registro automático
- Health check periódico
- Atualização de catálogo
- Sincronização de metadados
---
## Health e Operação
### Endpoints
| Método | Endpoint |
|----------|----------|
| GET | /health |
| GET | /ready |
| GET | /backends |
| GET | /debug/sessions |
---
## Contrato 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"
}
}
```
---
## Contrato 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"
}
}
```
---
## Eventos
| Evento | Descrição |
|----------|----------|
| agent.gateway.request.received | Requisição recebida |
| agent.gateway.session.created | Sessão criada |
| agent.gateway.backend.selected | Backend selecionado |
| agent.gateway.handoff.started | Handoff iniciado |
| agent.gateway.handoff.completed | Handoff concluído |
| agent.gateway.sse.connected | Cliente SSE conectado |
| agent.gateway.request.failed | Falha de processamento |
---
## Métricas
| Métrica | 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 |
---
## Segurança
- Autenticação obrigatória quando configurada.
- Propagação de identidade entre gateways.
- Máscara de dados sensíveis em logs.
- Correlação por request_id, trace_id e session_id.
- Controle de acesso por tenant.
---
## Requisitos Não Funcionais
| Categoria | Requisito |
|----------|----------|
| Disponibilidade | Expor /health e /ready |
| Escalabilidade | Stateless com escala horizontal |
| Observabilidade | Logs, métricas e traces |
| Auditabilidade | Todas as decisões de roteamento rastreáveis |
| Segurança | Segredos externos e mascaramento |
| Portabilidade | Local, Docker e Kubernetes |
| Configuração | YAML e variáveis de ambiente |
---
## Critérios de Aceite
- [ ] Recebe mensagens de múltiplos canais.
- [ ] Seleciona backend corretamente.
- [ ] Mantém sessão global.
- [ ] Encaminha SSE.
- [ ] Executa handoff.
- [ ] Preserva Business Context.
- [ ] Suporta múltiplos backends.
- [ ] Permite descoberta dinâmica.
- [ ] Expõe health e readiness.
- [ ] Gera métricas e telemetria.

231
specs/SPEC-004-MCP-Gateway.md Normal file
View File

@@ -0,0 +1,231 @@
# SPEC-004 — MCP Gateway
## Escopo
O MCP Gateway centraliza catálogo, autorização, roteamento, execução, cache, timeout, retry, observabilidade e resposta padronizada de tools MCP.
## Endpoints
| Método | Endpoint | Descrição |
|---|---|---|
| `GET` | `/health` | Health check. |
| `GET` | `/ready` | Readiness check. |
| `GET` | `/v1/tools` | Catálogo de tools. |
| `GET` | `/v1/tools/{tool_name}` | Detalhe da tool. |
| `POST` | `/v1/tools/{tool_name}/invoke` | Execução de tool. |
| `GET` | `/v1/servers` | Lista MCP servers. |
## ToolInvocation
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"tool_name": "consultar_fatura",
"arguments": {
"msisdn": "11999999999",
"invoice_id": "3000131180",
"session_id": "default:telecom_contas:session-001"
},
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
## ToolResult
```json
{
"tool_name": "consultar_fatura",
"ok": true,
"data": {
"invoice_id": "3000131180",
"valor_total": 249.90,
"vencimento": "2026-06-10",
"status": "ABERTA"
},
"cache": {
"hit": false,
"ttl_seconds": 300
},
"latency_ms": 140,
"metadata": {
"server": "telecom"
}
}
```
## mcp_servers.yaml
```yaml
servers:
telecom:
transport: http
url: http://telecom-mcp:8001/mcp
enabled: true
timeout_seconds: 30
retail:
transport: http
url: http://retail-mcp:8002/mcp
enabled: true
timeout_seconds: 30
```
## tools.yaml
```yaml
tools:
consultar_fatura:
server: telecom
enabled: true
idempotent: true
cache_ttl_seconds: 300
allowed_agents:
- telecom_contas
required_business_keys:
- customer_key
- contract_key
solicitar_devolucao:
server: retail
enabled: true
idempotent: false
requires_confirmation: true
allowed_agents:
- retail_orders
```
## mcp_parameter_mapping.yaml
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
## Autorização
```yaml
authorization:
default_policy: deny
agents:
telecom_contas:
allowed_tools:
- consultar_fatura
- consultar_pagamentos
- consultar_plano
```
## Cache
| Regra | Valor |
|---|---|
| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
| Aplicação | Apenas tools idempotentes |
| Bypass | `metadata.cache_bypass=true` |
| TTL | `cache_ttl_seconds` |
| Escrita | Não cachear operações mutáveis |
## Retry e Timeout
```yaml
execution:
default_timeout_seconds: 30
retry:
enabled: true
max_attempts: 2
backoff_ms: 250
circuit_breaker:
enabled: true
failure_threshold: 5
recovery_seconds: 60
```
## Eventos
| Evento | Descrição |
|---|---|
| `mcp.tool.requested` | Tool requisitada. |
| `mcp.tool.authorized` | Autorização aprovada. |
| `mcp.tool.denied` | Autorização negada. |
| `mcp.tool.started` | Execução iniciada. |
| `mcp.tool.completed` | Execução concluída. |
| `mcp.tool.failed` | Execução falhou. |
| `mcp.cache.hit` | Cache hit. |
| `mcp.cache.miss` | Cache miss. |
## Métricas
| Métrica | Dimensões |
|---|---|
| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
| `mcp_tool_latency_ms` | tool, server |
| `mcp_tool_errors_total` | tool, server, error_type |
| `mcp_cache_hits_total` | tool |
| `mcp_cache_misses_total` | tool |
## Segurança
- Tools são negadas por padrão.
- Argumentos sensíveis são mascarados.
- Tools mutáveis exigem confirmação quando configurado.
- MCP servers não recebem payload bruto de canal.
- Credenciais de backend são mantidas nos MCP servers ou secret store.
## 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
- [ ] Catálogo de tools retorna tools habilitadas.
- [ ] ToolInvocation é validado antes da execução.
- [ ] Autorização por agente é aplicada.
- [ ] Parâmetros são derivados do BusinessContext.
- [ ] Cache só é aplicado a tools idempotentes.
- [ ] Timeout/retry/circuit breaker são configuráveis.
- [ ] Eventos e métricas são emitidos.
- [ ] Falhas retornam ToolResult padronizado.
- [ ] MCP servers são substituíveis por configuração.
- [ ] Tools críticas possuem testes de contrato.
## 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. |
## Política mínima de operação
Antes de encaminhar uma tool, o runtime deve aplicar a política opcional do backend em `config/tool_policies.yaml`. Os tipos canônicos são `read_only` e `transactional`; esta última pode exigir confirmação booleana explícita e campos obrigatórios. A ausência do arquivo não é erro e preserva os campos legados de `tools.yaml`. A política conversacional não substitui autenticação, autorização, idempotência nem atomicidade no MCP Server.

194
specs/SPEC-005-Guardrails.md Normal file
View File

@@ -0,0 +1,194 @@
# SPEC-005 — Guardrails
## Escopo
Guardrails são políticas executadas sobre entrada, saída, tool calls, RAG e respostas finais. A plataforma suporta guardrails globais, por agente, por canal e por fase.
## Fases
| Fase | Entrada | Saída |
|---|---|---|
| Input | `user_text`, `context` | `sanitized_input`, `GuardrailResult` |
| Tool | `ToolInvocation` | tool permitida/bloqueada |
| RAG | query/contexto recuperado | contexto aprovado/filtrado |
| Output | `response_text` | resposta aprovada/sanitizada/bloqueada |
| Review | resposta + evidências | decisão final |
## GuardrailResult
```json
{
"code": "PINJ",
"phase": "input",
"status": "blocked",
"severity": "high",
"score": 0.98,
"message": "Entrada bloqueada por política.",
"details": {
"matched_policy": "prompt_injection"
}
}
```
## Configuração Global
```yaml
input:
- code: MSK
enabled: true
mode: enforce
- code: VLOOP
enabled: true
mode: enforce
- code: PINJ
enabled: true
mode: enforce
output:
- code: REVPREC
enabled: true
mode: enforce
- code: DLEX_OUT
enabled: true
mode: enforce
- code: PINJ
enabled: true
mode: observe
```
## Configuração por Agente
```yaml
agents:
telecom_contas:
input:
- code: BILLING_INPUT_POLICY
enabled: true
mode: observe
output:
- code: BILLING_COMPLIANCE
enabled: true
mode: enforce
```
## Modos
| Modo | Comportamento |
|---|---|
| `enforce` | Aplica bloqueio, máscara ou alteração. |
| `observe` | Registra sem bloquear. |
| `fail_open` | Em erro técnico, prossegue e emite NOC. |
| `fail_closed` | Em erro técnico, bloqueia. |
## Tipos
| Tipo | Implementação |
|---|---|
| Determinístico | Regex, listas, tamanho, estrutura, regras. |
| LLM | Classificação semântica por profile. |
| Híbrido | Determinístico + LLM em casos ambíguos. |
## Profiles LLM
```yaml
profiles:
guardrail:
provider: oci_openai
model: openai.gpt-4.1
temperature: 0
max_tokens: 600
grl:
provider: oci_openai
model: openai.gpt-4.1
temperature: 0
max_tokens: 700
```
## Fluxo
```mermaid
flowchart TD
A[Input] --> B[Deterministic Guardrails]
B --> C{Blocked?}
C -- yes --> D[Safe Response]
C -- no --> E[LLM Guardrails]
E --> F{Approved?}
F -- no --> D
F -- yes --> G[Runtime]
```
## Eventos
| Evento | Descrição |
|---|---|
| `guardrail.started` | Execução iniciada. |
| `guardrail.completed` | Execução concluída. |
| `guardrail.blocked` | Conteúdo bloqueado. |
| `guardrail.masked` | Conteúdo mascarado. |
| `guardrail.failed` | Falha técnica. |
| `guardrail.observe` | Política observacional registrada. |
## Códigos Base
| Código | Fase | Uso |
|---|---|---|
| `MSK` | input/output | Mascaramento. |
| `VLOOP` | input | Detecção de loop. |
| `PINJ` | input/output | Prompt injection. |
| `REVPREC` | output | Revisão de precisão. |
| `DLEX_OUT` | output | Controle de dados e linguagem na saída. |
| `RAGSEC` | rag/output | Segurança de contexto recuperado. |
## Testes
| Teste | Objetivo |
|---|---|
| Unitário | Validar guardrail isolado. |
| Config | Validar YAML e schema. |
| Integração | Validar execução no workflow. |
| Observabilidade | Validar eventos e traces. |
| Negativo | Validar bloqueio. |
| Observe-only | Validar não bloqueio. |
## 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
- [ ] Guardrails globais são carregados por YAML.
- [ ] Guardrails por agente sobrescrevem ou complementam globais.
- [ ] GuardrailResult é gerado para cada execução.
- [ ] Modo enforce bloqueia quando aplicável.
- [ ] Modo observe não bloqueia.
- [ ] Falhas técnicas seguem política configurada.
- [ ] Guardrails LLM usam profile dedicado.
- [ ] Eventos e métricas são emitidos.
- [ ] Testes cobrem casos positivos e negativos.
- [ ] Output guardrails executam antes da resposta final.
## 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. |

226
specs/SPEC-006-Evals.md Normal file
View File

@@ -0,0 +1,226 @@
# SPEC-006 — Evals
## Escopo
A camada de Evals executa avaliação online, avaliação offline, regressão, certificação e publicação de métricas. Ela padroniza a validação de agentes, prompts, tools, respostas e guardrails.
## Componentes
| Componente | Responsabilidade |
|---|---|
| Online Judges | Avaliação durante a execução. |
| Offline Evaluator | Avaliação batch de conversas. |
| Dataset Runner | Execução de datasets versionados. |
| Regression Runner | Comparação entre versões. |
| Certification Suite | Validação técnica e funcional. |
| Metrics Engine | Cálculo de métricas. |
| Persistence | Persistência de runs e itens. |
| Exporter | Exportação TXT.GZ/JSON/HTML. |
| Publisher | Publicação de scores no Langfuse. |
## Fluxo Offline
```mermaid
flowchart TD
A[Start EvaluationRun] --> B[Collect Conversations]
B --> C[Normalize Items]
C --> D[Run Judges]
D --> E[Calculate Metrics]
E --> F[Persist Results]
F --> G[Export Reports]
G --> H[Publish Scores]
H --> I[Complete Run]
```
## EvaluationRun
```json
{
"run_id": "eval-20260619-001",
"agent_id": "telecom_contas",
"source": "langfuse",
"period_start": "2026-06-18T00:00:00Z",
"period_end": "2026-06-19T00:00:00Z",
"status": "running",
"limit": 500,
"metadata": {
"profile": "judge",
"dataset": "production-sample"
}
}
```
## EvaluationItem
```json
{
"conversation_id": "default:telecom_contas:session-001",
"trace_id": "trace-001",
"agent_id": "telecom_contas",
"input": "Quero consultar minha fatura",
"output": "Sua fatura está aberta...",
"evidence": {
"mcp_results": [],
"rag_context": ""
},
"scores": {
"quality": 0.86,
"groundedness": 0.78,
"safety": 1.0,
"resolution": 0.91
},
"findings": []
}
```
## Métricas
| Métrica | Descrição | Faixa |
|---|---|---|
| `quality` | Clareza, completude e utilidade. | 0–1 |
| `groundedness` | Aderência a evidências MCP/RAG. | 0–1 |
| `safety` | Conformidade de segurança. | 0–1 |
| `resolution` | Capacidade de resolver a intenção. | 0–1 |
| `tool_correctness` | Uso correto de tools. | 0–1 |
| `policy_compliance` | Aderência a regras de domínio. | 0–1 |
## Dataset
```yaml
dataset:
name: telecom_contas_billing
version: 1.0.0
items:
- id: billing-001
input: "Quero consultar minha fatura"
business_context:
customer_key: "11999999999"
contract_key: "3000131180"
expected:
route: billing_agent
tools:
- consultar_fatura
min_scores:
quality: 0.75
groundedness: 0.70
safety: 1.0
```
## Judges
```yaml
judges:
- name: response_quality
enabled: true
threshold: 0.7
profile: judge
- name: groundedness
enabled: true
threshold: 0.6
profile: judge
- name: safety
enabled: true
threshold: 1.0
profile: judge
```
## CLI
```bash
af-evaluator run \
--agent-id telecom_contas \
--source langfuse \
--period-start 2026-06-18T00:00:00Z \
--period-end 2026-06-19T00:00:00Z \
--limit 500
```
## API
| Método | Endpoint | Descrição |
|---|---|---|
| `POST` | `/evaluation/runs` | Cria run. |
| `GET` | `/evaluation/runs/{run_id}` | Consulta run. |
| `GET` | `/evaluation/runs/{run_id}/items` | Lista itens. |
| `POST` | `/evaluation/datasets/{name}/run` | Executa dataset. |
| `GET` | `/health` | Health check. |
## Persistência
| Tabela | Conteúdo |
|---|---|
| `EVAL_RUNS` | Runs executadas. |
| `EVAL_ITEMS` | Conversas avaliadas. |
| `EVAL_SCORES` | Scores por métrica. |
| `EVAL_FINDINGS` | Achados. |
| `EVAL_EXPORTS` | Arquivos exportados. |
## Certificação
A Certification Suite valida:
- endpoints de health;
- GatewayRequest;
- roteamento;
- MCP tools;
- guardrails;
- judges;
- memória;
- checkpoint;
- Langfuse/OTEL;
- datasets mínimos;
- evidências JSON/HTML.
## Eventos
| Evento | Descrição |
|---|---|
| `eval.run.started` | Run iniciada. |
| `eval.item.completed` | Item avaliado. |
| `eval.run.completed` | Run concluída. |
| `eval.run.failed` | Run falhou. |
| `eval.score.published` | Score publicado. |
## 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
- [ ] Evaluator executa runs por período/agente.
- [ ] Langfuse é fonte suportada.
- [ ] Datasets são versionados.
- [ ] LLM Judges usam profile `judge`.
- [ ] Scores são persistidos.
- [ ] TXT.GZ/JSON/HTML são exportáveis.
- [ ] Scores podem ser publicados no Langfuse.
- [ ] Certification Suite gera evidências.
- [ ] Métricas mínimas são padronizadas.
- [ ] Falhas permitem retomada por checkpoint de run.
## 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. |

202
specs/SPEC-007-Observability.md Normal file
View File

@@ -0,0 +1,202 @@
# SPEC-007 — Observability
## Escopo
Observabilidade cobre logs, métricas, traces, eventos IC/NOC/GRL, Langfuse, OpenTelemetry, dashboards, alertas e evidências operacionais.
## Correlação
Campos obrigatórios:
```text
request_id
trace_id
session_id
conversation_key
tenant_id
agent_id
channel
message_id
route
intent
```
## Logs
Formato:
```json
{
"timestamp": "2026-06-19T12:00:00Z",
"level": "INFO",
"service": "agent-runtime",
"event": "runtime.route.selected",
"tenant_id": "default",
"agent_id": "telecom_contas",
"session_id": "default:telecom_contas:session-001",
"trace_id": "trace-001",
"route": "billing_agent",
"intent": "billing_invoice_explanation"
}
```
## Traces
```mermaid
flowchart TD
T[conversation trace] --> A[gateway.received]
T --> B[channel.normalized]
T --> C[runtime.started]
T --> D[guardrails.input]
T --> E[routing]
T --> F[agent.execution]
F --> G[mcp.tool]
F --> H[llm.generation]
T --> I[guardrails.output]
T --> J[judges]
T --> K[persist]
```
## Métricas
| Métrica | Dimensões |
|---|---|
| `requests_total` | service, tenant, agent, channel, status |
| `request_latency_ms` | service, route, intent |
| `active_sessions` | tenant, agent |
| `llm_tokens_total` | provider, model, profile |
| `llm_cost_estimated` | provider, model, tenant, agent |
| `mcp_tool_calls_total` | tool, server, status |
| `mcp_tool_latency_ms` | tool, server |
| `guardrail_blocks_total` | code, phase, agent |
| `judge_scores` | metric, agent, route |
| `errors_total` | service, component, error_type |
## Langfuse
Dados registrados:
- trace de conversa;
- spans técnicos;
- generations LLM;
- prompts e respostas quando permitido;
- tokens;
- custos;
- latência;
- scores;
- metadados;
- erros.
## OpenTelemetry
Configuração:
```yaml
otel:
enabled: true
service_name: agent-runtime
exporter: otlp
endpoint: http://otel-collector:4317
```
## IC/NOC/GRL
| Família | Eventos |
|---|---|
| IC | `IC.GATEWAY_RECEIVED`, `IC.AGENT_STARTED`, `IC.AGENT_COMPLETED` |
| NOC | `NOC.RUNTIME_FAILED`, `NOC.MCP_TIMEOUT`, `NOC.LLM_FAILED` |
| GRL | `GRL.INPUT_BLOCKED`, `GRL.OUTPUT_BLOCKED`, `GRL.MASK_APPLIED` |
## Dashboards
| Dashboard | Conteúdo |
|---|---|
| Platform Overview | tráfego, erros, latência, sessões. |
| Agent Runtime | rotas, intents, memória, checkpoints. |
| LLM Usage | tokens, custo, latência, provider/model. |
| MCP Operations | chamadas, erros, cache, latência. |
| Guardrails | bloqueios, observe-only, códigos. |
| Evals | scores, trends, regressões. |
| Channels | tráfego por canal, erros, retries. |
## Alertas
| Alerta | Condição |
|---|---|
| `GatewayHighErrorRate` | Erros 5xx acima do limite. |
| `RuntimeLatencyHigh` | p95 acima do SLO. |
| `LLMProviderUnavailable` | falhas consecutivas de provider. |
| `MCPToolTimeoutSpike` | aumento de timeouts. |
| `GuardrailBlockSpike` | aumento anômalo de bloqueios. |
| `EvaluatorRunFailed` | run batch falhou. |
| `CheckpointFailure` | falha persistente em checkpoint. |
## Mascaramento
Campos mascarados:
- tokens;
- API keys;
- senhas;
- secrets;
- CPF/CNPJ, quando aplicável;
- telefone, quando configurado;
- payload bruto de canal;
- documentos sensíveis.
## Evidências
Relatórios de homologação incluem:
- health checks;
- logs de execução;
- traces Langfuse;
- métricas;
- resultados de guardrails;
- resultados de judges;
- chamadas MCP;
- chamadas LLM;
- relatório do evaluator;
- relatório da certification suite.
## 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
- [ ] Todos os serviços emitem logs estruturados.
- [ ] Trace correlaciona gateway, runtime, MCP, LLM, guardrails e judges.
- [ ] Langfuse recebe traces quando habilitado.
- [ ] OTEL exporta spans quando habilitado.
- [ ] Métricas mínimas estão disponíveis.
- [ ] Dashboards estão definidos.
- [ ] Alertas estão definidos.
- [ ] Segredos e PII são mascarados.
- [ ] Evaluator consome dados observáveis.
- [ ] Certification Suite gera evidências.
## 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. |

233
specs/SPEC-008-Deployment.md Normal file
View File

@@ -0,0 +1,233 @@
# SPEC-008 — Deployment
## Escopo
Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, autenticação OCI, health checks, rollback e operação dos componentes.
## Componentes Deployáveis
| Componente | Artefato |
|---|---|
| Agent Gateway | Docker image + Kubernetes Deployment |
| Channel Gateway | Docker image + Kubernetes Deployment |
| AI Gateway | Docker image + Kubernetes Deployment |
| MCP Gateway | Docker image + Kubernetes Deployment |
| Agent Backend | Docker image + Kubernetes Deployment |
| MCP Server | Docker image + Kubernetes Deployment |
| Evaluator API | Docker image + Kubernetes Deployment |
| Evaluator Batch | Kubernetes CronJob |
| Frontend Demo | Docker image opcional |
## Pipeline
```mermaid
flowchart LR
A[Commit] --> B[Lint]
B --> C[Type Check]
C --> D[Unit Tests]
D --> E[Contract Tests]
E --> F[Security Scan]
F --> G[Build Wheel]
G --> H[Build Images]
H --> I[Publish]
I --> J[Deploy Dev]
J --> K[Smoke Tests]
K --> L[Certification]
L --> M[Deploy HML/Prod]
```
## Stages
```yaml
stages:
- validate
- lint
- type_check
- unit_test
- contract_test
- security_scan
- build_package
- build_image
- publish
- deploy_dev
- smoke_test
- certification
- deploy_hml
- deploy_prod
```
## Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: agent-runtime
labels:
app: agent-runtime
component: runtime
spec:
replicas: 2
selector:
matchLabels:
app: agent-runtime
template:
metadata:
labels:
app: agent-runtime
spec:
serviceAccountName: agent-runtime-sa
containers:
- name: agent-runtime
image: registry/agent-runtime:1.0.0
ports:
- containerPort: 8000
envFrom:
- configMapRef:
name: agent-runtime-config
- secretRef:
name: agent-runtime-secrets
readinessProbe:
httpGet:
path: /ready
port: 8000
livenessProbe:
httpGet:
path: /health
port: 8000
```
## Service
```yaml
apiVersion: v1
kind: Service
metadata:
name: agent-runtime
spec:
selector:
app: agent-runtime
ports:
- port: 8000
targetPort: 8000
```
## OCI Authentication
| Ambiente | Modo |
|---|---|
| Local | `config_file` |
| Local com endpoint OpenAI-Compatible | API key |
| OCI Compute | `instance_principal` |
| OKE | `workload_identity` ou `resource_principal` |
| Testes | `mock` |
## Variáveis
```env
LLM_PROVIDER=oci_sdk
OCI_AUTH_MODE=workload_identity
ENABLE_LANGFUSE=true
ENABLE_OTEL=true
SESSION_REPOSITORY_PROVIDER=autonomous
MEMORY_REPOSITORY_PROVIDER=autonomous
CHECKPOINT_REPOSITORY_PROVIDER=autonomous
```
## Secrets
| Secret | Uso |
|---|---|
| `LANGFUSE_PUBLIC_KEY` | Langfuse |
| `LANGFUSE_SECRET_KEY` | Langfuse |
| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
| `ADB_PASSWORD` | Autonomous Database |
| `MCP_BACKEND_TOKEN` | Integrações MCP |
| `OTEL_AUTH_TOKEN` | Exportador OTEL, se aplicável |
## Health Checks
| Endpoint | Uso |
|---|---|
| `/health` | Processo vivo. |
| `/ready` | Pronto para tráfego. |
| `/version` | Versão de build. |
| `/debug/env` | Ambiente sem segredos, quando habilitado. |
## Rollback
Itens considerados:
- tag da imagem;
- versão do pacote Python;
- versão dos schemas;
- versão dos YAMLs;
- migrations;
- datasets de eval;
- contracts;
- dashboards.
## Smoke Tests
```bash
curl -f http://agent-runtime:8000/health
curl -f http://agent-gateway:9000/health
curl -f http://mcp-gateway:8300/health
curl -f http://ai-gateway:9100/health
```
## Certification Stage
A pipeline executa:
- health checks;
- contrato GatewayRequest;
- roteamento;
- MCP invoke;
- LLM mock/real conforme ambiente;
- guardrails;
- judges;
- memória/checkpoint;
- relatório JSON/HTML.
## 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
- [ ] Cada app possui Dockerfile.
- [ ] Cada app possui manifest Kubernetes.
- [ ] CI executa lint, type check e testes.
- [ ] Contract tests validam contratos principais.
- [ ] Security scan executa antes do publish.
- [ ] Secrets não são versionados.
- [ ] Workload Identity está configurado em OKE.
- [ ] Health/readiness/liveness estão ativos.
- [ ] Smoke tests rodam após deploy.
- [ ] Rollback está documentado.
## 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. |

197
specs/SPEC-009-Channel-Gateway.md Normal file
View File

@@ -0,0 +1,197 @@
# SPEC-009 — Channel Gateway
## Escopo
O Channel Gateway normaliza payloads de canais externos para GatewayRequest e traduz ChannelResponse para o formato de resposta do canal.
## Modos de Operação
| Modo | Descrição |
|---|---|
| Embedded | Normalização no próprio backend para demos e cenários simples. |
| External | Serviço dedicado para canais corporativos. |
## GatewayRequest
```json
{
"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
```json
{
"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"
}
}
```
## Fluxo Externo
```mermaid
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
```
## Responsabilidades
| Responsabilidade | Detalhe |
|---|---|
| Auth | Validar assinatura, token ou origem. |
| Parse | Interpretar payload bruto. |
| Dedup | Evitar reprocessamento por message_id. |
| Normalize | Criar GatewayRequest. |
| Business Context | Mapear chaves canônicas. |
| Forward | Chamar Agent Gateway. |
| Translate | Converter ChannelResponse para canal. |
| Observe | Emitir logs, métricas e traces. |
## Idempotência
Chave:
```text
tenant_id:channel:user_id:message_id
```
Comportamentos:
| Situação | Ação |
|---|---|
| Primeira mensagem | Processar. |
| Duplicada em andamento | Retornar 202 ou resposta controlada. |
| Duplicada concluída | Retornar resposta anterior. |
## Versionamento
Header:
```http
X-Agent-Framework-Contract: gateway-request-v1
```
Campo alternativo:
```json
{
"payload": {
"metadata": {
"contract_version": "gateway-request-v1"
}
}
}
```
## Segurança
Validações:
- assinatura do webhook;
- origem permitida;
- tamanho máximo;
- tipo de evento permitido;
- anexos permitidos;
- sanitização de texto;
- remoção de tokens;
- máscara de dados sensíveis;
- rate limit;
- deduplicação.
## Erros
| Código HTTP | Uso |
|---|---|
| 400 | Payload inválido do canal. |
| 401 | Autenticação ausente. |
| 403 | Origem não autorizada. |
| 422 | GatewayRequest inválido. |
| 429 | Rate limit. |
| 500 | Erro interno. |
| 503 | Runtime indisponível. |
## Anti-patterns
- Agente lendo payload bruto.
- Workflow tratando `channel == whatsapp`.
- MCP recebendo payload bruto.
- Tokens do canal em metadata.
- Gateway externo executando regra de agente.
- Frontend enviando campos fora do contrato.
## 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
- [ ] Payload bruto é convertido para GatewayRequest.
- [ ] GatewayRequest é validado.
- [ ] message_id é usado para idempotência.
- [ ] business_context contém chaves canônicas.
- [ ] Resposta do runtime é traduzida para o canal.
- [ ] Payload bruto não chega ao Agent Runtime.
- [ ] Auth/rate limit/dedup estão implementados.
- [ ] Erros são padronizados.
- [ ] Contrato possui versão.
- [ ] Logs/traces usam request_id e trace_id.
## 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. |

333
specs/SPEC-010-Agent-Development.md Normal file
View File

@@ -0,0 +1,333 @@
# SPEC-010 — Agent Development
## Escopo
Esta SPEC define o padrão para criação de agentes usando templates, configuração YAML, BusinessContext, MCP, guardrails, judges, RAG, memória, observabilidade e evals.
## Estrutura do Template
```text
templates/agent_template_backend/
├── app/
│ ├── main.py
│ ├── state.py
│ ├── workflows/
│ │ └── agent_graph.py
│ ├── agents/
│ │ ├── runtime.py
│ │ └── domain_agent.py
│ └── examples/
├── config/
│ ├── agents.yaml
│ ├── routing.yaml
│ ├── tools.yaml
│ ├── mcp_servers.yaml
│ ├── mcp_parameter_mapping.yaml
│ ├── identity.yaml
│ ├── guardrails.yaml
│ ├── judges.yaml
│ ├── prompt_policy.yaml
│ └── agents/<agent_id>/
├── Dockerfile
├── requirements.txt
└── .env.example
```
## Responsabilidades do Framework
- LangGraph;
- memória;
- checkpoint;
- sessão;
- router;
- supervisor;
- guardrails;
- judges;
- telemetry;
- MCP integration;
- RAG genérico;
- cache;
- providers LLM;
- event bus.
## Responsabilidades do Agente
- prompts de domínio;
- regras de negócio;
- schemas específicos;
- decisão de uso de evidências;
- tratamento de campos obrigatórios;
- mensagens de domínio;
- ICs de jornada;
- datasets de eval específicos.
## Registro do Agente
```yaml
agents:
financeiro_agent:
enabled: true
description: "Agente financeiro"
profile: financeiro_agent
rag_namespace: financeiro
allowed_tools:
- consultar_fatura
- consultar_pagamentos
```
## Roteamento
```yaml
intents:
financeiro_consulta_fatura:
route: financeiro_agent
keywords:
- fatura
- boleto
- cobrança
mcp_tools:
- consultar_fatura
```
## Tool Mapping
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
## Classe de Agente
```python
class FinanceiroAgent(AgentRuntimeMixin):
name = "financeiro_agent"
def __init__(
self,
llm,
telemetry=None,
tool_router=None,
rag_service=None,
cache=None,
settings=None,
observer=None,
memory=None,
summary_memory=None,
):
self.llm = llm
self.telemetry = telemetry
self.tool_router = tool_router
self.rag_service = rag_service
self.cache = cache
self.settings = settings
self.observer = observer
self.memory = memory
self.summary_memory = summary_memory
async def run(self, state):
await self._emit_ic("IC.FINANCEIRO_AGENT_STARTED", state, {})
tool_context = await self._collect_mcp_context(state)
rag_context, rag_metadata = await self._retrieve_rag_context(state)
response = await self._invoke_llm_cached(
state,
"FinanceiroAgent",
[
{"role": "system", "content": "Você é um agente financeiro."},
{"role": "user", "content": state.get("sanitized_input") or state.get("user_text", "")},
],
)
await self._emit_ic("IC.FINANCEIRO_AGENT_COMPLETED", state, {})
return {
"response_text": response,
"mcp_results": tool_context,
"rag_metadata": rag_metadata,
}
```
## Ordem de Confiança dos Dados
1. `tool_arguments`
2. `business_context`
3. `context`
4. `session.metadata`
5. `state`
6. extração complementar do texto
## Prompt Policy
```yaml
prompt_policy:
system_prompt_path: prompts/system.md
response_style: concise
require_evidence: true
allow_tool_usage: true
```
## Guardrails por Agente
```yaml
input:
- code: FIN_INPUT_POLICY
enabled: true
mode: observe
output:
- code: FIN_OUTPUT_COMPLIANCE
enabled: true
mode: enforce
```
## Judges por Agente
```yaml
judges:
- name: response_quality
enabled: true
threshold: 0.75
- name: groundedness
enabled: true
threshold: 0.70
```
## Dataset de Eval
```yaml
dataset:
name: financeiro_agent_regression
version: 1.0.0
items:
- id: fin-001
input: "Quero consultar minha fatura"
business_context:
customer_key: "11999999999"
contract_key: "3000131180"
expected:
route: financeiro_agent
tools:
- consultar_fatura
min_scores:
quality: 0.75
groundedness: 0.70
```
## Contrato obrigatório para agentes transacionais
Ao criar um agente que usa tools transacionais do framework, o desenvolvedor não deve criar um motor paralelo de coleta/confirmação. Deve reutilizar `AgentRuntime` e garantir que o `AgentState` do host mantenha o latch durável:
```python
active_transaction: dict[str, Any]
last_transaction: dict[str, Any]
```
Durante uma transação ativa, parâmetros já coletados são preservados e novos valores são mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, uma resposta que satisfaz um parâmetro pendente tem precedência sobre keywords genéricas. Mudanças de intenção explícitas e inequívocas continuam permitidas.
Antes de publicar um novo template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
## Contrato MCP Multi-item
Para uma intenção que opere sobre múltiplos itens homogêneos, o agente **não deve implementar fan-out/loop de chamadas MCP por conta própria**. Deve reutilizar o runtime e declarar o contrato natural da tool. A entrada pode ser escalar ou coleção; `type: array/list` não é requisito para suporte multi-item.
Regras:
1. canonicalização de itens pertence ao MCP/pre-validation e pode usar `transaction_decision.resolved_arguments`;
2. confirmação transacional deve representar o conjunto efetivo de itens;
3. a tool primária deve retornar `results[]` com dois ou mais itens contendo `success` ou `ok` booleano por item;
4. para workflow-backed tools, a fonte preferencial é `workflow.output[tool_name].results`;
5. o runtime normaliza o agregado para `SUCCESS`, `PARTIAL_SUCCESS` ou `FAILED`;
6. falha em etapa auxiliar posterior não pode apagar evidência terminal de itens concluídos;
7. um `eligible=false` global em pre-validation encerra toda a transação; para processamento parcial, mantenha `eligible=true` quando houver ao menos um item acionável e deixe a tool primária materializar o resultado por item.
Referência de implementação: [`MCP Multi-item — Guia do Desenvolvedor`](../docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md).
## Testes
| Teste | Escopo |
|---|---|
| Unitário | Classe do agente. |
| Routing | Intent e rota. |
| MCP Mapping | BusinessContext para argumentos. |
| Guardrails | Entrada e saída. |
| Judges | Scores mínimos. |
| Runtime | Execução completa. |
| Memory | Continuidade de conversa. |
| Checkpoint | Resume/replay. |
| Observability | Trace e eventos. |
| Certification | Evidências finais. |
## Definition of Done
- agente registrado;
- rota configurada;
- tools declaradas;
- mapping definido;
- prompts versionados;
- guardrails configurados;
- judges configurados;
- dataset criado;
- testes executados;
- traces gerados;
- certification suite aprovada;
- documentação do agente atualizada.
## Anti-patterns
- agente criando sessão;
- agente abrindo SSE;
- agente compilando LangGraph;
- agente chamando sistema externo diretamente;
- prompt hardcoded sem política;
- lógica genérica duplicada no agente;
- payload bruto de canal dentro do agente;
- ausência de dataset de eval.
## 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
- [ ] Novo agente é criado sem alterar core do framework.
- [ ] Se houver transações multi-turno, `AgentState` declara `active_transaction` e `last_transaction`.
- [ ] Configuração ocorre por YAML e `.env`.
- [ ] Agente usa BusinessContext.
- [ ] Agente acessa MCP por router/gateway.
- [ ] Casos multi-item usam o contrato natural da operação (escalar ou coleção) + resultado por item, sem loop MCP de negócio dentro do agente.
- [ ] Agente não conhece payload bruto de canal.
- [ ] Guardrails e judges são configurados.
- [ ] Dataset de eval existe.
- [ ] Testes mínimos executam.
- [ ] Trace completo é gerado.
- [ ] Definition of Done é atendida.
## 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. |

347
specs/SPEC-011-Governance-Model.md Normal file
View File

@@ -0,0 +1,347 @@
# SPEC-011 — Governance Model
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Governança é o conjunto de papéis, responsabilidades, controles, aprovações, evidências e processos que permite que a Agent Platform OCI seja usada por múltiplos times sem perder padronização, segurança, rastreabilidade e capacidade de evolução.
A governança não substitui a engenharia. Ela define como a engenharia evolui de forma controlada.
Em uma plataforma de agentes, governança cobre:
- quem pode criar agentes;
- quem pode alterar prompts;
- quem pode liberar MCP tools;
- quem aprova mudanças de guardrails;
- quem aprova modelos;
- quem aprova datasets;
- quem promove para produção;
- quais evidências são obrigatórias;
- como auditar decisões da plataforma.
# 2. Problema que resolve
Sem governança, cada time tende a criar agentes de forma diferente.
Problemas comuns:
- prompts sem versionamento;
- MCP tools sem owner;
- datasets ausentes;
- agentes sem avaliação;
- produção sem certification;
- mudanças de modelo sem rastreabilidade;
- guardrails duplicados;
- regras de negócio dentro do runtime;
- uso diferente da plataforma por cada fornecedor;
- dificuldade de manutenção.
A governança cria um modelo único de adoção.
# 3. Domínios de governança
| Domínio | Escopo |
| --- | --- |
| Platform Governance | Framework, Runtime, Gateways, Evaluator, Certification Suite. |
| Agent Governance | Agentes, prompts, regras de negócio, datasets e configs. |
| Model Governance | LLM profiles, providers, fallback, custo e uso. |
| MCP Governance | Tools, MCP servers, owners, SLAs, autorização e contratos. |
| Data Governance | BusinessContext, RAG, datasets, memória e retenção. |
| Security Governance | Identidade, autorização, secrets, auditoria e PII. |
| Operational Governance | Deploy, monitoramento, alertas, SLOs e incidentes. |
| Evaluation Governance | Judges, evaluator, certification e métricas. |
# 4. Modelo de ownership
## 4.1. Platform Team
Responsável por:
- Agent Framework;
- Agent Runtime;
- Agent Gateway;
- Channel Gateway;
- AI Gateway;
- MCP Gateway;
- Evaluator;
- Certification Suite;
- contratos canônicos;
- documentação da plataforma;
- templates oficiais.
## 4.2. Domain Team
Responsável por:
- comportamento do agente;
- prompts;
- regras de negócio;
- datasets;
- configurações específicas;
- validação funcional;
- critérios de sucesso.
## 4.3. Integration Team
Responsável por:
- MCP servers;
- APIs externas;
- SLAs de tools;
- contratos de integração;
- credenciais de backend;
- disponibilidade de sistemas externos.
## 4.4. SRE / DevOps
Responsável por:
- CI/CD;
- deploy;
- observabilidade;
- alertas;
- capacidade;
- SLOs;
- runbooks;
- rollback.
## 4.5. Security / Architecture
Responsável por:
- segurança;
- arquitetura;
- policies;
- Workload Identity;
- secrets;
- revisão de risco;
- aprovação de exceções.
# 5. RACI
| Atividade | Platform | Domain | Integration | SRE | Security |
| --- | --- | --- | --- | --- | --- |
| Framework change | R/A | C | I | C | C |
| Runtime change | R/A | C | I | C | C |
| New agent | C | R/A | C | I | I |
| New MCP tool | C | C | R/A | I | C |
| Prompt change | I | R/A | I | I | C |
| Guardrail change | R | C | I | I | A |
| Model profile change | R | C | I | I | C |
| Production deploy | I | C | C | R/A | C |
| Security review | I | C | C | C | R/A |
| Certification | R/A | C | C | I | I |
# 6. Governança de agentes
Todo agente deve possuir:
```yaml
agent:
id: telecom_contas
owner: billing_team
technical_owner: ai_platform_team
business_objective: "Atendimento sobre faturas, pagamentos e cobranças"
status: active
version: 1.0.0
```
Artefatos obrigatórios:
- `agents.yaml`;
- `routing.yaml`;
- `prompt_policy.yaml`;
- `guardrails.yaml`;
- `judges.yaml`;
- `tools.yaml`;
- `mcp_parameter_mapping.yaml`;
- dataset de regressão;
- testes;
- evidências de evaluator;
- evidências de certification.
# 7. Governança de prompts
Prompts devem ser versionados e rastreáveis.
```yaml
prompt:
name: billing_system_prompt
version: 1.3.0
owner: billing_team
reviewed_at: 2026-06-19
status: approved
```
Mudanças de prompt exigem:
1. revisão do domain owner;
2. execução de dataset;
3. evaluator;
4. comparação contra baseline;
5. registro da versão.
# 8. Governança de guardrails
Guardrails globais pertencem à plataforma/segurança.
Guardrails por agente pertencem ao domínio, mas precisam seguir o contrato da plataforma.
```yaml
guardrail:
code: REVPREC
version: 2.0.0
owner: platform_security
phase: output
mode: enforce
```
Mudanças em guardrails `enforce` exigem certification.
# 9. Governança de judges
Judges devem ter objetivo, métrica, threshold e owner.
```yaml
judge:
name: groundedness
version: 1.1.0
threshold: 0.70
owner: platform_quality
```
Mudanças de threshold exigem reexecução do evaluator.
# 10. Governança de modelos
Agentes não referenciam modelo diretamente.
O modelo é resolvido por profile.
```yaml
profiles:
judge:
provider: oci_openai
model: openai.gpt-4.1
temperature: 0
```
Mudanças de modelo exigem:
- validação de custo;
- evaluator;
- validação de qualidade;
- validação de latência;
- atualização de release notes.
# 11. Governança de MCP
Cada tool deve ter owner, SLA, timeout e contrato.
```yaml
tool:
name: consultar_fatura
version: 1.0.0
owner: billing_platform
sla: p95_2s
timeout_seconds: 30
idempotent: true
```
Tools mutáveis exigem política de confirmação.
# 12. Governança de datasets
Datasets são ativos de qualidade.
```yaml
dataset:
name: telecom_contas_regression
version: 1.0.0
owner: billing_team
```
Datasets devem conter:
- entrada;
- BusinessContext;
- rota esperada;
- tools esperadas;
- critérios mínimos;
- casos negativos;
- casos de segurança.
# 13. Processo de aprovação
```mermaid
flowchart LR
Dev[Development] --> Tests[Tests]
Tests --> Eval[Evaluator]
Eval --> Cert[Certification]
Cert --> Sec[Security Review]
Sec --> Arch[Architecture Approval]
Arch --> HML[Homologation]
HML --> PROD[Production]
```
# 14. Evidências obrigatórias
- relatório de testes;
- relatório evaluator;
- relatório certification;
- trace Langfuse;
- logs e métricas;
- checklist de segurança;
- release notes;
- versão dos artefatos.
# 15. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Prompt sem owner | Dificulta manutenção e aprovação. | Definir owner no metadata. |
| Tool sem SLA | Operação sem expectativa de resposta. | Registrar SLA em tools.yaml. |
| Dataset ausente | Sem regressão objetiva. | Criar dataset mínimo. |
| Guardrail hardcoded | Governança fora do YAML. | Mover para config. |
| Modelo definido no agente | Quebra governança de modelos. | Usar AI Gateway profiles. |
# 16. Critérios de aceite
- [ ] Cada agente possui owner funcional e técnico.
- [ ] Prompts estão versionados.
- [ ] Tools MCP possuem owner, SLA e versão.
- [ ] Guardrails possuem owner e modo.
- [ ] Judges possuem threshold e versão.
- [ ] Datasets estão versionados.
- [ ] Evaluator roda por agente.
- [ ] Certification aprova antes de produção.
- [ ] Release possui evidências.
- [ ] Exceções são documentadas.

312
specs/SPEC-012-Canonical-Contracts.md Normal file
View File

@@ -0,0 +1,312 @@
# SPEC-012 — Canonical Contracts
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Contratos canônicos são estruturas padronizadas usadas para desacoplar canais, gateways, runtime, agentes, tools, LLMs, evaluator e observabilidade.
A plataforma usa contratos para garantir que componentes independentes possam evoluir sem quebrar uns aos outros.
# 2. Problema que resolve
Sem contratos:
- cada canal envia payload diferente;
- agentes passam a conhecer WhatsApp, Voice, Teams ou CRM;
- MCP tools recebem parâmetros inconsistentes;
- LLM calls ficam acopladas ao provider;
- evaluator não consegue comparar respostas;
- observabilidade fica fragmentada.
Com contratos:
```text
Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
```
# 3. Catálogo de contratos
| Contrato | Uso |
| --- | --- |
| GatewayRequest | Entrada canônica da plataforma. |
| ChannelResponse | Resposta canônica ao canal. |
| BusinessContext | Identidade canônica de negócio. |
| AgentState | Estado interno do runtime. |
| Session | Sessão técnica/conversacional. |
| Checkpoint | Persistência de estado LangGraph. |
| ToolInvocation | Chamada canônica de tool MCP. |
| ToolResult | Resposta canônica de tool MCP. |
| LLMRequest | Chamada canônica ao AI Gateway. |
| LLMResponse | Resposta canônica do AI Gateway. |
| EvaluationRun | Execução do evaluator. |
| EvaluationResult | Resultado de avaliação. |
| CertificationResult | Resultado de certificação. |
| EventEnvelope | Envelope de eventos IC/NOC/GRL. |
# 4. GatewayRequest
## 4.1. Uso
Usado por Channel Gateway e Agent Gateway para enviar mensagens ao Runtime.
```json
{
"channel": "web",
"tenant_id": "default",
"agent_id": "telecom_contas",
"payload": {
"message": "Quero consultar minha fatura",
"session_id": "session-001",
"user_id": "user-001",
"message_id": "msg-001",
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"interaction_key": "301953872",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001",
"contract_version": "gateway-request-v1"
}
}
}
```
## 4.2. Campos obrigatórios
- `channel`;
- `payload.message`;
- `payload.session_id`;
- `payload.message_id`;
- `tenant_id` quando multi-tenant;
- `agent_id` quando não houver roteamento global.
# 5. ChannelResponse
```json
{
"channel": "web",
"session_id": "default:telecom_contas:session-001",
"text": "Resposta final do agente.",
"metadata": {
"tenant_id": "default",
"agent_id": "telecom_contas",
"route": "billing_agent",
"intent": "billing_invoice_explanation",
"guardrails": [],
"judges": []
}
}
```
# 6. BusinessContext
## 6.1. Uso
BusinessContext transporta identidade de negócio sem acoplar a plataforma ao formato de cada canal.
```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
```
## 6.2. Mapeamento para MCP
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
# 7. AgentState
```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
business_context: dict
mcp_tools: list[str]
mcp_results: list[dict]
rag_context: str
guardrails: list[dict]
judges: list[dict]
```
# 8. ToolInvocation
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"tool_name": "consultar_fatura",
"arguments": {
"msisdn": "11999999999",
"invoice_id": "3000131180"
},
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180"
},
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
# 9. ToolResult
```json
{
"tool_name": "consultar_fatura",
"ok": true,
"data": {
"invoice_id": "3000131180",
"valor_total": 249.90,
"status": "ABERTA"
},
"cache": {
"hit": false,
"ttl_seconds": 300
},
"latency_ms": 140
}
```
# 10. LLMRequest
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"profile": "judge",
"operation": "judge.response_quality",
"messages": [
{"role": "system", "content": "Você é um avaliador."},
{"role": "user", "content": "Avalie a resposta."}
],
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
# 11. LLMResponse
```json
{
"provider": "oci_openai",
"model": "openai.gpt-4.1",
"profile": "judge",
"content": "Resultado",
"usage": {
"input_tokens": 1200,
"output_tokens": 300,
"total_tokens": 1500
},
"latency_ms": 820
}
```
# 12. EvaluationRun
```json
{
"run_id": "eval-001",
"agent_id": "telecom_contas",
"source": "langfuse",
"period_start": "2026-06-18T00:00:00Z",
"period_end": "2026-06-19T00:00:00Z",
"status": "running"
}
```
# 13. EventEnvelope
```json
{
"event_type": "IC.AGENT_COMPLETED",
"timestamp": "2026-06-19T12:00:00Z",
"tenant_id": "default",
"agent_id": "telecom_contas",
"session_id": "session-001",
"trace_id": "trace-001",
"payload": {}
}
```
# 14. Regras de evolução
- campos novos devem ser opcionais;
- campos obrigatórios não podem ser removidos dentro da mesma major;
- mudança semântica exige nova versão;
- contratos são versionados independentemente.
# 15. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Payload bruto no Runtime | Acopla canais ao core. | Usar GatewayRequest. |
| Tool recebendo BusinessContext bruto sem mapping | Quebra contrato da tool. | Usar mcp_parameter_mapping.yaml. |
| LLM direto no agente | Quebra AI Gateway. | Usar LLMRequest/profile. |
| Campos sem versão | Dificulta migração. | Declarar contract_version. |
# 16. Critérios de aceite
- [ ] GatewayRequest documentado e versionado.
- [ ] ChannelResponse documentado e versionado.
- [ ] BusinessContext usado por canais e MCP.
- [ ] ToolInvocation e ToolResult padronizados.
- [ ] LLMRequest e LLMResponse padronizados.
- [ ] EvaluationRun e EvaluationResult padronizados.
- [ ] EventEnvelope usado para IC/NOC/GRL.
- [ ] Contratos possuem regras de evolução.

175
specs/SPEC-013-Versioning-and-Compatibility-Model.md Normal file
View File

@@ -0,0 +1,175 @@
# SPEC-013 — Versioning and Compatibility Model
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Versionamento define como a plataforma evolui sem quebrar projetos existentes. Compatibilidade define quais versões de framework, runtime, gateways, contracts, templates, prompts, tools e evaluator podem operar juntas.
# 2. Problema que resolve
Sem modelo de versionamento:
- uma mudança em GatewayRequest quebra canais;
- uma mudança em MCP tool quebra agentes;
- um prompt alterado muda comportamento sem rastreabilidade;
- evaluator muda score sem histórico;
- templates ficam incompatíveis com runtime;
- produção usa imagem `latest` sem controle.
# 3. Semantic Versioning
Formato:
```text
MAJOR.MINOR.PATCH
```
Regras:
| Parte | Significado |
| --- | --- |
| MAJOR | Mudança incompatível. |
| MINOR | Nova capacidade compatível. |
| PATCH | Correção sem mudança de contrato. |
# 4. Artefatos versionados
| Artefato | Modelo |
| --- | --- |
| agent_framework | SemVer |
| agent_runtime | SemVer alinhado ao framework |
| agent_gateway | SemVer + Docker tag |
| channel_gateway | SemVer + Docker tag |
| ai_gateway | SemVer + Docker tag |
| mcp_gateway | SemVer + Docker tag |
| templates | versão da plataforma |
| contracts | contract-name-vN |
| prompts | SemVer |
| datasets | SemVer |
| guardrails | SemVer por código |
| judges | SemVer por judge |
| mcp_tools | SemVer por tool |
| evaluator | SemVer |
| certification_suite | SemVer + ruleset version |
# 5. Contract versioning
Exemplos:
```text
gateway-request-v1
business-context-v1
tool-invocation-v1
llm-request-v1
```
Permitido na mesma versão major:
- adicionar campos opcionais;
- adicionar metadata;
- adicionar enum documentado.
Não permitido:
- remover campo obrigatório;
- mudar tipo;
- mudar significado;
- alterar regra obrigatória.
# 6. Compatibility Matrix
```yaml
compatibility:
- framework: "1.4.x"
runtime: "1.4.x"
agent_gateway: "1.4.x"
supported: true
- framework: "1.4.x"
runtime: "2.0.x"
supported: false
```
# 7. Política de depreciação
Ciclo:
```text
Active → Deprecated → Retired
```
Período recomendado:
```text
12 meses
```
# 8. Política de migração
Mudanças major exigem:
- migration guide;
- compatibility matrix;
- rollback strategy;
- certification;
- evaluator;
- release notes.
# 9. Estratégia de rollback
Rollback deve considerar:
- imagem Docker;
- versão do pacote;
- versão dos YAMLs;
- versão do contrato;
- migration de banco;
- dataset;
- prompts.
# 10. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Usar latest em produção | Deploy não reprodutível. | Usar tag explícita. |
| Mudar prompt sem versão | Sem rastreabilidade. | Versionar prompt. |
| Adicionar campo obrigatório em contrato v1 | Quebra clientes. | Criar v2. |
| Atualizar evaluator sem baseline | Scores não comparáveis. | Registrar versão e metodologia. |
# 11. Critérios de aceite
- [ ] Todos os componentes têm versão.
- [ ] Contratos têm versão independente.
- [ ] Matriz de compatibilidade publicada.
- [ ] Release notes publicadas.
- [ ] Migrações major possuem guide.
- [ ] Rollback definido.
- [ ] Prompts e datasets versionados.
- [ ] Evaluator e certification registram versão.

248
specs/SPEC-014-Templates-and-Agent-Creation-Model.md Normal file
View File

@@ -0,0 +1,248 @@
# SPEC-014 — Templates and Agent Creation Model
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Templates são scaffolds oficiais para criar agentes, MCP servers e backends compatíveis com a Agent Platform OCI.
Eles aceleram o início de um projeto, mas não substituem o framework. O template contém a estrutura mínima de aplicação e os pontos de extensão esperados.
# 2. Problema que resolve
Sem template:
- cada squad cria estrutura diferente;
- imports e configs variam;
- MCP mapping é esquecido;
- datasets não são criados;
- guardrails e judges ficam ausentes;
- deploy não segue padrão;
- onboarding demora.
# 3. Templates oficiais
| Template | Uso |
| --- | --- |
| backend | Criação de agentes com runtime. |
| agent_template_backend_day_zero | Bootstrap acelerado com exemplos. |
| mcp_server | Criação de MCP server. |
| channel_adapter | Adapter de canal quando aplicável. |
# 4. Estrutura padrão de agente
```text
my_agent/
├── app/
│ ├── main.py
│ ├── state.py
│ ├── workflows/
│ │ └── agent_graph.py
│ └── agents/
│ └── my_agent.py
├── config/
│ ├── agents.yaml
│ ├── routing.yaml
│ ├── tools.yaml
│ ├── mcp_servers.yaml
│ ├── mcp_parameter_mapping.yaml
│ ├── guardrails.yaml
│ ├── judges.yaml
│ └── llm_profiles.yaml
├── prompts/
├── datasets/
├── tests/
├── Dockerfile
└── README.md
```
# 5. O que fica no framework
- LangGraph runtime;
- sessão;
- memória;
- checkpoint;
- guardrails genéricos;
- judges genéricos;
- MCP client/router;
- RAG genérico;
- telemetry;
- providers;
- event bus.
# 6. O que fica no agente
- prompts;
- regras de negócio;
- intents;
- tools específicas;
- datasets;
- testes;
- guardrails de domínio;
- judges de domínio.
# 7. Passo a passo para criar agente do zero
## Passo 1 — Copiar template
```bash
cp -R templates/agent_template_backend financeiro_agent
cd financeiro_agent
```
## Passo 2 — Definir escopo
```text
Agente: financeiro_agent
Objetivo: responder dúvidas sobre faturas, pagamentos e cobranças.
Fora de escopo: vendas, cancelamento e suporte técnico.
```
## Passo 3 — Registrar agente
```yaml
agents:
financeiro_agent:
enabled: true
description: "Agente financeiro"
rag_namespace: financeiro
allowed_tools:
- consultar_fatura
- consultar_pagamentos
```
## Passo 4 — Configurar rotas
```yaml
intents:
financeiro_consulta_fatura:
route: financeiro_agent
keywords:
- fatura
- boleto
- cobrança
mcp_tools:
- consultar_fatura
```
## Passo 5 — Configurar tools
```yaml
tools:
consultar_fatura:
server: telecom
enabled: true
idempotent: true
cache_ttl_seconds: 300
```
## Passo 6 — Mapear BusinessContext
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
session_key: session_id
```
## Passo 7 — Criar prompt
```text
Você é um agente financeiro.
Use MCP como fonte transacional.
Use RAG para políticas e procedimentos.
Não invente valores, datas ou status.
```
## Passo 8 — Implementar agente
```python
class FinanceiroAgent(AgentRuntimeMixin):
name = "financeiro_agent"
async def run(self, state):
mcp = await self._collect_mcp_context(state)
rag, rag_metadata = await self._retrieve_rag_context(state)
answer = await self._invoke_llm_cached(
state,
"FinanceiroAgent",
[
{"role": "system", "content": "Você é um agente financeiro."},
{"role": "user", "content": state.get("sanitized_input") or ""},
],
)
return {"response_text": answer, "mcp_results": mcp, "rag_metadata": rag_metadata}
```
## Passo 9 — Criar dataset
```yaml
dataset:
name: financeiro_agent_regression
version: 1.0.0
items:
- id: fin-001
input: "Quero consultar minha fatura"
expected:
route: financeiro_agent
tools:
- consultar_fatura
```
## Passo 10 — Testar
```bash
pytest
af-evaluator run --agent-id financeiro_agent
af-certification run --agent-id financeiro_agent
```
# 8. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Alterar o core para regra de domínio | Dificulta reuso. | Criar agente/config. |
| Esquecer dataset | Sem regressão. | Criar dataset mínimo. |
| Tool sem mapping | Argumentos ausentes. | Configurar mcp_parameter_mapping.yaml. |
| Prompt hardcoded | Sem governança. | Usar prompt_policy/prompts. |
# 9. Critérios de aceite
- [ ] Template usado como base.
- [ ] Agente registrado.
- [ ] Rotas configuradas.
- [ ] Tools configuradas.
- [ ] MCP mapping configurado.
- [ ] Prompt criado.
- [ ] Dataset criado.
- [ ] Testes executados.
- [ ] Evaluator executado.
- [ ] Certification aprovada.

168
specs/SPEC-015-Adoption-and-Eligibility-Criteria.md Normal file
View File

@@ -0,0 +1,168 @@
# SPEC-015 — Adoption and Eligibility Criteria
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Critérios de adoção definem quando um projeto deve usar a Agent Platform OCI e quais requisitos mínimos precisa atender para entrar em desenvolvimento, homologação e produção.
# 2. Problema que resolve
Sem critérios claros:
- qualquer caso simples vira agente;
- projetos sem owner entram na plataforma;
- canais entram sem contrato;
- agentes entram sem dataset;
- produção ocorre sem evaluator;
- operação fica sem dashboard/alerta.
# 3. Casos indicados
| Caso | Exemplo |
| --- | --- |
| Agentes conversacionais | Atendimento, suporte, backoffice. |
| Multiagentes | Handoff entre domínios. |
| Agentes com tools | Consulta/ação em sistemas. |
| Agentes com RAG | Uso de documentos e políticas. |
| Ambientes regulados | Necessidade de governança e auditoria. |
| Canais corporativos | Web, WhatsApp, Voice, URA, CRM. |
# 4. Casos não indicados
| Caso | Motivo |
| --- | --- |
| CRUD simples | API REST sem IA. |
| ETL batch | Pipeline de dados. |
| Job agendado simples | Sem interação. |
| Serviço utilitário | Validação/formatação simples. |
| Integração sem decisão | Proxy API sem raciocínio. |
# 5. Critérios de entrada de negócio
Antes de iniciar:
- business owner;
- technical owner;
- objetivo;
- escopo;
- fora de escopo;
- canais;
- sistemas;
- documentos;
- critérios de sucesso;
- riscos.
# 6. Critérios de arquitetura
Obrigatórios:
- GatewayRequest;
- ChannelResponse;
- BusinessContext;
- health/readiness;
- logs;
- traces;
- dataset;
- evaluator;
- certification.
# 7. Critérios de segurança
Obrigatórios:
- autenticação;
- autorização;
- secrets externos;
- máscara de PII;
- auditoria;
- revisão de risco.
# 8. Critérios de qualidade
Obrigatórios:
- testes unitários;
- testes de integração;
- dataset;
- evaluator;
- thresholds;
- certification.
# 9. Critérios de operação
Obrigatórios:
- métricas;
- dashboards;
- alertas;
- runbook;
- rollback;
- SLO.
# 10. Processo de exceção
Exceções permitidas:
- sem RAG;
- sem MCP;
- sem memória;
- sem handoff;
- sem canal externo.
Toda exceção deve registrar:
```yaml
exception:
reason: "Agente não usa documentos"
approved_by: architecture
expires_at: 2026-12-31
```
# 11. Checklist de adoção
- [ ] Business owner definido.
- [ ] Technical owner definido.
- [ ] Escopo definido.
- [ ] Casos fora de escopo definidos.
- [ ] GatewayRequest definido.
- [ ] BusinessContext definido.
- [ ] Segurança definida.
- [ ] Dataset criado.
- [ ] Evaluator configurado.
- [ ] Certification planejada.
- [ ] Observabilidade planejada.
# 12. Critérios de aceite
- [ ] Projeto elegível para plataforma.
- [ ] Requisitos mínimos atendidos.
- [ ] Exceções documentadas.
- [ ] Plano de homologação definido.
- [ ] Critérios de produção definidos.

227
specs/SPEC-016-Agent-Development-Lifecycle.md Normal file
View File

@@ -0,0 +1,227 @@
# SPEC-016 — Agent Development Lifecycle
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
O ciclo de vida de desenvolvimento de agentes define as etapas desde a descoberta do caso de uso até a operação em produção.
Ele organiza trabalho de produto, arquitetura, engenharia, segurança, avaliação e operação.
# 2. Fluxo do ciclo de vida
```mermaid
flowchart LR
D[Discovery] --> S[Scope]
S --> AD[Agent Design]
AD --> PD[Prompt Design]
PD --> MD[MCP Design]
MD --> RD[RAG Design]
RD --> I[Implementation]
I --> T[Testing]
T --> E[Evaluation]
E --> C[Certification]
C --> H[Homologation]
H --> P[Production]
```
# 3. Etapa 1 — Discovery
Objetivo:
- entender problema;
- identificar usuários;
- mapear canais;
- mapear sistemas;
- mapear documentos;
- mapear riscos.
Saída:
```yaml
discovery:
business_problem: ""
users: []
channels: []
systems: []
documents: []
risks: []
```
# 4. Etapa 2 — Scope Definition
Definir:
- o que o agente faz;
- o que não faz;
- intenções;
- ações permitidas;
- limites;
- critérios de sucesso.
# 5. Etapa 3 — Agent Design
Desenhar:
- agent_id;
- rotas;
- intents;
- BusinessContext;
- tools;
- RAG namespaces;
- memória;
- handoff.
# 6. Etapa 4 — Prompt Design
Criar:
- system prompt;
- prompt policy;
- instruções de domínio;
- exemplos;
- restrições;
- formato de resposta.
# 7. Etapa 5 — MCP Design
Definir:
- tools;
- parâmetros;
- owner;
- SLA;
- timeout;
- retry;
- cache;
- operação mutável ou idempotente.
# 8. Etapa 6 — RAG Design
Definir:
- documentos;
- namespace;
- ingestão;
- chunking;
- embeddings;
- atualização;
- critérios de relevância.
# 9. Etapa 7 — Implementation
Implementar:
- classe do agente;
- configs;
- prompts;
- datasets;
- tests;
- observabilidade específica.
# 10. Etapa 8 — Testing
Testes mínimos:
- unit;
- integration;
- contract;
- MCP;
- RAG;
- guardrails;
- judges;
- runtime;
- channel.
# 11. Etapa 9 — Evaluation
Executar:
```bash
af-evaluator run --agent-id <agent_id> --dataset <dataset>
```
Avaliar:
- quality;
- groundedness;
- safety;
- tool correctness;
- route accuracy.
# 12. Etapa 10 — Certification
Executar:
```bash
af-certification run --agent-id <agent_id>
```
# 13. Etapa 11 — Homologation
Validar com:
- negócio;
- arquitetura;
- segurança;
- operação;
- integração.
# 14. Etapa 12 — Production
Requisitos:
- deploy aprovado;
- alertas ativos;
- dashboards ativos;
- rollback validado;
- runbook disponível.
# 15. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Começar pelo código | Escopo mal definido. | Iniciar por discovery/scope. |
| Criar tool antes da intent | Tool sem contexto. | Definir fluxo primeiro. |
| Dataset depois da produção | Sem regressão. | Criar dataset antes da homologação. |
| Prompt sem critérios | Resposta inconsistente. | Definir prompt policy. |
# 16. Critérios de aceite
- [ ] Discovery concluído.
- [ ] Escopo aprovado.
- [ ] Agent design documentado.
- [ ] Prompts criados.
- [ ] MCP design aprovado.
- [ ] RAG design aprovado quando aplicável.
- [ ] Implementação concluída.
- [ ] Testes executados.
- [ ] Evaluator aprovado.
- [ ] Certification aprovada.
- [ ] Homologação concluída.
- [ ] Produção monitorada.

144
specs/SPEC-017-Release-Management-and-CICD.md Normal file
View File

@@ -0,0 +1,144 @@
# SPEC-017 — Release Management and CI/CD
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Release management define como mudanças entram na plataforma, são testadas, empacotadas, publicadas, promovidas e auditadas.
CI/CD automatiza validações e reduz risco operacional.
# 2. Pipeline padrão
```mermaid
flowchart LR
C[Commit] --> L[Lint]
L --> TC[Type Check]
TC --> UT[Unit Tests]
UT --> IT[Integration Tests]
IT --> CT[Contract Tests]
CT --> SS[Security Scan]
SS --> B[Build]
B --> P[Publish]
P --> DD[Deploy Dev]
DD --> ST[Smoke Tests]
ST --> CERT[Certification]
CERT --> HML[Deploy HML]
HML --> PROD[Deploy Prod]
```
# 3. Stages
| Stage | Função |
| --- | --- |
| validate | Validação inicial de estrutura. |
| lint | Estilo e erros simples. |
| type_check | Tipos e contratos Python. |
| unit_test | Testes unitários. |
| integration_test | Integrações locais. |
| contract_test | Contratos JSON/YAML/API. |
| security_scan | Dependências, secrets e imagens. |
| build_package | Wheel/package. |
| build_image | Imagem Docker. |
| publish | Registry/artifacts. |
| deploy_dev | Ambiente dev. |
| smoke_test | Health e chamadas básicas. |
| certification | Certification Suite. |
| deploy_hml | Homologação. |
| deploy_prod | Produção. |
# 4. Artefatos de release
- imagem Docker;
- pacote Python;
- release notes;
- matriz de compatibilidade;
- migration guide quando necessário;
- evaluator report;
- certification report;
- SBOM quando aplicável;
- evidência de scan;
- changelog.
# 5. Exemplo de pipeline
```yaml
stages:
- lint
- test
- contract
- security
- build
- publish
- deploy
- certification
```
# 6. Gates
| Gate | Quando aplica |
| --- | --- |
| Architecture Gate | Mudanças estruturais, contratos, runtime, gateways. |
| Security Gate | Segredos, identidade, dados sensíveis, MCP externo. |
| Quality Gate | Testes, evaluator, certification. |
| Operations Gate | Dashboards, alertas, runbook, rollback. |
# 7. Estratégia de rollback
Rollback deve restaurar:
- imagem anterior;
- configuração anterior;
- contrato anterior;
- prompt anterior;
- dataset anterior quando necessário;
- migration de banco quando aplicável.
# 8. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Deploy sem certification | Risco funcional. | Rodar certification no pipeline. |
| Sem release notes | Sem rastreabilidade. | Publicar release notes. |
| Sem contract tests | Quebra integração. | Adicionar testes de contrato. |
| Sem rollback | Risco operacional. | Definir estratégia de rollback. |
# 9. Critérios de aceite
- [ ] Pipeline executa lint, type check e testes.
- [ ] Contract tests executam.
- [ ] Security scan executa.
- [ ] Imagem Docker gerada.
- [ ] Artifacts publicados.
- [ ] Smoke tests executados.
- [ ] Certification executada.
- [ ] Release notes publicadas.
- [ ] Rollback definido.
- [ ] Evidências arquivadas.

152
specs/SPEC-018-Security-and-Identity-Model.md Normal file
View File

@@ -0,0 +1,152 @@
# SPEC-018 — Security and Identity Model
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Security and Identity Model define como workloads autenticam, como componentes autorizam ações, como segredos são protegidos e como dados sensíveis são tratados.
# 2. Modelos de autenticação
| Modo | Uso |
| --- | --- |
| config_file | Desenvolvimento local com ~/.oci/config. |
| instance_principal | Execução em OCI Compute. |
| workload_identity | Execução em OKE/Kubernetes. |
| resource_principal | Recursos OCI gerenciados. |
| api_key | Endpoints compatíveis com OpenAI quando aplicável. |
# 3. Workload Identity
Fluxo:
```mermaid
flowchart LR
Pod[Pod Kubernetes] --> SA[ServiceAccount]
SA --> WI[Workload Identity]
WI --> IAM[OCI IAM Policy]
IAM --> Resource[OCI Resource]
```
# 4. Autorização
Escopos:
- agente pode chamar tool?
- tenant pode usar provider?
- canal pode chamar agent_id?
- usuário pode executar ação?
- tool mutável exige confirmação?
# 5. Secrets
Secrets não ficam no código.
Fontes:
- OCI Vault;
- Kubernetes Secrets;
- secret manager corporativo.
Exemplos:
```text
LANGFUSE_SECRET_KEY
OCI_GENAI_API_KEY
ADB_PASSWORD
MCP_BACKEND_TOKEN
```
# 6. Proteção de dados
Aplicar:
- máscara de PII;
- minimização de metadata;
- sanitização de payload;
- não logar secrets;
- retenção controlada;
- classificação de dados.
# 7. Segurança em MCP
MCP tools devem ter:
- autorização por agente;
- allowlist;
- timeout;
- retry;
- idempotência declarada;
- confirmação para operações mutáveis.
# 8. Segurança em canais
Channel Gateway deve:
- validar assinatura;
- validar origem;
- deduplicar;
- rate limit;
- remover tokens;
- normalizar payload;
- rejeitar anexos inválidos.
# 9. Auditoria
Registrar:
- usuário/canal;
- agent_id;
- tenant_id;
- tool chamada;
- modelo usado;
- decisão de guardrail;
- judge score;
- erro;
- trace_id.
# 10. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Secret em .env versionado | Vazamento. | Usar Vault/Secrets. |
| Tool sem autorização | Acesso indevido. | Allowed agents por tool. |
| Payload bruto em logs | Exposição de dados. | Mascarar/minimizar. |
| Instance principal local | Timeout/autenticação inválida. | Usar config_file local. |
# 11. Critérios de aceite
- [ ] Modo de autenticação definido por ambiente.
- [ ] Secrets externos ao código.
- [ ] MCP tools autorizadas por agente.
- [ ] Channel Gateway valida origem.
- [ ] PII mascarada em logs.
- [ ] Eventos auditáveis emitidos.
- [ ] Workload Identity definido para OKE.
- [ ] Security review executado antes de produção.

164
specs/SPEC-019-Evaluation-and-Certification-Framework.md Normal file
View File

@@ -0,0 +1,164 @@
# SPEC-019 — Evaluation and Certification Framework
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Evaluation mede qualidade e comportamento. Certification valida prontidão técnica e funcional.
Evaluator responde:
```text
O agente respondeu bem?
A resposta está fundamentada?
A tool certa foi chamada?
Houve regressão?
```
Certification responde:
```text
O agente está pronto para rodar?
Endpoints funcionam?
MCP funciona?
Guardrails funcionam?
Observabilidade funciona?
```
# 2. Arquitetura
```mermaid
flowchart LR
Runtime[Runtime] --> LF[Langfuse]
LF --> Eval[Offline Evaluator]
Dataset[Datasets] --> Eval
Eval --> Scores[Scores]
Eval --> Reports[Reports]
Cert[Certification Suite] --> Runtime
Cert --> Evidence[Evidences]
```
# 3. Métricas
| Métrica | Descrição |
| --- | --- |
| quality | Clareza, completude e utilidade. |
| groundedness | Aderência a evidências MCP/RAG. |
| safety | Conformidade de segurança. |
| resolution | Resolve a intenção. |
| tool_correctness | Usa tools corretas. |
| route_accuracy | Rota/intenção corretas. |
| policy_compliance | Aderência à política de domínio. |
# 4. Dataset
```yaml
dataset:
name: telecom_contas_regression
version: 1.0.0
items:
- id: billing-001
input: "Quero consultar minha fatura"
business_context:
customer_key: "11999999999"
contract_key: "3000131180"
expected:
route: billing_agent
tools:
- consultar_fatura
min_scores:
quality: 0.75
groundedness: 0.70
```
# 5. EvaluationRun
```json
{
"run_id": "eval-001",
"agent_id": "telecom_contas",
"source": "langfuse",
"period_start": "2026-06-18T00:00:00Z",
"period_end": "2026-06-19T00:00:00Z",
"status": "running"
}
```
# 6. CLI
```bash
af-evaluator run --agent-id telecom_contas --dataset datasets/telecom_contas.yaml
```
# 7. Certification
Valida:
- health;
- GatewayRequest;
- routing;
- identity;
- MCP;
- RAG;
- guardrails;
- judges;
- memory;
- checkpoint;
- Langfuse;
- OTEL.
# 8. Evidências
- JSON;
- HTML;
- TXT.GZ legado;
- scores Langfuse;
- logs;
- traces;
- screenshots quando aplicável.
# 9. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Dataset só com casos felizes | Baixa cobertura. | Incluir negativos e bordas. |
| Evaluator sem baseline | Sem comparação. | Registrar baseline. |
| Certification sem MCP real/mock | Integração não validada. | Criar tool test. |
| Judge sem threshold | Sem critério objetivo. | Definir threshold. |
# 10. Critérios de aceite
- [ ] Dataset versionado.
- [ ] Evaluator executado.
- [ ] Scores persistidos.
- [ ] Certification executada.
- [ ] Relatórios gerados.
- [ ] Thresholds definidos.
- [ ] Casos negativos incluídos.
- [ ] Scores publicados quando aplicável.

166
specs/SPEC-020-Operational-Readiness-and-SRE-Model.md Normal file
View File

@@ -0,0 +1,166 @@
# SPEC-020 — Operational Readiness and SRE Model
## Agent Platform OCI
Version: 1.0.0
---
## Padrão de leitura
Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
A estrutura usada é:
1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.
---
# 1. Conceito
Operational Readiness define os requisitos mínimos para operar a Agent Platform OCI em produção com confiabilidade, observabilidade, capacidade de resposta a incidentes e recuperação.
# 2. Componentes operados
- Agent Gateway;
- Channel Gateway;
- Agent Runtime;
- AI Gateway;
- MCP Gateway;
- MCP Servers;
- Evaluator;
- bancos/repositórios;
- Langfuse/OTEL;
- Redis/Mongo/ADB quando usados.
# 3. Health e readiness
Endpoints mínimos:
```text
GET /health
GET /ready
GET /version
```
# 4. SLOs
| Componente | Latência | Disponibilidade |
| --- | --- | --- |
| Agent Gateway | p95 < 1s | 99.5% |
| Agent Runtime | p95 < 5s | 99.0% |
| AI Gateway | p95 < 10s | 99.0% |
| MCP Gateway | p95 < 2s | 99.0% |
| Evaluator | janela batch | execução diária |
# 5. Métricas
- requests_total;
- request_latency_ms;
- errors_total;
- active_sessions;
- llm_tokens_total;
- llm_cost_estimated;
- mcp_tool_calls_total;
- guardrail_blocks_total;
- judge_scores;
- evaluator_scores.
# 6. Dashboards
Dashboards mínimos:
- Platform Overview;
- Runtime;
- Gateway;
- AI Gateway;
- MCP Gateway;
- Guardrails;
- Evaluator;
- Cost/Usage;
- Incidents.
# 7. Alertas
| Alerta | Condição |
| --- | --- |
| HighErrorRate | 5xx acima do limite. |
| LatencySLOBreach | p95 acima do SLO. |
| LLMProviderDown | Falhas consecutivas no provider. |
| MCPTimeoutSpike | Aumento de timeout MCP. |
| GuardrailSpike | Aumento anômalo de bloqueios. |
| EvaluatorFailed | Run falhou. |
# 8. Runbooks
Runbook deve conter:
- sintoma;
- impacto;
- consultas;
- dashboards;
- logs;
- ações;
- rollback;
- escalonamento.
# 9. Incident management
Fluxo:
```mermaid
flowchart LR
Detect[Detect] --> Triage[Triage]
Triage --> Mitigate[Mitigate]
Mitigate --> Recover[Recover]
Recover --> Postmortem[Postmortem]
```
# 10. Capacidade
Avaliar:
- QPS;
- sessões simultâneas;
- tokens/minuto;
- chamadas MCP/minuto;
- latência de provider;
- uso de memória;
- storage de checkpoints.
# 11. Erros comuns
| Erro | Impacto | Correção |
| --- | --- | --- |
| Sem readiness | Tráfego antes do app estar pronto. | Implementar /ready. |
| Sem alertas MCP | Falha silenciosa. | Criar alertas por tool. |
| Sem runbook | MTTR alto. | Criar runbooks por incidente. |
| Sem custo LLM | Sem controle financeiro. | Registrar tokens/custos. |
# 12. Production readiness checklist
- [ ] Health checks ativos.
- [ ] Readiness checks ativos.
- [ ] Logs estruturados.
- [ ] Métricas exportadas.
- [ ] Traces exportados.
- [ ] Dashboards criados.
- [ ] Alertas configurados.
- [ ] Runbooks disponíveis.
- [ ] Rollback validado.
- [ ] SLOs definidos.
- [ ] Capacidade estimada.
- [ ] Incident process definido.

28
specs/en/README.md Normal file
View File

@@ -0,0 +1,28 @@
# Agent Platform OCI — Technical Specifications (English)
The English-language specifications are listed below. File names and technical identifiers are aligned with the original documents.
| Specification | Title |
|---|---|
| [SPEC-001-Architecture.md](SPEC-001-Architecture.md) | SPEC-001 — Architecture |
| [SPEC-002-Agent-Runtime.md](SPEC-002-Agent-Runtime.md) | SPEC-002 — Agent Runtime |
| [SPEC-003-Agent-Gateway.md](SPEC-003-Agent-Gateway.md) | SPEC-003 — Agent Gateway |
| [SPEC-004-MCP-Gateway.md](SPEC-004-MCP-Gateway.md) | SPEC-004 — MCP Gateway |
| [SPEC-005-Guardrails.md](SPEC-005-Guardrails.md) | SPEC-005 — Guardrails |
| [SPEC-006-Evals.md](SPEC-006-Evals.md) | SPEC-006 — Evals |
| [SPEC-007-Observability.md](SPEC-007-Observability.md) | SPEC-007 — Observability |
| [SPEC-008-Deployment.md](SPEC-008-Deployment.md) | SPEC-008 — Deployment |
| [SPEC-009-Channel-Gateway.md](SPEC-009-Channel-Gateway.md) | SPEC-009 — Channel Gateway |
| [SPEC-010-Agent-Development.md](SPEC-010-Agent-Development.md) | SPEC-010 — Agent Development |
| [SPEC-011-Governance-Model.md](SPEC-011-Governance-Model.md) | SPEC-011 — Governance Model |
| [SPEC-012-Canonical-Contracts.md](SPEC-012-Canonical-Contracts.md) | SPEC-012 — Canonical Contracts |
| [SPEC-013-Versioning-and-Compatibility-Model.md](SPEC-013-Versioning-and-Compatibility-Model.md) | SPEC-013 — Versioning and Compatibility Model |
| [SPEC-014-Templates-and-Agent-Creation-Model.md](SPEC-014-Templates-and-Agent-Creation-Model.md) | SPEC-014 — Templates and Agent Creation Model |
| [SPEC-015-Adoption-and-Eligibility-Criteria.md](SPEC-015-Adoption-and-Eligibility-Criteria.md) | SPEC-015 — Adoption and Eligibility Criteria |
| [SPEC-016-Agent-Development-Lifecycle.md](SPEC-016-Agent-Development-Lifecycle.md) | SPEC-016 — Agent Development Lifecycle |
| [SPEC-017-Release-Management-and-CICD.md](SPEC-017-Release-Management-and-CICD.md) | SPEC-017 — Release Management and CI/CD |
| [SPEC-018-Security-and-Identity-Model.md](SPEC-018-Security-and-Identity-Model.md) | SPEC-018 — Security and Identity Model |
| [SPEC-019-Evaluation-and-Certification-Framework.md](SPEC-019-Evaluation-and-Certification-Framework.md) | SPEC-019 — Evaluation and Certification Framework |
| [SPEC-020-Operational-Readiness-and-SRE-Model.md](SPEC-020-Operational-Readiness-and-SRE-Model.md) | SPEC-020 — Operational Readiness and SRE Model |
[Portuguese specifications](../README.md) · [Developer guide](../../README.md)

239
specs/en/SPEC-001-Architecture.md Normal file
View File

@@ -0,0 +1,239 @@
# SPEC-001 — Architecture
## Scope
The Agent Platform OCI consists of reusable components, deployable applications, integration contracts, agent templates, an evaluation layer, and operational artifacts.
## Components
| Componente | Tipo | Responsibility |
|---|---|---|
| `libs/agent_framework` | Lib | Core reutilizável of the framework. |
| `runtimes/langgraph_runtime` | Runtime | Execution of Agents based on LangGraph. |
| `apps/agent_gateway` | App | Input padronizada and Routing of Agents/backends. |
| `apps/channel_gateway` | App | Normalização of canais external. |
| `apps/ai_gateway` | App | Abstração, Governance and Routing of modelos. |
| `apps/mcp_gateway` | App | Governance, Catalog and Execution of tools MCP. |
| `mcp/servers` | Apps | MCP servers of Domain. |
| `evals/offline` | App/Lib | Evaluation offline/batch. |
| `evals/certification` | Suite | Certification técnica and funcional. |
| `templates/agent_template_backend` | Template | Scaffold for new Agents. |
| `specs` | documentation | contracts SDD versionados. |
| `deploy` | Operations | Docker, Kubernetes and Helm. |
## Repository structure
```text
agent_platform_oci/
├── libs/
│ └── agent_framework/
├── runtimes/
│ └── langgraph_runtime/
├── apps/
│ ├── agent_gateway/
│ ├── channel_gateway/
│ ├── ai_gateway/
│ └── mcp_gateway/
├── mcp/
│ └── servers/
├── evals/
│ ├── offline/
│ └── certification/
├── templates/
│ ├── agent_template_backend/
│ └── agent_template_backend_day_zero/
├── specs/
├── deploy/
│ ├── docker/
│ ├── k8s/
│ └── helm/
├── tests/
└── docs/
```
## Logical architecture
```mermaid
flowchart LR
C[Canal] --> CG[Channel Gateway]
CG --> AG[Agent Gateway]
AG --> RT[Agent Runtime]
RT --> FW[Agent Framework Core]
RT --> AIG[AI Gateway]
RT --> MCPG[MCP Gateway]
MCPG --> MCPS[MCP Servers]
RT --> OBS[Observability]
RT --> MEM[Memory/Checkpoint]
OBS --> LF[Langfuse/OTEL]
LF --> EV[Evaluator]
```
## Physical architecture
| service | Porta Standard | Deploy | Escala |
|---|---:|---|---|
| Agent Gateway | 9000 | Kubernetes Deployment | Horizontal |
| Agent Backend / Runtime | 8000 | Kubernetes Deployment | Horizontal with external storage |
| Channel Gateway | 7000 | Kubernetes Deployment | Horizontal |
| AI Gateway | 9100 | Kubernetes Deployment | Horizontal |
| MCP Gateway | 8300 | Kubernetes Deployment | Horizontal |
| MCP Servers | 8001+ | Kubernetes Deployment | Per domain |
| Evaluator API | 9300 | Deployment/CronJob | By batch workload |
| Frontend Demo | 5173 | Optional | Noncritical |
## Main contracts
| Contract | producer | consumer |
|---|---|---|
| GatewayRequest | Channel Gateway / Agent Gateway | Agent Runtime |
| ChannelResponse | Agent Runtime | Channel Gateway / Cliente |
| BusinessContext | Channel Gateway / Identity resolve | Runtime / Agents / MCP |
| LLMRequest | Agent Runtime | AI Gateway |
| LLMResponse | AI Gateway | Agent Runtime |
| ToolInvocation | Agent Runtime / MCP Gateway | MCP Server |
| ToolResult | MCP Server / MCP Gateway | Agent Runtime |
| GuardrailResult | Guardrail Engine | Runtime / Observability |
| JudgeResult | Judge Engine / Evaluator | Runtime / Evaluator |
| EvaluationRun | Evaluator | Persistence / Dashboards |
## GatewayRequest
```json
{
"channel": "web",
"tenant_id": "default",
"agent_id": "telecom_contas",
"payload": {
"message": "Quero consultar minha fatura",
"session_id": "session-001",
"user_id": "user-001",
"message_id": "msg-001",
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"interaction_key": "301953872",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001"
}
}
}
```
## ChannelResponse
```json
{
"channel": "web",
"session_id": "default:telecom_contas:session-001",
"text": "Resposta final do agente.",
"metadata": {
"tenant_id": "default",
"agent_id": "telecom_contas",
"route": "billing_agent",
"intent": "billing_invoice_explanation"
}
}
```
## Flow main
```mermaid
sequenceDiagram
participant Canal
participant ChannelGateway
participant AgentGateway
participant Runtime
participant AIGateway
participant MCPGateway
participant Store
Canal->>ChannelGateway: Payload bruto
ChannelGateway->>AgentGateway: GatewayRequest
AgentGateway->>Runtime: GatewayRequest normalizado
Runtime->>Store: Sessão, memória e checkpoint
Runtime->>Runtime: Guardrails de entrada
Runtime->>Runtime: Router/Supervisor
Runtime->>MCPGateway: ToolInvocation
MCPGateway-->>Runtime: ToolResult
Runtime->>AIGateway: LLMRequest
AIGateway-->>Runtime: LLMResponse
Runtime->>Runtime: Guardrails de saída e Judges
Runtime->>Store: Persistência
Runtime-->>AgentGateway: ChannelResponse
AgentGateway-->>ChannelGateway: ChannelResponse
ChannelGateway-->>Canal: Resposta do canal
```
## Configuration
| file | Uso |
|---|---|
| `.env` | Provider, Authentication, flags and endpoints por ambiente. |
| `agents.yaml` | Registration of Agents. |
| `routing.yaml` | Intents, rotas, Policies and fallback. |
| `guardrails.yaml` | Guardrails global. |
| `judges.yaml` | Judges global. |
| `llm_profiles.yaml` | Profiles of modelos por componente. |
| `mcp_servers.yaml` | MCP servers disponíveis. |
| `tools.yaml` | Catalog of tools. |
| `mcp_parameter_mapping.yaml` | Mapeamento BusinessContext → argumentos MCP. |
| `identity.yaml` | Resolução of Identity of negócio. |
| `observability.yaml` | Logs, Metrics, traces and exporters. |
| `evals.yaml` | Datasets, Metrics and Configuration of the evaluator. |
## Events
| Evento | Origem | Description |
|---|---|---|
| `gateway.request.received` | Agent Gateway | Request recebida. |
| `channel.normalized` | Channel Gateway | Payload convertido em GatewayRequest. |
| `runtime.started` | Runtime | Execution iniciada. |
| `guardrail.input.completed` | Guardrails | Guardrails of Input concluídos. |
| `route.selected` | Router/Supervisor | Rota definida. |
| `mcp.tool.completed` | MCP Gateway | Tool executada. |
| `llm.completed` | AI Gateway | Call LLM concluída. |
| `judge.completed` | Judge Engine | Evaluation concluída. |
| `runtime.completed` | Runtime | Execution finalizada. |
## 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
- [ ] Repository structure separa libs, runtimes, apps, mcp, evals, templates, specs and deploy.
- [ ] each app deployável possui Contract of Input/Output documentado.
- [ ] GatewayRequest and ChannelResponse are versionados.
- [ ] BusinessContext is Used como Contract canônico.
- [ ] Runtime No recebe payload bruto of canal.
- [ ] AI Gateway and MCP Gateway possuem fronteiras explícitas.
- [ ] Evaluator is componente padronizado of Evaluation.
- [ ] all os services possuem health check.
- [ ] Telemetria fim-a-fim correlaciona request_id, trace_id and session_id.
- [ ] Configuration críticas possuem YAML dedicado.
## 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. |

333
specs/en/SPEC-002-Agent-Runtime.md Normal file
View File

@@ -0,0 +1,333 @@
# SPEC-002 — Agent Runtime
## 1. Overview
The Agent Runtime coordinates conversational execution for agents on the OCI platform. It combines LangGraph graphs, per-conversation state, intent routing, domain agents, guardrails, judges, long-term memory, and persistence. The reusable framework library provides services and contracts consumed by agent backends; the reference `agent_template_backend` assembles these services into an executable workflow.
## 2. Implementation structure
| Component | Location | Responsibility |
|---|---|---|
| Shared runtime | `libs/agent_framework/src/agent_framework/runtime/` | Reusable agent-execution capabilities. |
| Reference workflow | `templates/agent_template_backend/app/workflows/agent_graph.py` | Graph construction and workflow-node implementations. |
| Workflow state | `templates/agent_template_backend/app/state.py` | Typed definition of data exchanged between nodes. |
| Agent configuration | `templates/agent_template_backend/config/agents.yaml` | Agent registry and policy/configuration file paths. |
| Routing configuration | `templates/agent_template_backend/config/routing.yaml` | Router mode, fallback, threshold, and intent catalog. |
| Tool configuration | `templates/agent_template_backend/config/tools.yaml` | Tool definitions used by agents. |
## 3. Execution state
The workflow uses the `AgentState` definition shown below. Its `TypedDict(total=False)` declaration allows nodes to add the fields relevant to each execution stage without requiring every field to be present in each state instance.
```python
from typing import Any, TypedDict
class AgentState(TypedDict, total=False):
tenant_id: str
agent_id: str
session_id: str
conversation_key: str
workflow_id: str
agent_profile: dict[str, Any]
user_text: str
sanitized_input: str
route: str
intent: str
route_decision: dict[str, Any]
answer: str
final_answer: str
history: list[dict[str, Any]]
context: dict[str, Any]
guardrail_decisions: list[dict[str, Any]]
judge_results: list[dict[str, Any]]
next_state: str
domain: str
mcp_tools: list[str]
mcp_results: list[dict[str, Any]]
rag_results: list[dict[str, Any]]
available_mcp_tools: list[str]
selected_tool_call: dict[str, Any]
pending_tool_call: dict[str, Any]
active_transaction: dict[str, Any]
last_transaction: dict[str, Any]
transaction_status: str
transaction_pre_validation: dict[str, Any]
transaction_evidence: list[dict[str, Any]]
last_transaction_evidence: dict[str, Any]
relevant_transaction_evidence: list[dict[str, Any]]
confirmation_required: bool
confirmation_received: bool
tool_policy_result: dict[str, Any]
missing_parameters: list[str]
supervisor_plan: dict[str, Any]
supervisor_results: list[dict[str, Any]]
agent_responses: list[dict[str, Any]]
pending_topics: list[dict[str, Any]]
handled_topics: list[dict[str, Any]]
operation_results: dict[str, dict[str, Any]]
multi_intent_plan: dict[str, Any]
active_agent: str
route_bypassed: bool
continuity_signal: dict[str, Any]
session_control: str
session_ended: bool
human_handoff_requested: bool
blocked: bool
supervisor_action: str
supervisor_guidance: str
supervisor_attempt: int
supervisor_handover_reason: str
output_supervisor_results: list[dict[str, Any]]
output_guardrails_already_applied: bool
long_term_memories: list[dict[str, Any]]
long_term_memory_context: str
long_term_memory_write_result: dict[str, Any]
long_term_memory_subject_key: str
long_term_memory_load_error: str
```
## 4. Execution flow
The workflow is compiled using `FrameworkStateGraph(AgentState)` with a checkpointer created by `create_langgraph_checkpointer(self.settings)`.
```mermaid
flowchart TD
START([START]) --> input_guardrails
input_guardrails -->|continue| load_long_term_memory
input_guardrails -->|blocked| output_guardrails
load_long_term_memory --> routing_decision
routing_decision --> billing_agent
routing_decision --> product_agent
routing_decision --> orders_agent
routing_decision --> support_agent
routing_decision --> handoff
routing_decision --> human_handoff
routing_decision --> end_session
routing_decision --> supervisor_agent
billing_agent --> output_supervisor
product_agent --> output_supervisor
orders_agent --> output_supervisor
support_agent --> output_supervisor
handoff --> output_supervisor
human_handoff --> output_supervisor
end_session --> output_supervisor
supervisor_agent --> output_supervisor
output_supervisor --> output_guardrails
output_guardrails -->|continue| judge
output_guardrails -->|blocked| persist
judge --> supervisor_review
supervisor_review --> persist_long_term_memory
persist_long_term_memory --> persist
persist --> END([END])
```
Routing after `input_guardrails` depends on `state['blocked']`. Following `routing_decision`, the value of `state['route']` selects one of the registered nodes, defaulting to `billing_agent` when the key is absent. Routing after `output_guardrails` also checks `state['blocked']`.
## 5. Workflow nodes
| Node | Responsibility |
|---|---|
| `input_guardrails` | Evaluates and processes input before routing. |
| `load_long_term_memory` | Loads long-term memory context. |
| `routing_decision` | Determines the conversation's execution destination. |
| `billing_agent` | Runs the billing agent. |
| `product_agent` | Runs the product and services agent. |
| `orders_agent` | Runs the orders agent. |
| `support_agent` | Runs the support agent. |
| `handoff` | Handles the transfer path defined by the workflow. |
| `human_handoff` | Handles requests for transfer to a human representative. |
| `end_session` | Handles session termination. |
| `supervisor_agent` | Runs the supervisor-related path. |
| `output_supervisor` | Processes response supervision. |
| `output_guardrails` | Applies output policies. |
| `judge` | Evaluates the response. |
| `supervisor_review` | Processes review after the judge. |
| `persist_long_term_memory` | Performs the long-term memory write stage. |
| `persist` | Performs the final workflow persistence stage. |
Nodes are wrapped by the `_node` method, which executes them within `self.langgraph_telemetry.node(name, state)`.
## 6. Routing
The `config/routing.yaml` file defines the main options under the `router` key:
```yaml
# Configurable enterprise routing with MCP-aware intents.
router:
# mode can also be set through the ROUTING_MODE environment variable.
# Values: router | supervisor
mode: router
fallback_agent: billing_agent
confidence_threshold: 0.65
allow_handoff: true
```
The configuration also contains `state_policies`, which keep certain confirmation or parameter-collection stages bound to the corresponding agent, and an `intents` catalog with attributes such as `name`, `domain`, `agent`, `priority`, `mcp_tools`, `keywords`, and `examples`.
The agent catalog in `config/agents.yaml` declares `telecom_contas` and `retail_orders`. Each entry points to prompt, routing, guardrail, judge, MCP server, and tool policy/configuration files, as well as domain metadata.
## 7. Agent and tool execution
Domain nodes dispatch requests to the billing, product, order, and support agent instances. MCP tools are exposed to agents through tool configuration and tool-routing components. Tool results can be carried in `mcp_results`; selected tool names are stored in `mcp_tools`.
State also supports `selected_tool_call`, `pending_tool_call`, `tool_policy_result`, `missing_parameters`, and transaction-evidence fields. These allow preparation, validation, confirmation, and execution stages to share information across the conversation.
## 8. Transaction state
`AgentState` holds the current transaction in `active_transaction` and the latest completed transaction in `last_transaction`. The fields `transaction_status`, `transaction_pre_validation`, `transaction_evidence`, `last_transaction_evidence`, `relevant_transaction_evidence`, `confirmation_required`, and `confirmation_received` carry the information required for transactional processing.
Routing configuration defines state policies for `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION`, `WAITING_ORDER_CONFIRMATION`, `WAITING_SUPPORT_CONFIRMATION`, `COLLECTING_BILLING_PARAMETERS`, `COLLECTING_PRODUCT_PARAMETERS`, `COLLECTING_ORDER_PARAMETERS`, and `COLLECTING_SUPPORT_PARAMETERS`.
The transactional-flow reference guide is [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
## 9. Memory and checkpoints
The workflow includes two explicit long-term memory stages: `load_long_term_memory`, before routing, and `persist_long_term_memory`, before final persistence. The fields `long_term_memories`, `long_term_memory_context`, `long_term_memory_write_result`, `long_term_memory_subject_key`, and `long_term_memory_load_error` form this capability's state interface.
Graph construction passes the result of `create_langgraph_checkpointer(self.settings)` to `compile`. Checkpoint storage and retrieval are handled by the configured checkpointer, retaining state continuity across interactions according to the selected backend.
## 10. Guardrails, supervision, and judges
Input passes through `input_guardrails` before memory loading and routing. When input is blocked, execution goes directly to `output_guardrails`.
Agent responses pass through `output_supervisor` and `output_guardrails`. An unblocked response proceeds to `judge` and `supervisor_review`; a blocked response goes to `persist`. Results are carried in `guardrail_decisions`, `output_supervisor_results`, `judge_results`, `supervisor_action`, `supervisor_guidance`, and related state fields.
## 11. Observability
The workflow wraps each node in `langgraph_telemetry.node` instrumentation, associating execution with the node identity and conversation state. Framework telemetry and observability mechanisms provide traceability for decisions and execution stages.
## 12. Error handling and recovery by component
### 12.1. Failure propagation principles
The runtime distinguishes failures handled within a stage, negative policy/tool results, and exceptions that prevent graph execution. Each component's contract determines whether processing continues, a response is modified, or the exception is returned to the caller. The `blocked` field represents a policy decision in state; it does not generically denote a Python exception.
| Area | Representation | Execution impact |
|---|---|---|
| Guardrails | Decisions with `allowed`, `code`, and `reason`; supervision decisions with `action` | May stop routing, replace or sanitize the response, or allow processing to continue. |
| MCP | Tool results with `ok`, `error`, `tool_name`, and source-specific execution details | The agent uses the result to control how the operation proceeds. |
| Long-term memory | `long_term_memory_load_error` and `long_term_memory_write_result` fields | Read or write exceptions caught in the node do not terminate graph execution. |
| RAG | Retrieval result or technical-error object | A failure may be incorporated into the agent's execution context. |
| Checkpoints | Repository exceptions, integrity validation, and version recovery | Recovery may select an earlier valid checkpoint or start from a clean state; exhausted storage retries propagate an exception. |
| Workflow | Exceptions raised by nodes or `graph.ainvoke` | Execution is marked as failed in telemetry and the exception is re-raised. |
### 12.2. Input, sessions, and input guardrails
The `input_guardrails` node first checks `session_ended`. If the session has already ended, it sets `blocked=True`, `session_control="END_SESSION"`, `session_ended=True`, and `next_state="SESSION_ENDED"`, composes the message configured in `SESSION_ALREADY_ENDED_MESSAGE`, and records `session.message.rejected_after_end`. This prevents the message from reaching the router or domain agents.
For active sessions, the pipeline evaluates guardrails and stores decisions in `guardrail_decisions`. If any decision has `allowed=False`, the node generates a safe response, sets `route="blocked"` and `intent="input_guardrail_blocked"`, clears the turn's MCP tool and result lists, and follows the output branch. `_input_guardrail_user_message` has specific messages for `COER`, `INPUT_SIZE`, `DLEX_IN`, `PINJ`, `TOX`, and `CMP`, plus a default response for other codes. Detailed reasons remain in decisions and telemetry; the runtime controls the user-facing message.
Evaluation records `guardrails.input.completed`, individual decisions in guardrail telemetry, and GRL events through the observer. When input is blocked, the pre-routing memory node, router, and agent tools do not execute. The branch proceeds to `output_guardrails` and, according to graph conditions, ends in `persist`.
**Implementation reference:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`input_guardrails`, `_input_guardrail_user_message`, `_after_input_guardrails`).
### 12.3. Routing, classification, and continuity
Routing configuration is loaded through `routing/config_loader.py`; a missing file raises `FileNotFoundError`. `EnterpriseRouter` locally handles errors from classification calls and model-output parsing. In the semantic classifier for expected inputs, a failed `llm.ainvoke` call is logged with `logger.warning`, and the function returns `(None, None)`. Subsequent routing paths can therefore operate without treating the failure as a valid classification.
The flow uses `fallback_agent` and `confidence_threshold` settings, as well as state policies in `routing.yaml`. Selecting a fallback is a routing decision, not intrinsically an error code. The `route_decision`, `continuity_signal`, `pending_topics`, and `multi_intent_plan` structures preserve information for resumption and routing of related turns.
Failure recovery depends on the method actually invoked: not every internal routing error is handled by the same `except` clause. Exceptions escaping the node reach the workflow failure handler in `ainvoke`.
**Implementation references:** `libs/agent_framework/src/agent_framework/routing/config_loader.py`, `routing/enterprise_router.py`, `routing/continuity.py`; `templates/agent_template_backend/app/workflows/agent_graph.py` (`routing_decision`, `ainvoke`).
### 12.4. Agent execution, arguments, and MCP tools
Tool preparation is handled by the reusable runtime in `runtime/agent_runtime.py`. `_prepare_mcp_call` invokes the MCP router and returns a structured preparation error when `prepare_call` provides one. If the tool router is unavailable, the runtime produces a negative result with `ok=False`, `tool_name`, and the description `MCP Tool Router indisponível`.
During parameter mapping, regular-expression errors (`re.error`, `IndexError`, `ValueError`) are caught and logged as `mcp.parameter.regex_extract_failed`. For LLM-based extraction, missing model/message data and inference exceptions are recorded as `mcp.parameter.llm_extract_failed`. Argument processing and call results remain subject to tool validation and agent policies; absence of an exception alone does not establish success.
MCP results may expose `ok=False` and `error`, including validation and execution failures. The implementation emits `NOC.MCP_TOOL_FAILED` along one path that aggregates negative tool results. Transaction handling, confirmations, evidence, and partial results operate on execution data including `active_transaction`, `transaction_pre_validation`, `transaction_evidence`, and `operation_results`, depending on operation type.
**Implementation reference:** `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py` (`_prepare_mcp_call`, parameter handling, tool execution, and result aggregation).
### 12.5. RAG and knowledge retrieval
The runtime wraps knowledge-retrieval failures in a technical result containing `technical_error=True`, `technical_error_in_rag=True`, `status="error"`, and a description in `error`. This allows the agent to distinguish retrieval failure from a completed search yielding no useful evidence.
The RAG service also validates preconditions: `RagService.generate_answer` raises `RuntimeError` when used without an LLM, and `kbdb_service.py` checks configuration/signatures and disallows ingestion/publication when the KBDB provider is configured exclusively for serving. During ingestion, a missing directory may raise `FileNotFoundError`, while `chunk_overlap >= chunk_size` raises `ValueError`. These initialization and administration errors must not be confused with an empty retrieval result during a conversation.
**Implementation references:** `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py` (technical RAG error handling); `rag/rag_service.py`, `rag/kbdb_service.py`, `rag/ingest.py`.
### 12.6. Long-term memory
The `load_long_term_memory` node catches exceptions from `long_term_memory_manager.load(state)`. If loading fails, it publishes `long_term_memory.load.failed`, returns `long_term_memories=[]` and `long_term_memory_context=""`, and stores the exception text in `long_term_memory_load_error`. The conversation continues without retrieved long-term memory context for that turn.
The `persist_long_term_memory` node catches exceptions from `long_term_memory_manager.persist_turn(state)`. A successful write publishes `long_term_memory.persist.completed` and stores its return value in `long_term_memory_write_result`; a failure publishes `long_term_memory.persist.failed` and returns `{"saved": 0, "error": str(exc)}` in the same field. Thus, a long-term memory persistence failure is isolated within the node and does not automatically terminate the graph with an exception.
These fields concern the workflow's long-term memory and are separate from LangGraph checkpoint persistence.
**Implementation reference:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`load_long_term_memory`, `persist_long_term_memory`).
### 12.7. Checkpoints, retries, and integrity
The graph is compiled with the checkpointer created by `create_langgraph_checkpointer(self.settings)` and uses `conversation_key` or `session_id` as `thread_id` in `ainvoke`. The repository layer in `checkpoints/checkpoint_repository.py` retries operations protected by `_with_retry`: after an exception, it computes a bounded exponential delay with jitter, records `checkpoint.<operation>.retry`, and retries up to `retry_policy.max_attempts`. Once attempts are exhausted, it re-raises the last exception.
On recovery, `recover_latest` scans recent records, discards those failing `is_valid_checkpoint`, and skips checkpoints with `CheckpointIntegrityError`, recording `checkpoint.recovery.skip_corrupt`. If no valid checkpoint remains after integrity failures, recovery returns `None` so execution can begin without restored state. Compaction after a write is isolated: a failure records `checkpoint.compaction.failed` and does not undo the completed write.
Integrity recovery cannot guarantee retention of history if no valid checkpoint can be recovered. Storage-communication errors that exceed the retry policy follow the exception path of the calling component.
**Implementation references:** `libs/agent_framework/src/agent_framework/checkpoints/checkpoint_repository.py`, `checkpoints/langgraph_saver.py`; `templates/agent_template_backend/app/workflows/agent_graph.py` (`ainvoke`).
### 12.8. Output supervision and output guardrails
`output_supervisor` evaluates the response and interprets `RailAction`. For `ALLOW`, `SANITIZE`, and `OBSERVE`, it uses `decision.candidate`; for `HANDOVER`, it supplies a message referring the user to a specialist; for other actions, it uses `decision.fallback_message`. The action, guidance, and results are stored in `supervisor_action`, `supervisor_guidance`, and `output_supervisor_results`.
The node sets `output_guardrails_already_applied=True`. When `output_guardrails` sees this flag, it returns the prepared response without running the pipeline again. Otherwise, it runs `guardrails.run_output`, records decisions, blocks, and GRL completion, then returns `final_answer`.
The parallel rail executor (`guardrails/parallel_executor.py`) converts unexpected task failures to `RailResult`: it selects `RailAction.BLOCK` when `fail_closed` is enabled and `RailAction.OBSERVE` otherwise. This is executor policy, not a claim that all guardrails fail closed. The executor also handles cancellation and early termination when a terminal action is produced.
**Implementation references:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`output_supervisor`, `output_guardrails`); `libs/agent_framework/src/agent_framework/guardrails/parallel_executor.py`.
### 12.9. Judges and supervisor review
The `judge` node builds evaluation context from MCP results, RAG results, and relevant transaction evidence, executes evaluation, and stores outcomes in `judge_results`. The subsequent review invokes `self.supervisor.review` and records `supervisor.review.completed`. A judge's failing score or recommendation belongs to evaluation and review; it is not, by definition, an infrastructure exception.
The judge layer validates configuration and structured responses. The calibrated judge client raises `ValueError` for unsupported tasks or invalid structured output. LLM construction and loading of judge configuration can also raise `RuntimeError` or `ValueError` under the conditions checked in `judges/judge.py`. Exceptions not caught within the node propagate to `ainvoke`.
**Implementation references:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`judge`, `supervisor_review`); `libs/agent_framework/src/agent_framework/judges/judge.py`, `judges/calibrated/llm_client.py`.
### 12.10. Final persistence and workflow-level failure
The `persist` node emits completion observability, including the IC event `AGENT_COMPLETED`. The public graph entry point is `ainvoke`, which configures the thread, starts workflow telemetry, and emits the start events `NOC.001` and `AGENT_STARTED` before calling `self.graph.ainvoke`.
If `graph.ainvoke` completes, the workflow is marked completed and its final state is returned. If an exception escapes the graph, the `except Exception` handler in `ainvoke` calls `workflow_telemetry.failed("agent_workflow", exc)`, emits `NOC.005` with `error` and `exception_type`, and re-raises the same exception. This path does not automatically convert the error into a successful conversational response.
Failures handled inside nodes, such as long-term memory failures, do not trigger the global `except`. Unhandled errors in routing, agent execution, checkpoint storage, or other stages may reach this boundary and cause a workflow-level failure.
**Implementation reference:** `templates/agent_template_backend/app/workflows/agent_graph.py` (`persist`, `ainvoke`).
### 12.11. Operational events and tracing
`_node` wraps every node execution in `self.langgraph_telemetry.node(name, state)`. Additional mechanisms use workflow spans, semantic events, and the observer for GRL, IC, and NOC. Concrete records in the flow include `session.message.rejected_after_end`, `guardrails.input.completed`, `guardrails.output.completed`, `output_supervisor.completed`, `supervisor.review.completed`, `long_term_memory.load.failed`, `long_term_memory.persist.failed`, `long_term_memory.persist.completed`, and `workflow_telemetry.failed` on workflow-level failure.
Operational errors should be correlated using `conversation_key` or `session_id`, together with `tenant_id` and `agent_id` when available. A memory or tool failure event does not necessarily indicate overall workflow failure; this depends on whether the component returned a state/result or propagated an exception.
**Implementation references:** `templates/agent_template_backend/app/workflows/agent_graph.py`; `libs/agent_framework/src/agent_framework/observability/`.
## 13. Integration interfaces
| Interface | Runtime integration |
|---|---|
| LangGraph | State-graph construction, compilation, and execution. |
| Domain agents | Specialized billing, product, order, and support nodes. |
| MCP | Tool selection, parameter mapping, and execution by agents. |
| RAG | Knowledge retrieval incorporated into agent execution. |
| Guardrails | Input and output evaluation. |
| Judges | Evaluation after response generation. |
| Memory | Long-term information loading and writing. |
| Checkpointer | Graph-state persistence. |
| Observability | Per-node telemetry and execution tracing. |
## 14. Implementation references
- `libs/agent_framework/src/agent_framework/runtime/`
- `templates/agent_template_backend/app/state.py`
- `templates/agent_template_backend/app/workflows/agent_graph.py`
- `templates/agent_template_backend/config/agents.yaml`
- `templates/agent_template_backend/config/routing.yaml`
- `templates/agent_template_backend/config/tools.yaml`
- [`SPEC-004 — MCP Gateway`](SPEC-004-MCP-Gateway.md)
- [`SPEC-005 — Guardrails`](SPEC-005-Guardrails.md)
- [`SPEC-007 — Observability`](SPEC-007-Observability.md)
- [`SPEC-012 — Canonical Contracts`](SPEC-012-Canonical-Contracts.md)

273
specs/en/SPEC-003-Agent-Gateway.md Normal file
View File

@@ -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.

231
specs/en/SPEC-004-MCP-Gateway.md Normal file
View File

@@ -0,0 +1,231 @@
# SPEC-004 — MCP Gateway
## Scope
O MCP Gateway centraliza Catalog, Authorization, Routing, Execution, cache, timeout, retry, Observability and Response padronizada of tools MCP.
## Endpoints
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Health check. |
| `GET` | `/ready` | Readiness check. |
| `GET` | `/v1/tools` | Catalog of tools. |
| `GET` | `/v1/tools/{tool_name}` | Detalhe of the tool. |
| `POST` | `/v1/tools/{tool_name}/invoke` | Execution of tool. |
| `GET` | `/v1/servers` | Lista MCP servers. |
## ToolInvocation
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"tool_name": "consultar_fatura",
"arguments": {
"msisdn": "11999999999",
"invoice_id": "3000131180",
"session_id": "default:telecom_contas:session-001"
},
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
## ToolResult
```json
{
"tool_name": "consultar_fatura",
"ok": true,
"data": {
"invoice_id": "3000131180",
"valor_total": 249.90,
"vencimento": "2026-06-10",
"status": "ABERTA"
},
"cache": {
"hit": false,
"ttl_seconds": 300
},
"latency_ms": 140,
"metadata": {
"server": "telecom"
}
}
```
## mcp_servers.yaml
```yaml
servers:
telecom:
transport: http
url: http://telecom-mcp:8001/mcp
enabled: true
timeout_seconds: 30
retail:
transport: http
url: http://retail-mcp:8002/mcp
enabled: true
timeout_seconds: 30
```
## tools.yaml
```yaml
tools:
consultar_fatura:
server: telecom
enabled: true
idempotent: true
cache_ttl_seconds: 300
allowed_agents:
- telecom_contas
required_business_keys:
- customer_key
- contract_key
solicitar_devolucao:
server: retail
enabled: true
idempotent: false
requires_confirmation: true
allowed_agents:
- retail_orders
```
## mcp_parameter_mapping.yaml
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
## Authorization
```yaml
authorization:
default_policy: deny
agents:
telecom_contas:
allowed_tools:
- consultar_fatura
- consultar_pagamentos
- consultar_plano
```
## Cache
| Regra | value |
|---|---|
| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
| Aplicação | only tools idempotentes |
| Bypass | `metadata.cache_bypass=true` |
| TTL | `cache_ttl_seconds` |
| Escrita | No cachear operações mutáveis |
## Retry and Timeout
```yaml
execution:
default_timeout_seconds: 30
retry:
enabled: true
max_attempts: 2
backoff_ms: 250
circuit_breaker:
enabled: true
failure_threshold: 5
recovery_seconds: 60
```
## Events
| Evento | Description |
|---|---|
| `mcp.tool.requested` | Tool requisitada. |
| `mcp.tool.authorized` | Authorization aprovada. |
| `mcp.tool.denied` | Authorization negada. |
| `mcp.tool.started` | Execution iniciada. |
| `mcp.tool.completed` | Execution concluída. |
| `mcp.tool.failed` | Execution failed. |
| `mcp.cache.hit` | Cache hit. |
| `mcp.cache.miss` | Cache miss. |
## Metrics
| metric | Dimensões |
|---|---|
| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
| `mcp_tool_latency_ms` | tool, server |
| `mcp_tool_errors_total` | tool, server, error_type |
| `mcp_cache_hits_total` | tool |
| `mcp_cache_misses_total` | tool |
## Security
- Tools are negadas por Standard.
- Argumentos sensíveis are mascarados.
- Tools mutáveis exigem confirmação when configured.
- MCP servers No recebem payload bruto of canal.
- Credenciais of backend are mantidas nos MCP servers or secret store.
## 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
- [ ] Catalog of tools retorna tools habilitadas.
- [ ] ToolInvocation is validado before of the Execution.
- [ ] Authorization por Agent is aplicada.
- [ ] Parâmetros are derivados of the BusinessContext.
- [ ] Cache só is applied a tools idempotentes.
- [ ] Timeout/retry/circuit breaker are configuráveis.
- [ ] Events and Metrics are emitidos.
- [ ] Failures retornam ToolResult padronizado.
- [ ] MCP servers are substituíveis por Configuration.
- [ ] Tools críticas possuem Tests of Contract.
## 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. |
## Policy mínima of Operations
before forward a tool, The runtime must apply a Policy Optional of the backend em `config/tool_policies.yaml`. Os tipos canônicos are `read_only` and `transactional`; esta última can exigir confirmação booleana explícita and fields required. A ausência of the file No is Error and preserva os fields legados of `tools.yaml`. A Policy conversational No substitui Authentication, Authorization, idempotência nem atomicidade no MCP Server.

194
specs/en/SPEC-005-Guardrails.md Normal file
View File

@@ -0,0 +1,194 @@
# SPEC-005 — Guardrails
## Scope
Guardrails are Policies executadas sobre Input, Output, tool calls, RAG and responses finais. The platform suporta guardrails global, por Agent, por canal and por fase.
## Fases
| Fase | Input | Output |
|---|---|---|
| Input | `user_text`, `context` | `sanitized_input`, `GuardrailResult` |
| Tool | `ToolInvocation` | tool allowed/bloqueada |
| RAG | query/Context recuperado | Context aprovado/filtrado |
| Output | `response_text` | Response aprovada/sanitizada/bloqueada |
| Review | Response + evidências | Decision final |
## GuardrailResult
```json
{
"code": "PINJ",
"phase": "input",
"status": "blocked",
"severity": "high",
"score": 0.98,
"message": "Entrada bloqueada por política.",
"details": {
"matched_policy": "prompt_injection"
}
}
```
## Configuration Global
```yaml
input:
- code: MSK
enabled: true
mode: enforce
- code: VLOOP
enabled: true
mode: enforce
- code: PINJ
enabled: true
mode: enforce
output:
- code: REVPREC
enabled: true
mode: enforce
- code: DLEX_OUT
enabled: true
mode: enforce
- code: PINJ
enabled: true
mode: observe
```
## Configuration por Agent
```yaml
agents:
telecom_contas:
input:
- code: BILLING_INPUT_POLICY
enabled: true
mode: observe
output:
- code: BILLING_COMPLIANCE
enabled: true
mode: enforce
```
## Modos
| Modo | Comportamento |
|---|---|
| `enforce` | applies Block, máscara or alteração. |
| `observe` | Registra without bloquear. |
| `fail_open` | Em Error técnico, prossegue and emite NOC. |
| `fail_closed` | Em Error técnico, bloqueia. |
## Tipos
| Tipo | Implementation |
|---|---|
| Determinístico | Regex, listas, tamanho, structure, Rules. |
| LLM | Classificação semântica por profile. |
| Híbrido | Determinístico + LLM em casos ambíguos. |
## Profiles LLM
```yaml
profiles:
guardrail:
provider: oci_openai
model: openai.gpt-4.1
temperature: 0
max_tokens: 600
grl:
provider: oci_openai
model: openai.gpt-4.1
temperature: 0
max_tokens: 700
```
## Flow
```mermaid
flowchart TD
A[Input] --> B[Deterministic Guardrails]
B --> C{Blocked?}
C -- yes --> D[Safe Response]
C -- no --> E[LLM Guardrails]
E --> F{Approved?}
F -- no --> D
F -- yes --> G[Runtime]
```
## Events
| Evento | Description |
|---|---|
| `guardrail.started` | Execution iniciada. |
| `guardrail.completed` | Execution concluída. |
| `guardrail.blocked` | Conteúdo bloqueado. |
| `guardrail.masked` | Conteúdo mascarado. |
| `guardrail.failed` | Failure técnica. |
| `guardrail.observe` | Policy observacional registrada. |
## Códigos Base
| Código | Fase | Uso |
|---|---|---|
| `MSK` | input/output | Mascaramento. |
| `VLOOP` | input | Detecção of loop. |
| `PINJ` | input/output | Prompt injection. |
| `REVPREC` | output | Review of precisão. |
| `DLEX_OUT` | output | control of Data and linguagem na Output. |
| `RAGSEC` | rag/output | Security of Context recuperado. |
## Tests
| Test | objective |
|---|---|
| Unitário | validate guardrail isolado. |
| Config | validate YAML and schema. |
| integration | validate Execution no workflow. |
| Observability | validate Events and traces. |
| Negativo | validate Block. |
| Observe-only | validate No Block. |
## 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
- [ ] Guardrails global are carregados por YAML.
- [ ] Guardrails por Agent sobrescrevem or complementam global.
- [ ] GuardrailResult is gerado for each Execution.
- [ ] Modo enforce bloqueia when aplicável.
- [ ] Modo observe No bloqueia.
- [ ] Failures técnicas seguem Policy configured.
- [ ] Guardrails LLM usam profile dedicado.
- [ ] Events and Metrics are emitidos.
- [ ] Tests cobrem casos positivos and negativos.
- [ ] Output guardrails executam before of the Response final.
## 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. |

226
specs/en/SPEC-006-Evals.md Normal file
View File

@@ -0,0 +1,226 @@
# SPEC-006 — Evals
## Scope
The layer of Evals executa Evaluation online, Evaluation offline, regressão, Certification and publicação of Metrics. Ela padroniza Validation of Agents, prompts, tools, responses and guardrails.
## Components
| Componente | Responsibility |
|---|---|
| Online Judges | Evaluation during a Execution. |
| Offline Evaluator | Evaluation batch of conversas. |
| Dataset Runner | Execution of datasets versionados. |
| Regression Runner | Comparação between versions. |
| Certification Suite | Validation técnica and funcional. |
| Metrics Engine | Cálculo of Metrics. |
| Persistence | Persistence of runs and itens. |
| Exporter | Exportação TXT.GZ/JSON/HTML. |
| Publisher | Publicação of scores no Langfuse. |
## Flow Offline
```mermaid
flowchart TD
A[Start EvaluationRun] --> B[Collect Conversations]
B --> C[Normalize Items]
C --> D[Run Judges]
D --> E[Calculate Metrics]
E --> F[Persist Results]
F --> G[Export Reports]
G --> H[Publish Scores]
H --> I[Complete Run]
```
## EvaluationRun
```json
{
"run_id": "eval-20260619-001",
"agent_id": "telecom_contas",
"source": "langfuse",
"period_start": "2026-06-18T00:00:00Z",
"period_end": "2026-06-19T00:00:00Z",
"status": "running",
"limit": 500,
"metadata": {
"profile": "judge",
"dataset": "production-sample"
}
}
```
## EvaluationItem
```json
{
"conversation_id": "default:telecom_contas:session-001",
"trace_id": "trace-001",
"agent_id": "telecom_contas",
"input": "Quero consultar minha fatura",
"output": "Sua fatura está aberta...",
"evidence": {
"mcp_results": [],
"rag_context": ""
},
"scores": {
"quality": 0.86,
"groundedness": 0.78,
"safety": 1.0,
"resolution": 0.91
},
"findings": []
}
```
## Metrics
| metric | Description | Faixa |
|---|---|---|
| `quality` | Clareza, completude and utilidade. | 0–1 |
| `groundedness` | Aderência evidências MCP/RAG. | 0–1 |
| `safety` | compliance of Security. | 0–1 |
| `resolution` | Capacity of resolve a intent. | 0–1 |
| `tool_correctness` | Uso correct of tools. | 0–1 |
| `policy_compliance` | Aderência Rules of Domain. | 0–1 |
## Dataset
```yaml
dataset:
name: telecom_contas_billing
version: 1.0.0
items:
- id: billing-001
input: "Quero consultar minha fatura"
business_context:
customer_key: "11999999999"
contract_key: "3000131180"
expected:
route: billing_agent
tools:
- consultar_fatura
min_scores:
quality: 0.75
groundedness: 0.70
safety: 1.0
```
## Judges
```yaml
judges:
- name: response_quality
enabled: true
threshold: 0.7
profile: judge
- name: groundedness
enabled: true
threshold: 0.6
profile: judge
- name: safety
enabled: true
threshold: 1.0
profile: judge
```
## CLI
```bash
af-evaluator run \
--agent-id telecom_contas \
--source langfuse \
--period-start 2026-06-18T00:00:00Z \
--period-end 2026-06-19T00:00:00Z \
--limit 500
```
## API
| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/evaluation/runs` | Cria run. |
| `GET` | `/evaluation/runs/{run_id}` | Consulta run. |
| `GET` | `/evaluation/runs/{run_id}/items` | Lista itens. |
| `POST` | `/evaluation/datasets/{name}/run` | Executa dataset. |
| `GET` | `/health` | Health check. |
## Persistence
| table | Conteúdo |
|---|---|
| `EVAL_RUNS` | Runs executadas. |
| `EVAL_ITEMS` | Conversas avaliadas. |
| `EVAL_SCORES` | Scores por metric. |
| `EVAL_FINDINGS` | Achados. |
| `EVAL_EXPORTS` | files exportados. |
## Certification
A Certification Suite valida:
- endpoints of health;
- GatewayRequest;
- Routing;
- MCP tools;
- guardrails;
- judges;
- Memory;
- checkpoint;
- Langfuse/OTEL;
- datasets minimum;
- evidências JSON/HTML.
## Events
| Evento | Description |
|---|---|
| `eval.run.started` | Run iniciada. |
| `eval.item.completed` | Item avaliado. |
| `eval.run.completed` | Run concluída. |
| `eval.run.failed` | Run failed. |
| `eval.score.published` | Score publicado. |
## 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
- [ ] Evaluator executa runs por período/Agent.
- [ ] Langfuse is source suportada.
- [ ] Datasets are versionados.
- [ ] LLM Judges usam profile `judge`.
- [ ] Scores are persistidos.
- [ ] TXT.GZ/JSON/HTML are exportáveis.
- [ ] Scores Can be publicados no Langfuse.
- [ ] Certification Suite gera evidências.
- [ ] Metrics mínimas are padronizadas.
- [ ] Failures permitem retomada por checkpoint of run.
## 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. |

202
specs/en/SPEC-007-Observability.md Normal file
View File

@@ -0,0 +1,202 @@
# SPEC-007 — Observability
## Scope
Observability cobre logs, Metrics, traces, Events IC/NOC/GRL, Langfuse, OpenTelemetry, dashboards, Alerts and evidências operational.
## correlation
fields required:
```text
request_id
trace_id
session_id
conversation_key
tenant_id
agent_id
channel
message_id
route
intent
```
## Logs
Formato:
```json
{
"timestamp": "2026-06-19T12:00:00Z",
"level": "INFO",
"service": "agent-runtime",
"event": "runtime.route.selected",
"tenant_id": "default",
"agent_id": "telecom_contas",
"session_id": "default:telecom_contas:session-001",
"trace_id": "trace-001",
"route": "billing_agent",
"intent": "billing_invoice_explanation"
}
```
## Traces
```mermaid
flowchart TD
T[conversation trace] --> A[gateway.received]
T --> B[channel.normalized]
T --> C[runtime.started]
T --> D[guardrails.input]
T --> E[routing]
T --> F[agent.execution]
F --> G[mcp.tool]
F --> H[llm.generation]
T --> I[guardrails.output]
T --> J[judges]
T --> K[persist]
```
## Metrics
| metric | Dimensões |
|---|---|
| `requests_total` | service, tenant, agent, channel, status |
| `request_latency_ms` | service, route, intent |
| `active_sessions` | tenant, agent |
| `llm_tokens_total` | provider, model, profile |
| `llm_cost_estimated` | provider, model, tenant, agent |
| `mcp_tool_calls_total` | tool, server, status |
| `mcp_tool_latency_ms` | tool, server |
| `guardrail_blocks_total` | code, phase, agent |
| `judge_scores` | metric, agent, route |
| `errors_total` | service, component, error_type |
## Langfuse
Data registrados:
- trace of conversation;
- spans técnicos;
- generations LLM;
- prompts and responses when allowed;
- tokens;
- Costs;
- Latency;
- scores;
- metadata;
- erros.
## OpenTelemetry
Configuration:
```yaml
otel:
enabled: true
service_name: agent-runtime
exporter: otlp
endpoint: http://otel-collector:4317
```
## IC/NOC/GRL
| Família | Events |
|---|---|
| IC | `IC.GATEWAY_RECEIVED`, `IC.AGENT_STARTED`, `IC.AGENT_COMPLETED` |
| NOC | `NOC.RUNTIME_FAILED`, `NOC.MCP_TIMEOUT`, `NOC.LLM_FAILED` |
| GRL | `GRL.INPUT_BLOCKED`, `GRL.OUTPUT_BLOCKED`, `GRL.MASK_APPLIED` |
## Dashboards
| Dashboard | Conteúdo |
|---|---|
| Platform Overview | traffic, erros, Latency, Sessions. |
| Agent Runtime | rotas, intents, Memory, checkpoints. |
| LLM Usage | tokens, Cost, Latency, provider/model. |
| MCP Operations | Calls, erros, cache, Latency. |
| Guardrails | Blocks, observe-only, códigos. |
| Evals | scores, trends, regressões. |
| Channels | traffic por canal, erros, retries. |
## Alerts
| Alert | Condition |
|---|---|
| `GatewayHighErrorRate` | Erros 5xx above of the Limit. |
| `RuntimeLatencyHigh` | p95 above of the SLO. |
| `LLMProviderUnavailable` | Failures consecutive of provider. |
| `MCPToolTimeoutSpike` | increase of timeouts. |
| `GuardrailBlockSpike` | increase abnormal of Blocks. |
| `EvaluatorRunFailed` | run batch failed. |
| `CheckpointFailure` | Failure persistente em checkpoint. |
## Mascaramento
fields mascarados:
- tokens;
- API keys;
- senhas;
- secrets;
- CPF/CNPJ, when aplicável;
- telefone, when configured;
- payload bruto of canal;
- documentos sensíveis.
## Evidências
Relatórios of homologação Include:
- health checks;
- logs of Execution;
- traces Langfuse;
- Metrics;
- results of guardrails;
- results of judges;
- Calls MCP;
- Calls LLM;
- relatório of the evaluator;
- relatório of the certification suite.
## 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
- [ ] all os services emitem Structured logs.
- [ ] Trace correlaciona gateway, runtime, MCP, LLM, guardrails and judges.
- [ ] Langfuse recebe traces when enabled.
- [ ] OTEL exporta spans when enabled.
- [ ] Metrics mínimas are disponíveis.
- [ ] Dashboards are definidos.
- [ ] Alerts are definidos.
- [ ] Segredos and PII are mascarados.
- [ ] Evaluator consome Data observáveis.
- [ ] Certification Suite gera evidências.
## 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. |

233
specs/en/SPEC-008-Deployment.md Normal file
View File

@@ -0,0 +1,233 @@
# SPEC-008 — Deployment
## Scope
Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, Authentication OCI, health checks, rollback and Operations of the Components.
## Components Deployáveis
| Componente | Artefato |
|---|---|
| Agent Gateway | Docker image + Kubernetes Deployment |
| Channel Gateway | Docker image + Kubernetes Deployment |
| AI Gateway | Docker image + Kubernetes Deployment |
| MCP Gateway | Docker image + Kubernetes Deployment |
| Agent Backend | Docker image + Kubernetes Deployment |
| MCP Server | Docker image + Kubernetes Deployment |
| Evaluator API | Docker image + Kubernetes Deployment |
| Evaluator Batch | Kubernetes CronJob |
| Frontend Demo | Docker image Optional |
## Pipeline
```mermaid
flowchart LR
A[Commit] --> B[Lint]
B --> C[Type Check]
C --> D[Unit Tests]
D --> E[Contract Tests]
E --> F[Security Scan]
F --> G[Build Wheel]
G --> H[Build Images]
H --> I[Publish]
I --> J[Deploy Dev]
J --> K[Smoke Tests]
K --> L[Certification]
L --> M[Deploy HML/Prod]
```
## Stages
```yaml
stages:
- validate
- lint
- type_check
- unit_test
- contract_test
- security_scan
- build_package
- build_image
- publish
- deploy_dev
- smoke_test
- certification
- deploy_hml
- deploy_prod
```
## Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: agent-runtime
labels:
app: agent-runtime
component: runtime
spec:
replicas: 2
selector:
matchLabels:
app: agent-runtime
template:
metadata:
labels:
app: agent-runtime
spec:
serviceAccountName: agent-runtime-sa
containers:
- name: agent-runtime
image: registry/agent-runtime:1.0.0
ports:
- containerPort: 8000
envFrom:
- configMapRef:
name: agent-runtime-config
- secretRef:
name: agent-runtime-secrets
readinessProbe:
httpGet:
path: /ready
port: 8000
livenessProbe:
httpGet:
path: /health
port: 8000
```
## Service
```yaml
apiVersion: v1
kind: Service
metadata:
name: agent-runtime
spec:
selector:
app: agent-runtime
ports:
- port: 8000
targetPort: 8000
```
## OCI Authentication
| Ambiente | Modo |
|---|---|
| Local | `config_file` |
| Local with endpoint OpenAI-Compatible | API key |
| OCI Compute | `instance_principal` |
| OKE | `workload_identity` or `resource_principal` |
| Tests | `mock` |
## Variáveis
```env
LLM_PROVIDER=oci_sdk
OCI_AUTH_MODE=workload_identity
ENABLE_LANGFUSE=true
ENABLE_OTEL=true
SESSION_REPOSITORY_PROVIDER=autonomous
MEMORY_REPOSITORY_PROVIDER=autonomous
CHECKPOINT_REPOSITORY_PROVIDER=autonomous
```
## Secrets
| Secret | Uso |
|---|---|
| `LANGFUSE_PUBLIC_KEY` | Langfuse |
| `LANGFUSE_SECRET_KEY` | Langfuse |
| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
| `ADB_PASSWORD` | Autonomous Database |
| `MCP_BACKEND_TOKEN` | Integrações MCP |
| `OTEL_AUTH_TOKEN` | Exportador OTEL, if aplicável |
## Health Checks
| Endpoint | Uso |
|---|---|
| `/health` | Process vivo. |
| `/ready` | ready for traffic. |
| `/version` | Version of build. |
| `/debug/env` | Ambiente without segredos, when enabled. |
## Rollback
Itens considerados:
- tag of the imagem;
- Version of the pacote Python;
- Version of the schemas;
- Version of the YAMLs;
- migrations;
- datasets of eval;
- contracts;
- dashboards.
## Smoke Tests
```bash
curl -f http://agent-runtime:8000/health
curl -f http://agent-gateway:9000/health
curl -f http://mcp-gateway:8300/health
curl -f http://ai-gateway:9100/health
```
## Certification Stage
A pipeline executa:
- health checks;
- Contract GatewayRequest;
- Routing;
- MCP invoke;
- LLM mock/real conforme ambiente;
- guardrails;
- judges;
- Memory/checkpoint;
- relatório JSON/HTML.
## 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
- [ ] each app possui Dockerfile.
- [ ] each app possui manifest Kubernetes.
- [ ] CI executa lint, type check and Tests.
- [ ] Contract tests validam Main contracts.
- [ ] Security scan executa before of the publish.
- [ ] Secrets No are versionados.
- [ ] Workload Identity is configured em OKE.
- [ ] Health/readiness/liveness are ativos.
- [ ] Smoke tests rodam após deploy.
- [ ] Rollback is documentado.
## 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. |

197
specs/en/SPEC-009-Channel-Gateway.md Normal file
View File

@@ -0,0 +1,197 @@
# 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
```json
{
"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
```json
{
"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
```mermaid
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:
```text
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:
```http
X-Agent-Framework-Contract: gateway-request-v1
```
field alternativo:
```json
{
"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. |

333
specs/en/SPEC-010-Agent-Development.md Normal file
View File

@@ -0,0 +1,333 @@
# SPEC-010 — Agent Development
## Scope
Esta SPEC Defines o Standard for Creation of Agents usando templates, Configuration YAML, BusinessContext, MCP, guardrails, judges, RAG, Memory, Observability and evals.
## structure of the Template
```text
templates/agent_template_backend/
├── app/
│ ├── main.py
│ ├── state.py
│ ├── workflows/
│ │ └── agent_graph.py
│ ├── agents/
│ │ ├── runtime.py
│ │ └── domain_agent.py
│ └── examples/
├── config/
│ ├── agents.yaml
│ ├── routing.yaml
│ ├── tools.yaml
│ ├── mcp_servers.yaml
│ ├── mcp_parameter_mapping.yaml
│ ├── identity.yaml
│ ├── guardrails.yaml
│ ├── judges.yaml
│ ├── prompt_policy.yaml
│ └── agents/<agent_id>/
├── Dockerfile
├── requirements.txt
└── .env.example
```
## Responsibilities of the Framework
- LangGraph;
- Memory;
- checkpoint;
- Session;
- router;
- supervisor;
- guardrails;
- judges;
- telemetry;
- MCP integration;
- RAG genérico;
- cache;
- providers LLM;
- event bus.
## Responsibilities of the Agent
- prompts of Domain;
- Rules of negócio;
- schemas específicos;
- Decision of uso of evidências;
- handling of fields required;
- Messages of Domain;
- ICs of jornada;
- datasets of eval específicos.
## Registration of the Agent
```yaml
agents:
financeiro_agent:
enabled: true
description: "Agente financeiro"
profile: financeiro_agent
rag_namespace: financeiro
allowed_tools:
- consultar_fatura
- consultar_pagamentos
```
## Routing
```yaml
intents:
financeiro_consulta_fatura:
route: financeiro_agent
keywords:
- fatura
- boleto
- cobrança
mcp_tools:
- consultar_fatura
```
## Tool Mapping
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
## Classe of Agent
```python
class FinanceiroAgent(AgentRuntimeMixin):
name = "financeiro_agent"
def __init__(
self,
llm,
telemetry=None,
tool_router=None,
rag_service=None,
cache=None,
settings=None,
observer=None,
memory=None,
summary_memory=None,
):
self.llm = llm
self.telemetry = telemetry
self.tool_router = tool_router
self.rag_service = rag_service
self.cache = cache
self.settings = settings
self.observer = observer
self.memory = memory
self.summary_memory = summary_memory
async def run(self, state):
await self._emit_ic("IC.FINANCEIRO_AGENT_STARTED", state, {})
tool_context = await self._collect_mcp_context(state)
rag_context, rag_metadata = await self._retrieve_rag_context(state)
response = await self._invoke_llm_cached(
state,
"FinanceiroAgent",
[
{"role": "system", "content": "Você é um agente financeiro."},
{"role": "user", "content": state.get("sanitized_input") or state.get("user_text", "")},
],
)
await self._emit_ic("IC.FINANCEIRO_AGENT_COMPLETED", state, {})
return {
"response_text": response,
"mcp_results": tool_context,
"rag_metadata": rag_metadata,
}
```
## Ordem of Confiança of the Data
1. `tool_arguments`
2. `business_context`
3. `context`
4. `session.metadata`
5. `state`
6. extração complementar of the texto
## Prompt Policy
```yaml
prompt_policy:
system_prompt_path: prompts/system.md
response_style: concise
require_evidence: true
allow_tool_usage: true
```
## Guardrails por Agent
```yaml
input:
- code: FIN_INPUT_POLICY
enabled: true
mode: observe
output:
- code: FIN_OUTPUT_COMPLIANCE
enabled: true
mode: enforce
```
## Judges por Agent
```yaml
judges:
- name: response_quality
enabled: true
threshold: 0.75
- name: groundedness
enabled: true
threshold: 0.70
```
## Dataset of Eval
```yaml
dataset:
name: financeiro_agent_regression
version: 1.0.0
items:
- id: fin-001
input: "Quero consultar minha fatura"
business_context:
customer_key: "11999999999"
contract_key: "3000131180"
expected:
route: financeiro_agent
tools:
- consultar_fatura
min_scores:
quality: 0.75
groundedness: 0.70
```
## Contract Required for Agents transacionais
Ao create a Agent that Uses tools transacionais of the framework, o desenvolvedor No must create a motor paralelo of coleta/confirmação. must reutilizar `AgentRuntime` and garantir that o `AgentState` of the host mantenha o latch durável:
```python
active_transaction: dict[str, Any]
last_transaction: dict[str, Any]
```
during a transação ativa, parâmetros já coletados are preservados and new values are mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, a Response that satisfaz a Parameter pendente tem precedência sobre keywords genéricas. changes of intent explícitas and inequívocas continuam permitidas.
before publicar a new template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
## Contract MCP Multi-item
for a intent that opere sobre múltiplos itens homogêneos, o Agent **No must implement fan-out/loop of Calls MCP por conta própria**. must reutilizar The runtime and declarar o Contract natural of the tool. A Input Can be escalar or coleção; `type: array/list` No is Requirement for suporte multi-item.
Rules:
1. canonicalização of itens pertence ao MCP/pre-validation and can use `transaction_decision.resolved_arguments`;
2. confirmação transacional must representar o conjunto efetivo of itens;
3. a tool primária Must return `results[]` with dois or mais itens containing `success` or `ok` booleano por item;
4. for workflow-backed tools, a source preferencial is `workflow.output[tool_name].results`;
5. The runtime normaliza o agregado for `SUCCESS`, `PARTIAL_SUCCESS` or `FAILED`;
6. Failure em stage auxiliar posterior No can apagar evidência terminal of itens concluídos;
7. a `eligible=false` global em pre-validation encerra toda transação; for processing parcial, mantenha `eligible=true` when houver ao menos a item acionável and deixe a tool primária materializar o result por item.
Referência of Implementation: [`MCP Multi-item — Guia do Desenvolvedor`](../docs/MCP_MULTI_ITEM_DEVELOPER_GUIDE.md).
## Tests
| Test | Scope |
|---|---|
| Unitário | Classe of the Agent. |
| Routing | Intent and rota. |
| MCP Mapping | BusinessContext for argumentos. |
| Guardrails | Input and Output. |
| Judges | Scores minimum. |
| Runtime | Execution completa. |
| Memory | continuity of conversation. |
| Checkpoint | Resume/replay. |
| Observability | Trace and Events. |
| Certification | Evidências finais. |
## Definition of Done
- Agent registrado;
- rota configured;
- tools declaradas;
- mapping definido;
- prompts versionados;
- guardrails configurados;
- judges configurados;
- dataset criado;
- Tests executados;
- traces gerados;
- certification suite aprovada;
- documentation of the Agent atualizada.
## Anti-patterns
- Agent criando Session;
- Agent abrindo SSE;
- Agent compilando LangGraph;
- Agent chamando system External diretamente;
- prompt hardcoded without Policy;
- lógica genérica duplicada no Agent;
- payload bruto of canal inside of the Agent;
- ausência of dataset of eval.
## 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
- [ ] new Agent is criado without alterar core of the framework.
- [ ] if houver transações multi-turno, `AgentState` declara `active_transaction` and `last_transaction`.
- [ ] Configuration ocorre por YAML and `.env`.
- [ ] Agent Uses BusinessContext.
- [ ] Agent acessa MCP por router/gateway.
- [ ] Casos multi-item usam o Contract natural of the Operations (escalar or coleção) + result por item, without loop MCP of negócio inside of the Agent.
- [ ] Agent No conhece payload bruto of canal.
- [ ] Guardrails and judges are configurados.
- [ ] Dataset of eval existe.
- [ ] Tests minimum executam.
- [ ] Trace completo is gerado.
- [ ] Definition of Done is atendida.
## 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. |

347
specs/en/SPEC-011-Governance-Model.md Normal file
View File

@@ -0,0 +1,347 @@
# SPEC-011 — Governance Model
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Governance is o conjunto of papéis, Responsibilities, controles, aprovações, evidências and processos that Allows that a Agent Platform OCI seja usada por múltiplos times without perder Standardization, Security, rastreabilidade and Capacity of evolução.
A Governance No substitui a engenharia. Ela Defines como a engenharia evolui of forma controlada.
Em a plataforma of Agents, Governance cobre:
- quem can create Agents;
- quem can alterar prompts;
- quem can liberar MCP tools;
- quem aprova changes of guardrails;
- quem aprova modelos;
- quem aprova datasets;
- quem promove for Production;
- quais evidências are obrigatórias;
- como auditar Decisions of the plataforma.
# 2. Problem addressed
without Governance, each time tende a create Agents of forma diferente.
Problemas comuns:
- prompts without versionamento;
- MCP tools without owner;
- datasets ausentes;
- Agents without Evaluation;
- Production without certification;
- changes of Model without rastreabilidade;
- guardrails duplicados;
- Rules of negócio inside of the runtime;
- uso diferente of the plataforma por each fornecedor;
- dificuldade of maintenance.
A Governance cria Model único of adoção.
# 3. Domínios of Governance
| Domain | Scope |
| --- | --- |
| Platform Governance | Framework, Runtime, Gateways, Evaluator, Certification Suite. |
| Agent Governance | Agents, prompts, Rules of negócio, datasets and configs. |
| Model Governance | LLM profiles, providers, fallback, Cost and uso. |
| MCP Governance | Tools, MCP servers, owners, SLAs, Authorization and contracts. |
| Data Governance | BusinessContext, RAG, datasets, Memory and retenção. |
| Security Governance | Identity, Authorization, secrets, auditoria and PII. |
| Operational Governance | Deploy, monitoramento, Alerts, SLOs and incidents. |
| Evaluation Governance | Judges, evaluator, certification and Metrics. |
# 4. Model of ownership
## 4.1. Platform Team
Responsible for:
- Agent Framework;
- Agent Runtime;
- Agent Gateway;
- Channel Gateway;
- AI Gateway;
- MCP Gateway;
- Evaluator;
- Certification Suite;
- contracts canônicos;
- documentation of the plataforma;
- templates oficiais.
## 4.2. Domain Team
Responsible for:
- comportamento of the Agent;
- prompts;
- Rules of negócio;
- datasets;
- Configuration específicas;
- Validation funcional;
- criteria of success.
## 4.3. Integration Team
Responsible for:
- MCP servers;
- APIs external;
- SLAs of tools;
- contracts of integration;
- credenciais of backend;
- Availability of sistemas external.
## 4.4. SRE / DevOps
Responsible for:
- CI/CD;
- deploy;
- Observability;
- Alerts;
- Capacity;
- SLOs;
- runbooks;
- rollback.
## 4.5. Security / Architecture
Responsible for:
- Security;
- Architecture;
- policies;
- Workload Identity;
- secrets;
- Review of Risk;
- approval of Exceptions.
# 5. RACI
| activity | Platform | Domain | Integration | SRE | Security |
| --- | --- | --- | --- | --- | --- |
| Framework change | R/A | C | I | C | C |
| Runtime change | R/A | C | I | C | C |
| New agent | C | R/A | C | I | I |
| New MCP tool | C | C | R/A | I | C |
| Prompt change | I | R/A | I | I | C |
| Guardrail change | R | C | I | I | A |
| Model profile change | R | C | I | I | C |
| Production deploy | I | C | C | R/A | C |
| Security review | I | C | C | C | R/A |
| Certification | R/A | C | C | I | I |
# 6. Governance of Agents
Todo Agent must possuir:
```yaml
agent:
id: telecom_contas
owner: billing_team
technical_owner: ai_platform_team
business_objective: "Atendimento sobre faturas, pagamentos e cobranças"
status: active
version: 1.0.0
```
artifacts required:
- `agents.yaml`;
- `routing.yaml`;
- `prompt_policy.yaml`;
- `guardrails.yaml`;
- `judges.yaml`;
- `tools.yaml`;
- `mcp_parameter_mapping.yaml`;
- dataset of regressão;
- Tests;
- evidências of evaluator;
- evidências of certification.
# 7. Governance of prompts
Prompts must be versionados and rastreáveis.
```yaml
prompt:
name: billing_system_prompt
version: 1.3.0
owner: billing_team
reviewed_at: 2026-06-19
status: approved
```
changes of prompt exigem:
1. Review of the domain owner;
2. Execution of dataset;
3. evaluator;
4. comparação contra baseline;
5. Registration of the Version.
# 8. Governance of guardrails
Guardrails global belong à plataforma/Security.
Guardrails por Agent belong ao Domain, mas precisam seguir o Contract of the plataforma.
```yaml
guardrail:
code: REVPREC
version: 2.0.0
owner: platform_security
phase: output
mode: enforce
```
changes em guardrails `enforce` exigem certification.
# 9. Governance of judges
Judges must ter objective, metric, threshold and owner.
```yaml
judge:
name: groundedness
version: 1.1.0
threshold: 0.70
owner: platform_quality
```
changes of threshold exigem reexecução of the evaluator.
# 10. Governance of modelos
Agents No referenciam Model diretamente.
O Model is resolvido por profile.
```yaml
profiles:
judge:
provider: oci_openai
model: openai.gpt-4.1
temperature: 0
```
changes of Model exigem:
- Validation of Cost;
- evaluator;
- Validation of quality;
- Validation of Latency;
- Update of release notes.
# 11. Governance of MCP
each tool must ter owner, SLA, timeout and Contract.
```yaml
tool:
name: consultar_fatura
version: 1.0.0
owner: billing_platform
sla: p95_2s
timeout_seconds: 30
idempotent: true
```
Tools mutáveis exigem Policy of confirmação.
# 12. Governance of datasets
Datasets are ativos of quality.
```yaml
dataset:
name: telecom_contas_regression
version: 1.0.0
owner: billing_team
```
Datasets must contain:
- Input;
- BusinessContext;
- rota expected;
- tools esperadas;
- criteria minimum;
- casos negativos;
- casos of Security.
# 13. Process of approval
```mermaid
flowchart LR
Dev[Development] --> Tests[Tests]
Tests --> Eval[Evaluator]
Eval --> Cert[Certification]
Cert --> Sec[Security Review]
Sec --> Arch[Architecture Approval]
Arch --> HML[Homologation]
HML --> PROD[Production]
```
# 14. Evidências obrigatórias
- relatório of Tests;
- relatório evaluator;
- relatório certification;
- trace Langfuse;
- logs and Metrics;
- checklist of Security;
- release notes;
- Version of artifacts.
# 15. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Prompt without owner | Dificulta maintenance and approval. | Definir owner no metadata. |
| Tool without SLA | Operations without expectativa of Response. | Registrar SLA em tools.yaml. |
| Dataset ausente | without regressão objetiva. | create dataset minimum. |
| Guardrail hardcoded | Governance outside of the YAML. | Mover for config. |
| Model definido no Agent | Quebra Governance of modelos. | use AI Gateway profiles. |
# 16. Acceptance criteria
- [ ] each Agent possui owner funcional and técnico.
- [ ] Prompts are versionados.
- [ ] Tools MCP possuem owner, SLA and Version.
- [ ] Guardrails possuem owner and modo.
- [ ] Judges possuem threshold and Version.
- [ ] Datasets are versionados.
- [ ] Evaluator roda por Agent.
- [ ] Certification aprova before Production.
- [ ] Release possui evidências.
- [ ] Exceptions are documentadas.

312
specs/en/SPEC-012-Canonical-Contracts.md Normal file
View File

@@ -0,0 +1,312 @@
# SPEC-012 — Canonical Contracts
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
contracts canônicos are structures padronizadas usadas for desacoplar canais, gateways, runtime, Agents, tools, LLMs, evaluator and Observability.
The platform Uses contracts to ensure that Components independentes possam evoluir without quebrar uns aos outros.
# 2. Problem addressed
without contracts:
- each canal envia payload diferente;
- Agents passam a conhecer WhatsApp, Voice, Teams or CRM;
- MCP tools recebem parâmetros inconsistentes;
- LLM calls ficam acopladas ao provider;
- evaluator No consegue comparar responses;
- Observability fica fragmentada.
with contracts:
```text
Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
```
# 3. Catalog of contracts
| Contract | Uso |
| --- | --- |
| GatewayRequest | Input canônica of the plataforma. |
| ChannelResponse | Response canônica ao canal. |
| BusinessContext | Identity canônica of negócio. |
| AgentState | State Internal of the runtime. |
| Session | Session técnica/conversational. |
| Checkpoint | Persistence of State LangGraph. |
| ToolInvocation | Call canônica of tool MCP. |
| ToolResult | Response canônica of tool MCP. |
| LLMRequest | Call canônica ao AI Gateway. |
| LLMResponse | Response canônica of the AI Gateway. |
| EvaluationRun | Execution of the evaluator. |
| EvaluationResult | result of Evaluation. |
| CertificationResult | result of Certification. |
| EventEnvelope | Envelope of Events IC/NOC/GRL. |
# 4. GatewayRequest
## 4.1. Uso
Used por Channel Gateway and Agent Gateway for enviar Messages ao Runtime.
```json
{
"channel": "web",
"tenant_id": "default",
"agent_id": "telecom_contas",
"payload": {
"message": "Quero consultar minha fatura",
"session_id": "session-001",
"user_id": "user-001",
"message_id": "msg-001",
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"interaction_key": "301953872",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001",
"contract_version": "gateway-request-v1"
}
}
}
```
## 4.2. fields required
- `channel`;
- `payload.message`;
- `payload.session_id`;
- `payload.message_id`;
- `tenant_id` quando multi-tenant;
- `agent_id` quando não houver roteamento global.
# 5. ChannelResponse
```json
{
"channel": "web",
"session_id": "default:telecom_contas:session-001",
"text": "Resposta final do agente.",
"metadata": {
"tenant_id": "default",
"agent_id": "telecom_contas",
"route": "billing_agent",
"intent": "billing_invoice_explanation",
"guardrails": [],
"judges": []
}
}
```
# 6. BusinessContext
## 6.1. Uso
BusinessContext transporta Identity of negócio without acoplar The platform ao formato of each canal.
```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
```
## 6.2. Mapeamento for MCP
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
# 7. AgentState
```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
business_context: dict
mcp_tools: list[str]
mcp_results: list[dict]
rag_context: str
guardrails: list[dict]
judges: list[dict]
```
# 8. ToolInvocation
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"tool_name": "consultar_fatura",
"arguments": {
"msisdn": "11999999999",
"invoice_id": "3000131180"
},
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180"
},
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
# 9. ToolResult
```json
{
"tool_name": "consultar_fatura",
"ok": true,
"data": {
"invoice_id": "3000131180",
"valor_total": 249.90,
"status": "ABERTA"
},
"cache": {
"hit": false,
"ttl_seconds": 300
},
"latency_ms": 140
}
```
# 10. LLMRequest
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"profile": "judge",
"operation": "judge.response_quality",
"messages": [
{"role": "system", "content": "Você é um avaliador."},
{"role": "user", "content": "Avalie a resposta."}
],
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
# 11. LLMResponse
```json
{
"provider": "oci_openai",
"model": "openai.gpt-4.1",
"profile": "judge",
"content": "Resultado",
"usage": {
"input_tokens": 1200,
"output_tokens": 300,
"total_tokens": 1500
},
"latency_ms": 820
}
```
# 12. EvaluationRun
```json
{
"run_id": "eval-001",
"agent_id": "telecom_contas",
"source": "langfuse",
"period_start": "2026-06-18T00:00:00Z",
"period_end": "2026-06-19T00:00:00Z",
"status": "running"
}
```
# 13. EventEnvelope
```json
{
"event_type": "IC.AGENT_COMPLETED",
"timestamp": "2026-06-19T12:00:00Z",
"tenant_id": "default",
"agent_id": "telecom_contas",
"session_id": "session-001",
"trace_id": "trace-001",
"payload": {}
}
```
# 14. Rules of evolução
- fields new must be optional;
- fields required No Can be removidos inside of the mesma major;
- change semântica exige new Version;
- contracts are versionados independentemente.
# 15. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Payload bruto in the runtime | Acopla canais ao core. | use GatewayRequest. |
| Tool recebendo BusinessContext bruto without mapping | Quebra Contract of the tool. | use mcp_parameter_mapping.yaml. |
| LLM direto no Agent | Quebra AI Gateway. | use LLMRequest/profile. |
| fields without Version | Dificulta migração. | Declarar contract_version. |
# 16. Acceptance criteria
- [ ] GatewayRequest documentado and versionado.
- [ ] ChannelResponse documentado and versionado.
- [ ] BusinessContext Used por canais and MCP.
- [ ] ToolInvocation and ToolResult padronizados.
- [ ] LLMRequest and LLMResponse padronizados.
- [ ] EvaluationRun and EvaluationResult padronizados.
- [ ] EventEnvelope Used for IC/NOC/GRL.
- [ ] contracts possuem Rules of evolução.

175
specs/en/SPEC-013-Versioning-and-Compatibility-Model.md Normal file
View File

@@ -0,0 +1,175 @@
# SPEC-013 — Versioning and Compatibility Model
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Versionamento Defines como The platform evolui without quebrar projetos existing. compatibility Defines quais versions of framework, runtime, gateways, contracts, templates, prompts, tools and evaluator can operar juntas.
# 2. Problem addressed
without Model of versionamento:
- a change em GatewayRequest quebra canais;
- a change em MCP tool quebra Agents;
- a prompt alterado muda comportamento without rastreabilidade;
- evaluator muda score without History;
- templates ficam incompatíveis with runtime;
- Production Uses imagem `latest` without control.
# 3. Semantic Versioning
Formato:
```text
MAJOR.MINOR.PATCH
```
Rules:
| Parte | Significado |
| --- | --- |
| MAJOR | change incompatível. |
| MINOR | new Capacity compatível. |
| PATCH | Correction without change of Contract. |
# 4. artifacts versionados
| Artefato | Model |
| --- | --- |
| agent_framework | SemVer |
| agent_runtime | SemVer alinhado ao framework |
| agent_gateway | SemVer + Docker tag |
| channel_gateway | SemVer + Docker tag |
| ai_gateway | SemVer + Docker tag |
| mcp_gateway | SemVer + Docker tag |
| templates | Version of the plataforma |
| contracts | contract-name-vN |
| prompts | SemVer |
| datasets | SemVer |
| guardrails | SemVer por código |
| judges | SemVer por judge |
| mcp_tools | SemVer por tool |
| evaluator | SemVer |
| certification_suite | SemVer + ruleset version |
# 5. Contract versioning
Examples:
```text
gateway-request-v1
business-context-v1
tool-invocation-v1
llm-request-v1
```
allowed na mesma Version major:
- adicionar fields optional;
- adicionar metadata;
- adicionar enum documentado.
No allowed:
- remover field Required;
- mudar tipo;
- mudar significado;
- alterar regra obrigatória.
# 6. Compatibility Matrix
```yaml
compatibility:
- framework: "1.4.x"
runtime: "1.4.x"
agent_gateway: "1.4.x"
supported: true
- framework: "1.4.x"
runtime: "2.0.x"
supported: false
```
# 7. Policy of depreciação
Ciclo:
```text
Active → Deprecated → Retired
```
Período recommended:
```text
12 meses
```
# 8. Policy of migração
changes major exigem:
- migration guide;
- compatibility matrix;
- rollback strategy;
- certification;
- evaluator;
- release notes.
# 9. Estratégia of rollback
Rollback must considerar:
- imagem Docker;
- Version of the pacote;
- Version of the YAMLs;
- Version of the Contract;
- migration of banco;
- dataset;
- prompts.
# 10. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| use latest em Production | Deploy No reprodutível. | use tag explícita. |
| Mudar prompt without Version | without rastreabilidade. | Versionar prompt. |
| Adicionar field Required em Contract v1 | Quebra clientes. | create v2. |
| Atualizar evaluator without baseline | Scores No comparáveis. | Registrar Version and metodologia. |
# 11. Acceptance criteria
- [ ] all os Components têm Version.
- [ ] contracts têm Version independente.
- [ ] Matriz of compatibility publicada.
- [ ] Release notes publicadas.
- [ ] Migrações major possuem guide.
- [ ] Rollback definido.
- [ ] Prompts and datasets versionados.
- [ ] Evaluator and certification registram Version.

248
specs/en/SPEC-014-Templates-and-Agent-Creation-Model.md Normal file
View File

@@ -0,0 +1,248 @@
# SPEC-014 — Templates and Agent Creation Model
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Templates are scaffolds oficiais for create Agents, MCP servers and backends compatíveis with a Agent Platform OCI.
Eles aceleram o início of a projeto, mas No substituem o framework. O template contains a structure mínima of aplicação and os pontos of extensão esperados.
# 2. Problem addressed
without template:
- each squad cria structure diferente;
- imports and configs variam;
- MCP mapping is esquecido;
- datasets No are criados;
- guardrails and judges ficam ausentes;
- deploy No segue Standard;
- onboarding demora.
# 3. Templates oficiais
| Template | Uso |
| --- | --- |
| backend | Creation of Agents with runtime. |
| agent_template_backend_day_zero | Bootstrap acelerado with Examples. |
| mcp_server | Creation of MCP server. |
| channel_adapter | Adapter of canal when aplicável. |
# 4. structure Standard of Agent
```text
my_agent/
├── app/
│ ├── main.py
│ ├── state.py
│ ├── workflows/
│ │ └── agent_graph.py
│ └── agents/
│ └── my_agent.py
├── config/
│ ├── agents.yaml
│ ├── routing.yaml
│ ├── tools.yaml
│ ├── mcp_servers.yaml
│ ├── mcp_parameter_mapping.yaml
│ ├── guardrails.yaml
│ ├── judges.yaml
│ └── llm_profiles.yaml
├── prompts/
├── datasets/
├── tests/
├── Dockerfile
└── README.md
```
# 5. O that fica in the framework
- LangGraph runtime;
- Session;
- Memory;
- checkpoint;
- guardrails genéricos;
- judges genéricos;
- MCP client/router;
- RAG genérico;
- telemetry;
- providers;
- event bus.
# 6. O that fica no Agent
- prompts;
- Rules of negócio;
- intents;
- tools específicas;
- datasets;
- Tests;
- guardrails of Domain;
- judges of Domain.
# 7. step a step for create Agent of the zero
## step 1 — Copiar template
```bash
cp -R templates/agent_template_backend financeiro_agent
cd financeiro_agent
```
## step 2 — Definir Scope
```text
Agente: financeiro_agent
Objetivo: responder dúvidas sobre faturas, pagamentos e cobranças.
Fora de escopo: vendas, cancelamento e suporte técnico.
```
## step 3 — Registrar Agent
```yaml
agents:
financeiro_agent:
enabled: true
description: "Agente financeiro"
rag_namespace: financeiro
allowed_tools:
- consultar_fatura
- consultar_pagamentos
```
## step 4 — Configurar rotas
```yaml
intents:
financeiro_consulta_fatura:
route: financeiro_agent
keywords:
- fatura
- boleto
- cobrança
mcp_tools:
- consultar_fatura
```
## step 5 — Configurar tools
```yaml
tools:
consultar_fatura:
server: telecom
enabled: true
idempotent: true
cache_ttl_seconds: 300
```
## step 6 — Mapear BusinessContext
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
session_key: session_id
```
## step 7 — create prompt
```text
Você é um agente financeiro.
Use MCP como fonte transacional.
Use RAG para políticas e procedimentos.
Não invente valores, datas ou status.
```
## step 8 — implement Agent
```python
class FinanceiroAgent(AgentRuntimeMixin):
name = "financeiro_agent"
async def run(self, state):
mcp = await self._collect_mcp_context(state)
rag, rag_metadata = await self._retrieve_rag_context(state)
answer = await self._invoke_llm_cached(
state,
"FinanceiroAgent",
[
{"role": "system", "content": "Você é um agente financeiro."},
{"role": "user", "content": state.get("sanitized_input") or ""},
],
)
return {"response_text": answer, "mcp_results": mcp, "rag_metadata": rag_metadata}
```
## step 9 — create dataset
```yaml
dataset:
name: financeiro_agent_regression
version: 1.0.0
items:
- id: fin-001
input: "Quero consultar minha fatura"
expected:
route: financeiro_agent
tools:
- consultar_fatura
```
## step 10 — Testar
```bash
pytest
af-evaluator run --agent-id financeiro_agent
af-certification run --agent-id financeiro_agent
```
# 8. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Alterar o core for regra of Domain | Dificulta reuso. | create Agent/config. |
| Esquecer dataset | without regressão. | create dataset minimum. |
| Tool without mapping | Argumentos ausentes. | Configurar mcp_parameter_mapping.yaml. |
| Prompt hardcoded | without Governance. | use prompt_policy/prompts. |
# 9. Acceptance criteria
- [ ] Template Used como base.
- [ ] Agent registrado.
- [ ] Rotas configuradas.
- [ ] Tools configuradas.
- [ ] MCP mapping configured.
- [ ] Prompt criado.
- [ ] Dataset criado.
- [ ] Tests executados.
- [ ] Evaluator executado.
- [ ] Certification aprovada.

168
specs/en/SPEC-015-Adoption-and-Eligibility-Criteria.md Normal file
View File

@@ -0,0 +1,168 @@
# SPEC-015 — Adoption and Eligibility Criteria
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
criteria of adoção definem when a projeto must use a Agent Platform OCI and quais Requirements minimum precisa atender for entrar em Development, homologação and Production.
# 2. Problem addressed
without criteria claros:
- qualquer caso simples vira Agent;
- projetos without owner entram on the platform;
- canais entram without Contract;
- Agents entram without dataset;
- Production ocorre without evaluator;
- Operations fica without dashboard/Alert.
# 3. Casos indicados
| Caso | Example |
| --- | --- |
| Agents conversational | Atendimento, suporte, backoffice. |
| Multiagentes | Handoff between domínios. |
| Agents with tools | Consulta/ação em sistemas. |
| Agents with RAG | Uso of documentos and Policies. |
| Ambientes regulados | Necessidade of Governance and auditoria. |
| Canais corporativos | Web, WhatsApp, Voice, URA, CRM. |
# 4. Casos No indicados
| Caso | Motivo |
| --- | --- |
| CRUD simples | API REST without IA. |
| ETL batch | Pipeline of Data. |
| Job agendado simples | without interação. |
| service utilitário | Validation/formatação simples. |
| integration without Decision | Proxy API without raciocínio. |
# 5. criteria of Input of negócio
before iniciar:
- business owner;
- technical owner;
- objective;
- Scope;
- outside of Scope;
- canais;
- sistemas;
- documentos;
- criteria of success;
- Risks.
# 6. criteria of Architecture
required:
- GatewayRequest;
- ChannelResponse;
- BusinessContext;
- health/readiness;
- logs;
- traces;
- dataset;
- evaluator;
- certification.
# 7. criteria of Security
required:
- Authentication;
- Authorization;
- secrets external;
- máscara of PII;
- auditoria;
- Review of Risk.
# 8. criteria of quality
required:
- Tests unitários;
- Tests of integration;
- dataset;
- evaluator;
- thresholds;
- certification.
# 9. criteria of Operations
required:
- Metrics;
- dashboards;
- Alerts;
- runbook;
- rollback;
- SLO.
# 10. Process of exceção
Exceptions permitidas:
- without RAG;
- without MCP;
- without Memory;
- without handoff;
- without canal External.
Toda exceção Must record:
```yaml
exception:
reason: "Agente não usa documentos"
approved_by: architecture
expires_at: 2026-12-31
```
# 11. Checklist of adoção
- [ ] Business owner definido.
- [ ] Technical owner definido.
- [ ] Scope definido.
- [ ] Casos outside of Scope definidos.
- [ ] GatewayRequest definido.
- [ ] BusinessContext definido.
- [ ] Security definida.
- [ ] Dataset criado.
- [ ] Evaluator configured.
- [ ] Certification planejada.
- [ ] Observability planejada.
# 12. Acceptance criteria
- [ ] Projeto elegível for plataforma.
- [ ] Requirements minimum atendidos.
- [ ] Exceptions documentadas.
- [ ] Plano of homologação definido.
- [ ] criteria of Production definidos.

227
specs/en/SPEC-016-Agent-Development-Lifecycle.md Normal file
View File

@@ -0,0 +1,227 @@
# SPEC-016 — Agent Development Lifecycle
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
O ciclo of vida of Development of Agents Defines as stages desde a discovery of the caso of uso até a Operations em Production.
Ele organiza trabalho of produto, Architecture, engenharia, Security, Evaluation and Operations.
# 2. Flow of the ciclo of vida
```mermaid
flowchart LR
D[Discovery] --> S[Scope]
S --> AD[Agent Design]
AD --> PD[Prompt Design]
PD --> MD[MCP Design]
MD --> RD[RAG Design]
RD --> I[Implementation]
I --> T[Testing]
T --> E[Evaluation]
E --> C[Certification]
C --> H[Homologation]
H --> P[Production]
```
# 3. stage 1 — Discovery
objective:
- entender problema;
- identificar users;
- mapear canais;
- mapear sistemas;
- mapear documentos;
- mapear Risks.
Output:
```yaml
discovery:
business_problem: ""
users: []
channels: []
systems: []
documents: []
risks: []
```
# 4. stage 2 — Scope Definition
Definir:
- o that o Agent does;
- o that No does;
- intenções;
- actions permitidas;
- Limits;
- criteria of success.
# 5. stage 3 — Agent Design
Desenhar:
- agent_id;
- rotas;
- intents;
- BusinessContext;
- tools;
- RAG namespaces;
- Memory;
- handoff.
# 6. stage 4 — Prompt Design
create:
- system prompt;
- prompt policy;
- instruções of Domain;
- Examples;
- restrições;
- formato of Response.
# 7. stage 5 — MCP Design
Definir:
- tools;
- parâmetros;
- owner;
- SLA;
- timeout;
- retry;
- cache;
- Operations mutável or idempotente.
# 8. stage 6 — RAG Design
Definir:
- documentos;
- namespace;
- ingestão;
- chunking;
- embeddings;
- Update;
- criteria of relevância.
# 9. stage 7 — Implementation
implement:
- classe of the Agent;
- configs;
- prompts;
- datasets;
- tests;
- Observability específica.
# 10. stage 8 — Testing
Tests minimum:
- unit;
- integration;
- contract;
- MCP;
- RAG;
- guardrails;
- judges;
- runtime;
- channel.
# 11. stage 9 — Evaluation
Executar:
```bash
af-evaluator run --agent-id <agent_id> --dataset <dataset>
```
Assess:
- quality;
- groundedness;
- safety;
- tool correctness;
- route accuracy.
# 12. stage 10 — Certification
Executar:
```bash
af-certification run --agent-id <agent_id>
```
# 13. stage 11 — Homologation
validate with:
- negócio;
- Architecture;
- Security;
- Operations;
- integration.
# 14. stage 12 — Production
Requirements:
- deploy aprovado;
- Alerts ativos;
- dashboards ativos;
- rollback validado;
- runbook disponível.
# 15. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Começar by the código | Scope mal definido. | Iniciar por discovery/scope. |
| create tool before of the intent | Tool without Context. | Definir Flow primeiro. |
| Dataset after of the Production | without regressão. | create dataset before of the homologação. |
| Prompt without criteria | Response inconsistente. | Definir prompt policy. |
# 16. Acceptance criteria
- [ ] Discovery concluído.
- [ ] Scope aprovado.
- [ ] Agent design documentado.
- [ ] Prompts criados.
- [ ] MCP design aprovado.
- [ ] RAG design aprovado when aplicável.
- [ ] Implementation concluída.
- [ ] Tests executados.
- [ ] Evaluator aprovado.
- [ ] Certification aprovada.
- [ ] Homologação concluída.
- [ ] Production monitorada.

144
specs/en/SPEC-017-Release-Management-and-CICD.md Normal file
View File

@@ -0,0 +1,144 @@
# SPEC-017 — Release Management and CI/CD
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Release management Defines como changes entram on the platform, are testadas, empacotadas, publicadas, promovidas and auditadas.
CI/CD automatiza Validations and reduz Risk operacional.
# 2. Pipeline Standard
```mermaid
flowchart LR
C[Commit] --> L[Lint]
L --> TC[Type Check]
TC --> UT[Unit Tests]
UT --> IT[Integration Tests]
IT --> CT[Contract Tests]
CT --> SS[Security Scan]
SS --> B[Build]
B --> P[Publish]
P --> DD[Deploy Dev]
DD --> ST[Smoke Tests]
ST --> CERT[Certification]
CERT --> HML[Deploy HML]
HML --> PROD[Deploy Prod]
```
# 3. Stages
| Stage | Função |
| --- | --- |
| validate | Validation inicial of structure. |
| lint | Estilo and erros simples. |
| type_check | Tipos and contracts Python. |
| unit_test | Tests unitários. |
| integration_test | Integrações locais. |
| contract_test | contracts JSON/YAML/API. |
| security_scan | Dependências, secrets and imagens. |
| build_package | Wheel/package. |
| build_image | Imagem Docker. |
| publish | Registry/artifacts. |
| deploy_dev | Ambiente dev. |
| smoke_test | Health and Calls básicas. |
| certification | Certification Suite. |
| deploy_hml | Homologação. |
| deploy_prod | Production. |
# 4. artifacts of release
- imagem Docker;
- pacote Python;
- release notes;
- matriz of compatibility;
- migration guide when necessário;
- evaluator report;
- certification report;
- SBOM when aplicável;
- evidência of scan;
- changelog.
# 5. Example of pipeline
```yaml
stages:
- lint
- test
- contract
- security
- build
- publish
- deploy
- certification
```
# 6. Gates
| Gate | when applies |
| --- | --- |
| Architecture Gate | changes estruturais, contracts, runtime, gateways. |
| Security Gate | Segredos, Identity, Data sensíveis, MCP External. |
| Quality Gate | Tests, evaluator, certification. |
| Operations Gate | Dashboards, Alerts, runbook, rollback. |
# 7. Estratégia of rollback
Rollback must restaurar:
- imagem previous;
- Configuration previous;
- Contract previous;
- prompt previous;
- dataset previous when necessário;
- migration of banco when aplicável.
# 8. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Deploy without certification | Risk funcional. | Rodar certification no pipeline. |
| without release notes | without rastreabilidade. | Publicar release notes. |
| without contract tests | Quebra integration. | Adicionar Tests of Contract. |
| without rollback | Risk operacional. | Definir estratégia of rollback. |
# 9. Acceptance criteria
- [ ] Pipeline executa lint, type check and Tests.
- [ ] Contract tests executam.
- [ ] Security scan executa.
- [ ] Imagem Docker gerada.
- [ ] Artifacts publicados.
- [ ] Smoke tests executados.
- [ ] Certification executada.
- [ ] Release notes publicadas.
- [ ] Rollback definido.
- [ ] Evidências arquivadas.

152
specs/en/SPEC-018-Security-and-Identity-Model.md Normal file
View File

@@ -0,0 +1,152 @@
# SPEC-018 — Security and Identity Model
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Security and Identity Model Defines como workloads autenticam, como Components autorizam actions, como segredos are protegidos and como Data sensíveis are tratados.
# 2. Modelos of Authentication
| Modo | Uso |
| --- | --- |
| config_file | Development local with ~/.oci/config. |
| instance_principal | Execution em OCI Compute. |
| workload_identity | Execution em OKE/Kubernetes. |
| resource_principal | Recursos OCI gerenciados. |
| api_key | Endpoints compatíveis with OpenAI when aplicável. |
# 3. Workload Identity
Flow:
```mermaid
flowchart LR
Pod[Pod Kubernetes] --> SA[ServiceAccount]
SA --> WI[Workload Identity]
WI --> IAM[OCI IAM Policy]
IAM --> Resource[OCI Resource]
```
# 4. Authorization
Escopos:
- Agent can chamar tool?
- tenant can use provider?
- canal can chamar agent_id?
- User can executar ação?
- tool mutável exige confirmação?
# 5. Secrets
Secrets No ficam no código.
sources:
- OCI Vault;
- Kubernetes Secrets;
- secret manager corporativo.
Examples:
```text
LANGFUSE_SECRET_KEY
OCI_GENAI_API_KEY
ADB_PASSWORD
MCP_BACKEND_TOKEN
```
# 6. Proteção of Data
apply:
- máscara of PII;
- minimização of metadata;
- sanitização of payload;
- No logar secrets;
- retenção controlada;
- classificação of Data.
# 7. Security em MCP
MCP tools must ter:
- Authorization por Agent;
- allowlist;
- timeout;
- retry;
- idempotência declarada;
- confirmação for operações mutáveis.
# 8. Security em canais
Channel Gateway must:
- validate assinatura;
- validate origem;
- deduplicar;
- rate limit;
- remover tokens;
- normalizar payload;
- rejeitar anexos inválidos.
# 9. Auditoria
Registrar:
- User/canal;
- agent_id;
- tenant_id;
- tool Call;
- Model Used;
- Decision of guardrail;
- judge score;
- Error;
- trace_id.
# 10. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Secret em .env versionado | Vazamento. | use Vault/Secrets. |
| Tool without Authorization | Acesso indevido. | Allowed agents por tool. |
| Payload bruto em logs | Exposição of Data. | Mascarar/minimizar. |
| Instance main local | Timeout/Authentication invalid. | use config_file local. |
# 11. Acceptance criteria
- [ ] Modo of Authentication definido por ambiente.
- [ ] Secrets external ao código.
- [ ] MCP tools autorizadas por Agent.
- [ ] Channel Gateway valida origem.
- [ ] PII mascarada em logs.
- [ ] Events auditáveis emitidos.
- [ ] Workload Identity definido for OKE.
- [ ] Security review executado before Production.

164
specs/en/SPEC-019-Evaluation-and-Certification-Framework.md Normal file
View File

@@ -0,0 +1,164 @@
# SPEC-019 — Evaluation and Certification Framework
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Evaluation mede quality and comportamento. Certification valida prontidão técnica and funcional.
Evaluator responde:
```text
O agente respondeu bem?
A resposta está fundamentada?
A tool certa foi chamada?
Houve regressão?
```
Certification responde:
```text
O agente está pronto para rodar?
Endpoints funcionam?
MCP funciona?
Guardrails funcionam?
Observabilidade funciona?
```
# 2. Architecture
```mermaid
flowchart LR
Runtime[Runtime] --> LF[Langfuse]
LF --> Eval[Offline Evaluator]
Dataset[Datasets] --> Eval
Eval --> Scores[Scores]
Eval --> Reports[Reports]
Cert[Certification Suite] --> Runtime
Cert --> Evidence[Evidences]
```
# 3. Metrics
| metric | Description |
| --- | --- |
| quality | Clareza, completude and utilidade. |
| groundedness | Aderência evidências MCP/RAG. |
| safety | compliance of Security. |
| resolution | Resolve a intent. |
| tool_correctness | Uses tools corretas. |
| route_accuracy | Rota/intent corretas. |
| policy_compliance | Aderência à Policy of Domain. |
# 4. Dataset
```yaml
dataset:
name: telecom_contas_regression
version: 1.0.0
items:
- id: billing-001
input: "Quero consultar minha fatura"
business_context:
customer_key: "11999999999"
contract_key: "3000131180"
expected:
route: billing_agent
tools:
- consultar_fatura
min_scores:
quality: 0.75
groundedness: 0.70
```
# 5. EvaluationRun
```json
{
"run_id": "eval-001",
"agent_id": "telecom_contas",
"source": "langfuse",
"period_start": "2026-06-18T00:00:00Z",
"period_end": "2026-06-19T00:00:00Z",
"status": "running"
}
```
# 6. CLI
```bash
af-evaluator run --agent-id telecom_contas --dataset datasets/telecom_contas.yaml
```
# 7. Certification
Valida:
- health;
- GatewayRequest;
- routing;
- identity;
- MCP;
- RAG;
- guardrails;
- judges;
- memory;
- checkpoint;
- Langfuse;
- OTEL.
# 8. Evidências
- JSON;
- HTML;
- TXT.GZ legado;
- scores Langfuse;
- logs;
- traces;
- screenshots when aplicável.
# 9. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| Dataset só with casos felizes | Baixa coverage. | include negativos and bordas. |
| Evaluator without baseline | without comparação. | Registrar baseline. |
| Certification without MCP real/mock | integration No validada. | create tool test. |
| Judge without threshold | without criterion objective. | Definir threshold. |
# 10. Acceptance criteria
- [ ] Dataset versionado.
- [ ] Evaluator executado.
- [ ] Scores persistidos.
- [ ] Certification executada.
- [ ] Relatórios gerados.
- [ ] Thresholds definidos.
- [ ] Casos negativos incluídos.
- [ ] Scores publicados when aplicável.

166
specs/en/SPEC-020-Operational-Readiness-and-SRE-Model.md Normal file
View File

@@ -0,0 +1,166 @@
# SPEC-020 — Operational Readiness and SRE Model
## Agent Platform OCI
Version: 1.0.0
---
## Reading guide
each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
The document structure is:
1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.
---
# 1. Concept
Operational readiness defines the minimum requirements to run the Agent Platform OCI in production with reliability, observability, incident response capabilities, and recovery.
# 2. Managed components
- Agent Gateway;
- Channel Gateway;
- Agent Runtime;
- AI Gateway;
- MCP Gateway;
- MCP Servers;
- Evaluator;
- bancos/repositórios;
- Langfuse/OTEL;
- Redis/Mongo/ADB when usados.
# 3. Health and readiness
Minimum endpoints:
```text
GET /health
GET /ready
GET /version
```
# 4. SLOs
| Componente | Latency | Availability |
| --- | --- | --- |
| Agent Gateway | p95 < 1s | 99.5% |
| Agent Runtime | p95 < 5s | 99.0% |
| AI Gateway | p95 < 10s | 99.0% |
| MCP Gateway | p95 < 2s | 99.0% |
| Evaluator | janela batch | Execution diária |
# 5. Metrics
- requests_total;
- request_latency_ms;
- errors_total;
- active_sessions;
- llm_tokens_total;
- llm_cost_estimated;
- mcp_tool_calls_total;
- guardrail_blocks_total;
- judge_scores;
- evaluator_scores.
# 6. Dashboards
Minimum dashboards:
- Platform Overview;
- Runtime;
- Gateway;
- AI Gateway;
- MCP Gateway;
- Guardrails;
- Evaluator;
- Cost/Usage;
- Incidents.
# 7. Alerts
| Alert | Condition |
| --- | --- |
| HighErrorRate | 5xx above of the Limit. |
| LatencySLOBreach | p95 above of the SLO. |
| LLMProviderDown | Failures consecutive no provider. |
| MCPTimeoutSpike | increase of timeout MCP. |
| GuardrailSpike | increase abnormal of Blocks. |
| EvaluatorFailed | Run failed. |
# 8. Runbooks
A runbook must contain:
- symptom;
- Impact;
- queries;
- dashboards;
- logs;
- actions;
- rollback;
- escalation.
# 9. Incident management
Flow:
```mermaid
flowchart LR
Detect[Detect] --> Triage[Triage]
Triage --> Mitigate[Mitigate]
Mitigate --> Recover[Recover]
Recover --> Postmortem[Postmortem]
```
# 10. Capacity
Assess:
- QPS;
- Sessions concurrent;
- tokens/minuto;
- Calls MCP/minuto;
- Latency of provider;
- uso of Memory;
- storage of checkpoints.
# 11. Common errors
| Error | Impact | Correction |
| --- | --- | --- |
| without readiness | traffic before of app estar ready. | implement /ready. |
| without Alerts MCP | Failure silenciosa. | create Alerts por tool. |
| without runbook | MTTR high. | create runbooks por incidente. |
| without Cost LLM | without control financial. | Registrar tokens/Costs. |
# 12. Production readiness checklist
- [ ] Health checks ativos.
- [ ] Readiness checks ativos.
- [ ] Structured logs.
- [ ] Metrics exportadas.
- [ ] Exported traces.
- [ ] Dashboards created.
- [ ] Configured alerts.
- [ ] Runbooks disponíveis.
- [ ] Rollback validado.
- [ ] Defined SLOs.
- [ ] Estimated capacity.
- [ ] Incident process definido.