mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-11-06 03:14:12 +00:00
fix: Spec Agent Runtime
This commit is contained in:
347
specs/en/SPEC-011-Governance-Model.md
Normal file
347
specs/en/SPEC-011-Governance-Model.md
Normal 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.
|
||||
Reference in New Issue
Block a user