JuanandClaude Opus 4.7
ce629139c2
Complementa a docs/explicacion.md (alto nivel) con la vista de bajo nivel: - grafo de dependencias de módulos por niveles topológicos (imports internos) - el grafo de inyección de dependencias de api/deps.py (lru_cache + factories) - las firmas exactas de los contratos: LLMProvider, GuardrailEngine, los validadores, el registry/policy store, el AgentOrchestrator, AgentState y el cableado del grafo LangGraph, y cómo orchestrator._build_execution mapea el StateSnapshot a AgentExecution - la cadena de llamada de cada endpoint (qué deps, qué llama, qué persiste) - mapa de persistencia (quién escribe/lee cada artefacto YAML/JSON/JSONL/SQLite) - mapa CoreClient ↔ endpoints ↔ páginas del dashboard - arranque/ciclo de vida y tabla Settings → consumidor - "gotchas" conocidos README y docs/explicacion.md enlazan al nuevo documento. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
🛡️ 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. Además:
docs/explicacion.md— 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).docs/componentes.md— referencia de cableado a bajo nivel (grafo de dependencias de módulos, inyección de dependencias, firmas de los contratos entre capas, cadenas de llamada de cada endpoint).
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_analyzery compararv1vsv2. - Ejecutar → seleccionar el escenario
01_sip_registration_dropy 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).