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

SPEC-016 — Agent Development Lifecycle

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

O ciclo of vida of Development of Agents Defines as stages desde a discovery of the caso of uso até a Operations em Production.

Ele organiza trabalho of produto, Architecture, engenharia, Security, Evaluation and Operations.

2. Flow of the ciclo of 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. stage 1 — Discovery

objective:

• entender problema;
• identificar users;
• mapear canais;
• mapear sistemas;
• mapear documentos;
• mapear Risks.

Output:

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

4. stage 2 — Scope Definition

Definir:

• o that o Agent does;
• o that No does;
• intenções;
• actions permitidas;
• Limits;
• criteria of success.

5. stage 3 — Agent Design

Desenhar:

• agent_id;
• rotas;
• intents;
• BusinessContext;
• tools;
• RAG namespaces;
• Memory;
• handoff.

6. stage 4 — Prompt Design

create:

• system prompt;
• prompt policy;
• instruções of Domain;
• Examples;
• restrições;
• formato of Response.

7. stage 5 — MCP Design

Definir:

• tools;
• parâmetros;
• owner;
• SLA;
• timeout;
• retry;
• cache;
• Operations mutável or idempotente.

8. stage 6 — RAG Design

Definir:

• documentos;
• namespace;
• ingestão;
• chunking;
• embeddings;
• Update;
• criteria of relevância.

9. stage 7 — Implementation

implement:

• classe of the Agent;
• configs;
• prompts;
• datasets;
• tests;
• Observability específica.

10. stage 8 — Testing

Tests minimum:

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

11. stage 9 — Evaluation

Executar:

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

Assess:

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

12. stage 10 — Certification

Executar:

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

13. stage 11 — Homologation

validate with:

• negócio;
• Architecture;
• Security;
• Operations;
• integration.

14. stage 12 — Production

Requirements:

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

15. Common errors

Error	Impact	Correction
Começar by the código	Scope mal definido.	Iniciar por discovery/scope.
create tool before of the intent	Tool without Context.	Definir Flow primeiro.
Dataset after of the Production	without regressão.	create dataset before of the homologação.
Prompt without criteria	Response inconsistente.	Definir prompt policy.

16. Acceptance criteria

• Discovery concluído.
• Scope aprovado.
• Agent design documentado.
• Prompts criados.
• MCP design aprovado.
• RAG design aprovado when aplicável.
• Implementation concluída.
• Tests executados.
• Evaluator aprovado.
• Certification aprovada.
• Homologação concluída.
• Production monitorada.