Guía para desarrolladores

Dos formas de desarrollar

Agent-Lab es un framework que consumes como biblioteca, y también es un repositorio en el que puedes trabajar directamente. Ambas opciones están soportadas:

Como biblioteca (recomendado para productos). Añade btech-agent-lab a tu propio proyecto, define agentes extendiendo las clases base y monta la aplicación con create_app(). Amplías el framework a través de su API pública (subclases, decoradores y configuración) y nunca editas el código del framework. Empieza por el Tutorial o el Inicio rápido y después lee Ampliar el framework. Para ahorrarte el código repetitivo, genera un proyecto consumidor listo para usar con uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (consulta cookiecutter/README.md).
Dentro del repositorio (para colaboradores y la implementación de referencia). Clona el repositorio y añade agentes en agent_lab/services/agent_types/, ejecuta la aplicación de referencia incluida y usa los notebooks y las pruebas de integración. Así es como se desarrollan los agentes integrados. Consulta Crear flujos de trabajo agénticos.

Ambos caminos usan los mismos componentes; la única diferencia es dónde reside tu código. Elige el que mejor se adapte a tu proyecto.

Instalación y configuración

Instalación

Agent-Lab requiere Python 3.12+ y usa uv para la gestión de dependencias.

Para consumir Agent-Lab como biblioteca, instálalo en tu propio proyecto:

pip install btech-agent-lab
# or
uv add btech-agent-lab

Para trabajar en el repositorio, clónalo y sincroniza el entorno:

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Asegúrate de que Docker u otro entorno de ejecución de contenedores esté instalado y en funcionamiento: las pruebas de integración lo utilizan (mediante testcontainers) y los archivos de Docker Compose incluidos proporcionan las dependencias de la aplicación.

Copiar el archivo de entorno de ejemplo

cp .env.example .env

Este archivo contiene las claves de API de los proveedores de IA y los endpoints que usan las simulaciones de agentes. Todas las variables están documentadas en la Referencia de configuración.

Implementación de referencia

El repositorio incluye una aplicación de referencia completa (agent_lab.main) que registra todos los agentes integrados: RAG, automatización del navegador, notas de voz, visión y supervisores multiagente. Es a la vez un producto desplegable y el ejemplo canónico de cómo consumir el framework: no es más que una llamada a create_app() sobre los paquetes de agentes integrados.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

Úsala como referencia viva mientras creas tu propia aplicación y como la forma más rápida de probar Agent-Lab de extremo a extremo. El aprovisionamiento de su infraestructura (las tres bases de datos PostgreSQL, Redis, Keycloak, Vault) en desarrollo o producción se explica en la Guía de despliegue. La siguiente sección muestra cómo ejecutarla en local.

Ejecutar la aplicación

Iniciar la aplicación con Uvicorn

Para desarrollar y depurar con un IDE, ejecuta directamente la aplicación de referencia:

uvicorn agent_lab.main:app --reload

Accede a la documentación interactiva de OpenAPI en http://localhost:8000/docs.

Cuando consumes Agent-Lab como biblioteca, ejecutas tu aplicación de la misma forma: apunta uvicorn al módulo que llama a create_app():

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Iniciar la aplicación con Docker Compose

Dos archivos de Docker Compose preconfigurados ejecutan la aplicación de referencia junto con un stack de observabilidad:

compose-grafana.yml: la aplicación más Grafana, Prometheus, Tempo y Loki.
compose-opensearch.yml: la aplicación más OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

Una vez iniciada la aplicación, la API está disponible en http://localhost:18000/docs. Paneles de observabilidad:

Grafana: http://localhost:3000 (credenciales por defecto: admin/admin). Consulta el ejemplo con Grafana.
OpenSearch Dashboards: http://localhost:5601. Consulta el ejemplo con OpenSearch.

Prácticas de desarrollo

Inyección de dependencias

La aplicación utiliza Dependency Injector para la inyección de dependencias, lo que mantiene separadas las responsabilidades y facilita las pruebas.

El contenedor se define en agent_lab/core/container.py. Cuando consumes Agent-Lab como biblioteca, crea una subclase de Container para añadir tus propios proveedores y pasa la instancia a create_app(container=...). Cuando trabajas dentro del repositorio, registra los servicios adicionales del framework directamente en el contenedor.

Configuración de la aplicación

