agent_framework_oci/specs/en/SPEC-011-Governance-Model.md

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:

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.

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.

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.

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.

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.

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.

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

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.