agent_platform_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:

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