agent_platform_oci/specs/SPEC-016-Agent-Development-Lifecycle.md

SPEC-016 — Agent Development Lifecycle

Agent Platform OCI

Version: 1.0.0

---

Padrão de leitura

Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.

A estrutura usada é:

1. Conceito.
2. Problema que resolve.
3. Quando usar.
4. Quando não usar.
5. Arquitetura.
6. Implementação.
7. Exemplos.
8. Erros comuns.
9. Critérios de aceite.

---

1. Conceito

O ciclo de vida de desenvolvimento de agentes define as etapas desde a descoberta do caso de uso até a operação em produção.

Ele organiza trabalho de produto, arquitetura, engenharia, segurança, avaliação e operação.

2. Fluxo do ciclo de vida

flowchart LR
    D[Discovery] --> S[Scope]
    S --> AD[Agent Design]
    AD --> PD[Prompt Design]
    PD --> MD[MCP Design]
    MD --> RD[RAG Design]
    RD --> I[Implementation]
    I --> T[Testing]
    T --> E[Evaluation]
    E --> C[Certification]
    C --> H[Homologation]
    H --> P[Production]

3. Etapa 1 — Discovery

Objetivo:

• entender problema;
• identificar usuários;
• mapear canais;
• mapear sistemas;
• mapear documentos;
• mapear riscos.

Saída:

discovery:
  business_problem: ""
  users: []
  channels: []
  systems: []
  documents: []
  risks: []

4. Etapa 2 — Scope Definition

Definir:

• o que o agente faz;
• o que não faz;
• intenções;
• ações permitidas;
• limites;
• critérios de sucesso.

5. Etapa 3 — Agent Design

Desenhar:

• agent_id;
• rotas;
• intents;
• BusinessContext;
• tools;
• RAG namespaces;
• memória;
• handoff.

6. Etapa 4 — Prompt Design

Criar:

• system prompt;
• prompt policy;
• instruções de domínio;
• exemplos;
• restrições;
• formato de resposta.

7. Etapa 5 — MCP Design

Definir:

• tools;
• parâmetros;
• owner;
• SLA;
• timeout;
• retry;
• cache;
• operação mutável ou idempotente.

8. Etapa 6 — RAG Design

Definir:

• documentos;
• namespace;
• ingestão;
• chunking;
• embeddings;
• atualização;
• critérios de relevância.

9. Etapa 7 — Implementation

Implementar:

• classe do agente;
• configs;
• prompts;
• datasets;
• tests;
• observabilidade específica.

10. Etapa 8 — Testing

Testes mínimos:

• unit;
• integration;
• contract;
• MCP;
• RAG;
• guardrails;
• judges;
• runtime;
• channel.

11. Etapa 9 — Evaluation

Executar:

af-evaluator run --agent-id <agent_id> --dataset <dataset>

Avaliar:

• quality;
• groundedness;
• safety;
• tool correctness;
• route accuracy.

12. Etapa 10 — Certification

Executar:

af-certification run --agent-id <agent_id>

13. Etapa 11 — Homologation

Validar com:

• negócio;
• arquitetura;
• segurança;
• operação;
• integração.

14. Etapa 12 — Production

Requisitos:

• deploy aprovado;
• alertas ativos;
• dashboards ativos;
• rollback validado;
• runbook disponível.

15. Erros comuns

Erro	Impacto	Correção
Começar pelo código	Escopo mal definido.	Iniciar por discovery/scope.
Criar tool antes da intent	Tool sem contexto.	Definir fluxo primeiro.
Dataset depois da produção	Sem regressão.	Criar dataset antes da homologação.
Prompt sem critérios	Resposta inconsistente.	Definir prompt policy.

16. Critérios de aceite

• Discovery concluído.
• Escopo aprovado.
• Agent design documentado.
• Prompts criados.
• MCP design aprovado.
• RAG design aprovado quando aplicável.
• Implementação concluída.
• Testes executados.
• Evaluator aprovado.
• Certification aprovada.
• Homologação concluída.
• Produção monitorada.