JuanandClaude Opus 4.7
57ba136c70
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>
105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# 🛡️ 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`](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`](docs/explicacion.md).
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up
|
|
```
|
|
|
|
Abre [http://localhost:8501](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)
|
|
|
|
1. **Registro** → ver `incident_analyzer` y comparar `v1` vs `v2`.
|
|
2. **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.
|
|
3. **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`](.env.example).
|
|
|
|
## Roadmap
|
|
|
|
Ver [`docs/futuro.md`](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
|
|
|
|
```bash
|
|
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).
|