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 son compatibles:

Como biblioteca (recomendado para productos). Agrega btech-agent-lab a tu propio proyecto, define agentes extendiendo las clases base y arma la aplicación con create_app(). Extiendes el framework a través de su API pública (herencia de clases, decoradores y configuración) y nunca editas el código del framework. Comienza con el Tutorial o el Inicio rápido y luego lee Extensión del framework. Para evitar 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 agrega 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 Creación de flujos de trabajo agénticos.

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

Configuración inicial

Instalación

Agent-Lab está pensado para 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 ejecución: las pruebas de integración lo usan (mediante testcontainers) y los archivos de Docker Compose incluidos proporcionan las dependencias de la aplicación.

Copia 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. Cada variable está documentada 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 de navegador, notas de voz, visión y supervisores multiagente. Es a la vez un producto implementable 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 principio a fin. 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 implementación. La siguiente sección muestra cómo ejecutarla localmente.

Ejecución de la aplicación

Inicia 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=[...])`

Inicia 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 que la aplicación inicia, la API está disponible en http://localhost:18000/docs. Dashboards de observabilidad:

Grafana: http://localhost:3000 (credenciales predeterminadas: admin/admin). Consulta el ejemplo de Grafana.
OpenSearch Dashboards: http://localhost:5601. Consulta el ejemplo de OpenSearch.

Prácticas de desarrollo

Inyección de dependencias

La aplicación usa Dependency Injector para la inyección de dependencias, lo que mantiene las responsabilidades separadas 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 agregar 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 a través de 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 mediante variables 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 predeterminada cuando no hay ninguna variable de entorno definida). Para obtener la configuración desde otro backend, implementa tu propio ConfigSource y pásalo a create_app(config_source=...). Cada clave de configuración y variable de entorno está documentada 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.

Logging y observabilidad

La aplicación usa OpenTelemetry para el logging y la observabilidad; la configuración se encuentra en agent_lab/infrastructure/metrics/tracer.py. Las llamadas a FastAPI, HTTPX, LangChain, SQLAlchemy y OpenAI están instrumentadas de forma predeterminada, con backends conectables para Langfuse y LangWatch. Consulta la guía de observabilidad para más detalles.

Pruebas

El proyecto usa pytest con un enfoque en las pruebas de integración (umbral de cobertura: 90%), respaldadas por Testcontainers, de modo que las pruebas se ejecutan contra servicios reales en contenedores Docker. Una suite de simulación independiente evalúa el comportamiento de los agentes de principio a fin 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 el panorama completo.

Inicializa pre-commit

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

pre-commit install

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

Creación de flujos de trabajo agénticos

Agent-Lab está construido sobre 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.

Define una nueva implementación de agente

El agente es un concepto central en Agent-Lab: representa una entidad autónoma que puede 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 de vectores, temperatura, etc.).

Este es un ejemplo de los parámetros de inicialización persistidos de un agente que realiza transcripción y análisis de voz, después de que el agente se crea y se almacena en la base de datos:

Parámetros de inicialización del agente

Se pueden crear y perfeccionar varios agentes respaldados por la misma implementación mediante la API REST.

Registra 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; 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 cualquier extra_deps declarada,
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 requerían conectar manualmente cada agente en container.py, agregarlo a registry.py y extender el esquema de Pydantic en agents/schema.py. Esos pasos están obsoletos: @discoverable_agent se encarga de todos ellos. Cualquier extra_deps que declares se resuelve 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.

Haz 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 escanea 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 reemplaza los valores predeterminados, 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"
```

Experimenta 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 práctica de crear prototipos 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 administra instancias de él a través de 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 solicitudes.

Prueba 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 principio a fin 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álogos y la comunicación entre agentes.

Extensión del framework

Cuando consumes Agent-Lab como biblioteca, das forma a la aplicación por completo mediante create_app() y la API pública que exporta 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`, agrega 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	Decóralos con `@discoverable_mcp_tool` / `@discoverable_mcp_prompt` / `@discoverable_mcp_registrar`, regístralos con el mismo mecanismo de `scan_packages` / entry point que los agentes y agrega fragmentos de instrucciones MCP mediante `create_app(mcp_instructions=[...])`.
Backends de rastreo	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 usan estas opciones está en la Referencia de configuración.

Cómo contribuir

Agradecemos mucho el apoyo de la comunidad. Si encuentras algún problema o tienes sugerencias de mejora, repórtalos creando un issue 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 de errores.
Activa los hooks de pre-commit ejecutando pre-commit install, haz tus cambios y confírmalos con mensajes claros y concisos.
Asegúrate de que tus cambios pasen los hooks de pre-commit y el umbral de cobertura del 90% (make test).
Sube tus cambios a tu fork del repositorio.
Crea un Pull Request (PR) hacia la rama main del repositorio original.

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

Implementación en producción

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