# 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).