# 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

```mermaid
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:

```yaml
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:

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

Assess:

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

# 12. stage 10 — Certification

Executar:

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