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>
108 lines
4.5 KiB
Markdown
108 lines
4.5 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). Además:
|
|
- [`docs/explicacion.md`](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`](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
|
|
|
|
```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).
|