agent_platform_oci/specs/en/SPEC-005-Guardrails.md

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