Files

T

JuanandClaude Opus 4.7 6216689511 docs: README, ARCHITECTURE, roadmap futuro y manual de QA del dashboard

- 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>

2026-05-11 13:02:06 +02:00

3.1 KiB

Raw Blame History

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.

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 Protocols 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.

3.1 KiB Raw Blame History