La configuración se carga mediante un ConfigSource (consulta agent_lab/core/config.py) y se vincula al contenedor de DI. El framework incluye tres fuentes YAML para desarrollo y pruebas, que se seleccionan automáticamente según la variable de entorno:

config-dev.yml: entorno de desarrollo, se activa cuando DEVELOPING está definida; pensado para depurar en el IDE.
config-test.yml: entorno de pruebas, se activa cuando TESTING está definida; lo usa la configuración de las pruebas de integración.
config-docker.yml: entorno de Docker Compose, se activa cuando DOCKER está definida.

Estos archivos definen ajustes como las conexiones a bases de datos y la autenticación, y están pensados solo para desarrollo y pruebas. En producción, usa Vault mediante VaultConfigSource (la opción por defecto cuando no hay ninguna variable de entorno definida). Para obtener la configuración de otro backend, implementa tu propio ConfigSource y pásalo a create_app(config_source=...). Todas las claves de configuración y variables de entorno están documentadas en la Referencia de configuración.

Modelo de dominio de entidades

Consulta el Modelo de dominio de entidades para conocer el modelo de datos: las entidades y sus relaciones que se usan en toda la aplicación.

Logs y observabilidad

La aplicación utiliza OpenTelemetry para los logs y la observabilidad; la configuración se encuentra en agent_lab/infrastructure/metrics/tracer.py. Las llamadas de FastAPI, HTTPX, LangChain, SQLAlchemy y OpenAI se instrumentan de serie, con backends conectables para Langfuse y LangWatch. Consulta la Guía de observabilidad para más detalles.

Pruebas

El proyecto utiliza pytest con énfasis en las pruebas de integración (umbral de cobertura: 90 %), apoyadas en Testcontainers para que las pruebas se ejecuten contra servicios reales en contenedores Docker. Una batería de simulación independiente evalúa el comportamiento de los agentes de extremo a extremo con un LLM como juez.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

La primera ejecución puede tardar varios minutos, ya que descarga imágenes de Docker y modelos de embeddings. Consulta la guía de pruebas para tener una visión completa.

Inicializar pre-commit

Si piensas contribuir al código o crear nuevos agentes sobre Agent-Lab, instala los hooks de pre-commit:

pre-commit install

Así te aseguras de que tu código cumple los estándares de programación del proyecto antes de hacer commit.

Crear flujos de trabajo agénticos

Agent-Lab se basa en LangGraph, que ofrece una forma potente de crear flujos de trabajo agénticos con LLM. Crear uno es un proceso sencillo gracias a la arquitectura modular y a las clases base de agentes.

Definir una nueva implementación de agente

El agente es un concepto central de Agent-Lab: representa una entidad autónoma capaz de realizar tareas, tomar decisiones e interactuar con otros agentes o sistemas externos. Un agente es una implementación concreta de una de las clases base:

Clases base de Agent-Lab

Una clase que extiende WorkflowAgentBase define:

un flujo de trabajo que representa el comportamiento del agente: tareas, toma de decisiones e interacciones con otros agentes o sistemas externos.
parámetros de inicialización, como los prompts (plantillas Jinja2) y otros ajustes que personalizan el comportamiento del agente (colecciones del almacén vectorial, temperatura, etc.).

Este es un ejemplo de parámetros de inicialización persistidos de un agente que realiza transcripción y análisis de voz, una vez creado el agente y almacenado en la base de datos:

Parámetros de inicialización del agente

Se pueden crear y refinar varios agentes basados en la misma implementación mediante la API REST.

Registrar el agente con `@discoverable_agent`

Decora tu subclase de AgentBase con @discoverable_agent("<agent_type>"). Ese único decorador es todo el registro que necesita un agente, y hace que el agente sea:

descubrible por el registro de agentes (agent_lab/services/agent_types/registry.py),
resoluble a través del contenedor de DI, que lo instancia de forma diferida e inyecta las extra_deps declaradas,
válido en la API, porque el esquema de creación de agentes valida agent_type contra el registro de forma dinámica.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

Nota (migración): las versiones anteriores obligaban a conectar manualmente cada agente en container.py, añadirlo a registry.py y ampliar el esquema de Pydantic en agents/schema.py. Esos pasos están obsoletos: @discoverable_agent se encarga de todos ellos. Las extra_deps que declares se resuelven por nombre a partir del contenedor (posiblemente una subclase) en el momento de la instanciación.

Si un agente necesita colaboradores además de AgentUtils, exponlos como proveedores en el contenedor (crea una subclase de Container cuando consumas la biblioteca) y nómbralos en extra_deps.

