JuanandClaude Opus 4.7
6216689511
- README.md: pitch, arquitectura, quickstart, demo guiada en 3 pasos, tabla de capacidades, estructura del repo, comandos de tests. - ARCHITECTURE.md: patrones (Strategy, config-over-code, fail-closed, trazabilidad), tabla de persistencia, patrón HITL, observabilidad, errores. - docs/futuro.md: roadmap post-MVP. - docs/manual_qa.md: checklist del smoke manual del dashboard (5 páginas + PII + persistencia). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# AgentForge — Arquitectura técnica
|
|
|
|
> Documento "vivo" con las decisiones técnicas. El spec original está en
|
|
> [`docs/superpowers/specs/2026-05-09-agentforge-design.md`](docs/superpowers/specs/2026-05-09-agentforge-design.md).
|
|
|
|
## Visión general
|
|
|
|
Two-tier:
|
|
- `agentforge-core` — FastAPI 8000. Dominio de gobierno, runtime LangGraph,
|
|
guardrails y persistencia.
|
|
- `agentforge-dashboard` — Streamlit 8501. Cliente HTTP del core.
|
|
|
|
## Diagrama
|
|
|
|
```
|
|
┌─────────────────────┐ HTTP/JSON ┌─────────────────────┐
|
|
│ Dashboard (Stream.) │ ───────────► │ Core (FastAPI) │
|
|
└─────────────────────┘ └─────────┬───────────┘
|
|
│
|
|
┌─────────────────────────┬────────┴──────┬────────────┐
|
|
▼ ▼ ▼ ▼
|
|
LLM layer Guardrails layer LangGraph State
|
|
(Strategy pattern) (Strategy pattern) Runtime JSON+SQL+JSONL
|
|
```
|
|
|
|
## Patrones aplicados
|
|
|
|
- **Strategy / Plugin**: `LLMProvider`, `GuardrailEngine`, `AgentRegistry`,
|
|
`PolicyStore` son `Protocol`s con varias implementaciones intercambiables
|
|
vía factory que lee `Settings`.
|
|
- **Configuration over code**: agentes y políticas como YAML versionados;
|
|
cambios sin redeploy.
|
|
- **Fail-closed por defecto**: errores en validadores cuentan como bloqueo.
|
|
- **Trazabilidad obligatoria**: `trace_id` UUID propagado por
|
|
middleware → structlog → API → JSONL.
|
|
|
|
## Persistencia
|
|
|
|
| Capa | Tecnología | Por qué |
|
|
|---|---|---|
|
|
| Agent Registry | JSON + YAML | Humano lo escribe (YAML); máquina lo cataloga (index.yaml). |
|
|
| Versionado | YAML por versión + index.yaml | Diff legible; hash SHA-256 normalizado. |
|
|
| Logs de violaciones | JSONL append-only | Inmutable, auditable, fácil de shipear. |
|
|
| Logs de ejecuciones | JSONL append-only | Idem. |
|
|
| Checkpoints LangGraph | SQLite | Tool right; persistencia entre restarts (HITL). |
|
|
|
|
## HITL — Patrón
|
|
|
|
Se usa la API dinámica `interrupt(payload)` de LangGraph ≥0.2 dentro del
|
|
nodo `approve_gate`. Sólo pausa cuando hay acciones de alto riesgo
|
|
(`risk_score >= threshold` o `requires_approval=True`). El cliente envía
|
|
`Command(resume={"approved_action_ids": [...]})` vía
|
|
`POST /executions/{trace_id}/approve`.
|
|
|
|
## Observabilidad
|
|
|
|
- `structlog` con renderer JSON.
|
|
- Middleware FastAPI inyecta `X-Trace-Id` y bind-ea contexto.
|
|
- Cada nodo del grafo añade un step a `decision_path` con `duration_ms`.
|
|
|
|
## Errores
|
|
|
|
- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s, fallback opcional, luego
|
|
`status=failed`.
|
|
- Validador: `fail_closed` por defecto.
|
|
- Schema mismatch en LLM output: 1 retry, luego `failed`.
|
|
- Checkpoint corrupto: 500 explícito (sin auto-recovery).
|
|
|
|
## Decisiones pospuestas
|
|
|
|
Ver [`docs/futuro.md`](docs/futuro.md).
|