agent_framework_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

{
  "code": "PINJ",
  "phase": "input",
  "status": "blocked",
  "severity": "high",
  "score": 0.98,
  "message": "Entrada bloqueada por política.",
  "details": {
    "matched_policy": "prompt_injection"
  }
}

Configuration Global

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

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

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

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.