Hacer que el agente sea descubrible

El framework solo importa los módulos de agentes que se le indican, para que el decorador se ejecute:

Dentro del repositorio: coloca el agente en agent_lab/services/agent_types/; la aplicación de referencia analiza ese paquete como parte de DEFAULT_SCAN_PACKAGES (create_app()).
Como biblioteca: pasa tu paquete a create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) (una lista explícita sustituye a los valores por defecto, que es también la forma de excluir capacidades integradas) o publícalo desde un paquete instalado mediante el grupo de entry points agent_lab.agents para que los consumidores lo detecten automáticamente:
```
# pyproject.toml of the package that ships the agents
[project.entry-points."agent_lab.agents"]
my_agents = "my_agents"
```

Experimentar con la implementación del agente

Consulta los notebooks para ver ejemplos de cómo probar un agente de forma interactiva con Jupyter, usando el mismo mecanismo de inyección de dependencias. Es una forma cómoda de prototipar y validar el comportamiento en un entorno controlado; consulta la Guía para investigadores.

Interfaz de agentes de la API REST

Una vez registrado un agente, crea y gestiona sus instancias mediante la API REST: puedes ejecutar varias instancias configuradas de la misma implementación, cada una con sus propios prompts y ajustes. Consulta la Referencia de la API REST para ver el catálogo de endpoints y ejemplos de peticiones.

Probar el agente

Las pruebas de integración (tests/integration/) validan el agente contra infraestructura real con pytest y testcontainers.
Las simulaciones (tests/simulation/) evalúan el comportamiento de extremo a extremo con un LLM como juez. Consulta la guía de pruebas.

Servidor MCP

Consulta la Guía del servidor MCP para exponer tus agentes (y herramientas adicionales) a clientes MCP como Claude Desktop, para el descubrimiento de agentes, el historial de diálogo y la comunicación entre agentes.

Ampliar el framework

Cuando consumes Agent-Lab como biblioteca, das forma a la aplicación exclusivamente mediante create_app() y la API pública exportada desde el paquete de nivel superior agent_lab, nunca editando el código del framework:

Punto de extensión	Cómo
Agentes	Crea una subclase de una clase base, decórala con `@discoverable_agent` y regístrala mediante `scan_packages=[...]` o el entry point `agent_lab.agents`.
Servicios y dependencias	Crea una subclase de `Container`, añade proveedores y pásala como `create_app(container=...)`.
Configuración	Implementa un `ConfigSource` (o usa `YamlConfigSource` / `VaultConfigSource`) y pasa `create_app(config_source=...)`.
Rutas HTTP adicionales	Crea un `APIRouter`, envuélvelo en un `RouterMount` (con su política de autenticación) y pasa `create_app(extra_routers=[...])`.
Herramientas y prompts MCP	Decora con `@discoverable_mcp_tool` / `@discoverable_mcp_prompt` / `@discoverable_mcp_registrar`, regístralos mediante el mismo `scan_packages` o entry point que los agentes y añade fragmentos de instrucciones MCP mediante `create_app(mcp_instructions=[...])`.
Backends de trazas	Crea una subclase de `TracingBackend` y regístrala en tu `Container` para exportar spans a tu propia plataforma.

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

Todo lo anterior se exporta desde agent_lab (consulta agent_lab/__init__.py); la lista completa de claves de configuración que utilizan estas opciones está en la Referencia de configuración.

Contribuir

El apoyo de la comunidad es muy apreciado. Si encuentras algún problema o tienes sugerencias de mejora, comunícanoslo creando una incidencia en nuestra página de GitHub Issues.

Para contribuir al proyecto, sigue estos pasos:

Haz un fork del repositorio.
Crea una nueva rama para tu funcionalidad o corrección.
Activa los hooks de pre-commit ejecutando pre-commit install, realiza tus cambios y haz commit con mensajes claros y concisos.
Asegúrate de que tus cambios superan los hooks de pre-commit y el umbral de cobertura del 90 % (make test).
Sube tus cambios a tu repositorio bifurcado.
Crea una Pull Request (PR) hacia la rama main del repositorio original.

Revisaremos tu PR y te daremos nuestra opinión. ¡Gracias por tus contribuciones y tu apoyo!

Despliegue en producción

Consulta la Guía de despliegue para desplegar la aplicación de referencia en producción con los charts de Helm y los scripts de Terraform incluidos.