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

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.