Guía para investigadores

A quién está dirigida esta guía

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

Agent-Lab ofrece componentes reutilizables (tipos de agentes, 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: ejecuta los ejemplos

Requisitos: Python 3.12+, un entorno de Jupyter que funcione (JupyterLab o Notebook) y, de forma opcional, Docker local para integraciones de principio a fin. 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 comienza con 01_…; luego avanza por los que te interesen.

Notas:

• Los notebooks son en su mayoría independientes; el encabezado de cada uno indica las variables de entorno y los servicios externos necesarios (claves de API, endpoints).
• Las claves necesarias van en .env: copia .env.example y complétalo (consulta la Referencia de configuración).
• Para experimentar con Agent-Lab desde tu propio proyecto en lugar del repositorio, ejecuta pip install btech-agent-lab y arma la aplicación con create_app(); consulta Extensión del framework en la Guía para desarrolladores.

Estructura del proyecto: recorrido rápido

• notebooks/: ejemplos interactivos de tipos de agentes, 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, resolución de extra_deps.
  • domain/: modelos, interfaces de repositorios, 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/rastreo.
• tests/: suites unit/, integration/, template/ y simulation/ (consulta Pruebas y simulaciones).
• doc/: la documentación que estás leyendo.

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

Notebooks: la ruta principal de aprendizaje

Progresión típica:

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

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

Conceptos clave

• Agente: una implementación registrada en agent_lab/services/agent_types/ (@discoverable_agent). El registro la resuelve de forma diferida mediante el contenedor de DI, e inyecta las extra_deps declaradas.
• Herramientas: capacidades específicas 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 agregar proveedores para tus experimentos.
• Repositorios: interfaces de acceso a datos en agent_lab/domain/repositories/.
• ConfigSource: el origen de la configuración; usa las fuentes YAML en los experimentos y Vault en producción.

Cuando quieras modificar el comportamiento, decide si el cambio es experimental (solo en el notebook), arquitectónico (core/domain/services) o de integración (adaptador en infrastructure). Prefiere cambios pequeños y fáciles de probar, y agrega o actualiza un notebook para mostrar el nuevo comportamiento.

Ejecución de experimentos y registro de 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, cantidad de llamadas a herramientas, puntuaciones del juez. La capa de observabilidad 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 del notebook a scripts y ejecútalos en CI o en nodos de cómputo:

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

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

Prototipado de nuevos comportamientos

1. Agrega un nuevo tipo de agente: crea la clase en agent_lab/services/agent_types/, decórala con @discoverable_agent("your_type") y agrega un notebook que la monte mediante el contenedor de DI y la ponga a prueba con un escenario pequeño. El recorrido completo está en Creación de flujos de trabajo agénticos.
2. Cambia el proveedor de embeddings: implementa un adaptador compatible en agent_lab/infrastructure/ y valídalo con el notebook 01.
3. Agrega un almacén de recuperación o una base de datos vectorial: implementa los métodos del 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 acotadas las interfaces de los adaptadores 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, agrega una prueba unitaria y un notebook breve que demuestre 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 verificación de reproducibilidad

• Fija las versiones de 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 rastreo a los que exportaste: las trazas son el registro de tu experimento.