Files

T

JuanandClaude Opus 4.7 57ba136c70 docs: añade docs/explicacion.md — guía didáctica del proyecto y sus módulos

Documento de alto nivel para terceros: las seis ideas clave, vista de los dos
servicios y las capas del core, recorrido módulo a módulo con sus dependencias
(quién depende de quién), el patrón Protocol+factory+Settings, el viaje completo
de una petición (con diagrama de secuencia), la estrategia de persistencia (YAML/
JSON/JSONL/SQLite), glosario, mapa del repo y ruta de lectura. README enlaza a él.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-11 15:01:01 +02:00

4.3 KiB

Raw Blame History

🛡️ AgentForge

Plataforma profesional de gobernanza de agentes IA: catalogación, versionado de prompts y políticas, guardrails runtime, ejecución stateful con Human-in-the-Loop, observabilidad y trazabilidad end-to-end.

¿Por qué?

Poner agentes IA en producción sin una capa de gobierno produce sistemas opacos: prompts que cambian sin historial, validaciones inconsistentes, acciones de alto impacto sin supervisión, sin auditoría de decisiones. AgentForge aporta el plano de control mínimo que un equipo de plataforma necesita antes de operar agentes con impacto real.

Arquitectura

┌───────────────────────── docker-compose ──────────────────────────┐
│                                                                    │
│  ┌─────────────────────┐     HTTP/JSON     ┌────────────────────┐ │
│  │ agentforge-dashboard│ ────────────────► │ agentforge-core    │ │
│  │ Streamlit  :8501    │ ◄──────────────── │ FastAPI    :8000   │ │
│  └─────────────────────┘                   └────────────────────┘ │
│                                                                    │
│   Strategy pattern (Protocol) para LLMProvider, GuardrailEngine,  │
│   AgentRegistry. Persistencia mixta: YAML (definiciones), JSON    │
│   (registry), JSONL (logs append-only), SQLite (checkpoints).     │
└────────────────────────────────────────────────────────────────────┘

Detalles completos en ARCHITECTURE.md. Para una explicación didáctica de extremo a extremo (conceptos, recorrido por todos los módulos y sus interrelaciones, y el viaje de una petición de principio a fin), ver docs/explicacion.md.

Quickstart

cp .env.example .env
docker compose up

Abre http://localhost:8501.

Funciona out-of-the-box (LLM_PROVIDER=mock, sin API keys). Si quieres usar Azure OpenAI real, edita .env.

Demo guiada (3 pasos)

Registro → ver incident_analyzer y comparar v1 vs v2.
Ejecutar → seleccionar el escenario 01_sip_registration_drop y pulsar Invocar. Verás el grafo recorrer validate_input → llm_reason → validate_output → propose_actions → approve_gate y pausarse en HITL.
Aprobaciones → revisar las acciones propuestas (con risk_score y rollback_plan), aprobar las seguras y comprobar que la ejecución completa.

Capacidades implementadas

Feature	Ubicación
Agent Registry	`core/src/agentforge_core/registry/repository.py`
Versionado tipo Git	`agents/<name>/versions/` + `registry/versioning.py`
Guardrails runtime	`core/src/agentforge_core/guardrails/`
LangGraph stateful + checkpointing	`core/src/agentforge_core/runtime/`
Human-in-the-Loop	nodo `approve_gate` + endpoints `/approve` y `/reject`
Observabilidad	`observability/logging.py` (structlog + trace_id)
LLM provider abstraction	`core/src/agentforge_core/llm/`
Política versionada	`policies/default/versions/v1.yaml`

Variables de entorno

Ver .env.example.

Roadmap

Ver docs/futuro.md.

Estructura del repositorio

agentforge/
├── core/                 servicio FastAPI
├── dashboard/            servicio Streamlit
├── agents/               definiciones declarativas (YAML)
├── policies/             políticas de guardrails
├── data/                 estado runtime (gitignored)
├── tests/                pytest unit + integration
└── docs/                 documentación adicional

Tests

make install
make test         # solo unit
make test-all     # unit + integration
make lint         # ruff + mypy
make smoke        # docker-compose + curl health

Licencia

MIT (a confirmar).

4.3 KiB Raw Blame History