228 lines
3.6 KiB
Markdown
228 lines
3.6 KiB
Markdown
# 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.
|