Guía para investigadores

A quién va dirigida esta guía

A investigadores de IA y desarrolladores que quieran explorar, reproducir y ampliar experimentos en Agent-Lab. Si programas en Python, usas Jupyter y piensas en términos de experimentos, agentes y pipelines, te sentirás como en casa. Conocer los LLM, RAG y los fundamentos de los contenedores es útil, pero no imprescindible.

Agent-Lab proporciona componentes reutilizables (tipos de agente, herramientas, integraciones) y una colección de notebooks de Jupyter con ejemplos paso a paso, para que puedas ser productivo rápidamente.

Inicio rápido: ejecutar los ejemplos

Requisitos: Python 3.12+, un entorno de Jupyter operativo (JupyterLab o Notebook) y, opcionalmente, Docker en local para las integraciones de extremo a extremo. Trabajando en un clon del repositorio:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

Abre notebooks/ y empieza por 01_…, avanzando por los que te interesen.

Notas:

• Los notebooks son en su mayoría autónomos; la cabecera de cada uno indica las variables de entorno y los servicios externos necesarios (claves de API, endpoints).
• Las claves necesarias se guardan en .env: copia .env.example y rellénalo (consulta la Referencia de configuración).
• Para experimentar con Agent-Lab desde tu propio proyecto en lugar de desde el repositorio, ejecuta pip install btech-agent-lab y monta la aplicación con create_app(); consulta Ampliar el framework en la Guía para desarrolladores.

Estructura del proyecto: recorrido rápido

• notebooks/: ejemplos interactivos de tipos de agente, evaluación e integraciones. Empieza aquí.
• agent_lab/: el paquete del framework:
  • app_factory.py: la raíz de composición: create_app().
  • core/: fuentes de configuración, contenedor de DI y resolución de extra_deps.
  • domain/: modelos, interfaces de repositorio y excepciones (el Modelo de dominio de entidades).
  • services/: lógica de negocio y las implementaciones de agent_types/.
  • interface/: api/ (routers HTTP) y mcp/ (el servidor MCP).
  • infrastructure/: adaptadores de base de datos, autenticación y métricas/trazas.
• tests/: baterías unit/, integration/, template/ y simulation/ (consulta Pruebas y simulaciones).
• doc/: la documentación que estás leyendo.

Entender estas capas te indica dónde reside cada comportamiento: los ejemplos en notebooks, los contratos centrales en core/ y domain/, y los adaptadores en infrastructure/.

Notebooks: el itinerario de aprendizaje principal

Progresión habitual:

Cada notebook contiene: una breve descripción del objetivo del experimento, las variables de entorno y los secretos necesarios, funciones auxiliares y salidas impresas o visuales para inspeccionar las decisiones y las métricas del agente.

Consejo: ejecuta los notebooks en orden para seguir una curva de aprendizaje progresiva. Usa conjuntos de datos y tamaños de muestra más pequeños mientras iteras para que las ejecuciones sean rápidas.

Conceptos básicos

• Agente: una implementación registrada en agent_lab/services/agent_types/ (@discoverable_agent). El registro la resuelve de forma diferida a través del contenedor de DI, inyectando las extra_deps declaradas.
• Herramientas: capacidades concretas que un agente puede invocar (búsqueda, navegación, TTS/ASR), implementadas como adaptadores en agent_lab/infrastructure/ o agent_lab/interface/.
• Contenedor: el objeto de composición de DI (agent_lab/core/container.py); crea una subclase para añadir proveedores para tus experimentos.
• Repositorios: interfaces de acceso a datos en agent_lab/domain/repositories/.
• ConfigSource: de dónde procede la configuración; usa las fuentes YAML en los experimentos y Vault en producción.

Cuando quieras modificar un comportamiento, decide si el cambio es experimental (solo en un notebook), arquitectónico (core/domain/services) o de integración (un adaptador en infrastructure). Prioriza los cambios pequeños y comprobables, y añade o actualiza un notebook que muestre el nuevo comportamiento.

Ejecutar experimentos y registrar resultados

Los notebooks imprimen los pasos intermedios; para experimentos más sólidos:

• Usa semillas deterministas cuando la aleatoriedad sea relevante.

• Registra las métricas relevantes para tu pregunta: latencia, uso de tokens, número de llamadas a herramientas, puntuaciones del juez. La capa de observabilidad lo exporta todo como OpenTelemetry (consulta Observabilidad); el entorno de simulación registra las puntuaciones del juez en Langfuse/LangWatch (consulta Pruebas y simulaciones).

• Para ejecuciones repetibles, exporta las celdas de los notebooks a scripts y ejecútalos en la CI o en nodos de cómputo:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• docker/app/Dockerfile genera una imagen de ejecución con versiones fijadas para una ejecución reproducible.

Prototipar nuevos comportamientos

1. Añadir un nuevo tipo de agente: crea la clase en agent_lab/services/agent_types/, decórala con @discoverable_agent("your_type") y añade un notebook que la monte a través del contenedor de DI y la ejercite con un escenario pequeño. El recorrido completo está en Crear flujos de trabajo agénticos.
2. Cambiar de proveedor de embeddings: implementa un adaptador compatible en agent_lab/infrastructure/ y valídalo con el notebook 01.
3. Añadir un almacén de recuperación o una base de datos vectorial: implementa los métodos de repositorio en agent_lab/domain/repositories/ y un adaptador en agent_lab/infrastructure/database/; cárgale datos con un pequeño notebook de carga y demuestra la recuperación en un notebook de consultas.

Consejo de diseño: mantén las interfaces de los adaptadores acotadas y pruébalas de forma aislada con pequeñas pruebas unitarias.

Pruebas y evaluación

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

Cuando cambies el comportamiento central, añade una prueba unitaria y un notebook breve que muestre el cambio: esa combinación es lo que hace que la investigación sea reproducible aquí. El entorno de pruebas completo, la configuración del juez y las plataformas de evaluación se explican en Pruebas y simulaciones.

Lista de comprobación de reproducibilidad

• Fija tu entorno (uv + pyproject.toml / uv.lock).
• Registra las semillas y los archivos de configuración (config-dev.yml, config-test.yml).
• Guarda el checkpoint del notebook y cualquier artefacto de salida (CSV/JSON) junto con tu experimento.
• Anota los endpoints de trazas a los que has exportado: las trazas son el registro de tu experimento.