Construir y ejecutar aplicaciones de IA agéntica con Docker

Tabla de contenidos

Tip
Esta guía utiliza el flujo de trabajo familiar de Docker Compose para orquestar aplicaciones de IA agéntica. Para una experiencia de desarrollo más fluida, consulta Docker Agent, un entorno de ejecución de agentes diseñado específicamente para simplificar la ejecución y gestión de agentes de IA.

Introducción

Las aplicaciones agénticas están transformando la forma en que se construye el software. Estas aplicaciones no solo responden, sino que deciden, planifican y actúan. Están potenciadas por modelos, orquestadas por agentes e integradas con APIs, herramientas y servicios en tiempo real.

Todas estas nuevas aplicaciones agénticas, sin importar lo que hagan, comparten una arquitectura común. Es un nuevo tipo de pila (stack), construida a partir de tres componentes principales:

Modelos: Estos son tus GPT, CodeLlama, Mistral, etc. Se encargan del razonamiento, la escritura y la planificación. Son el motor detrás de la inteligencia.
Agente: Aquí es donde reside la lógica. Los agentes toman un objetivo, lo desglosan y descubren cómo llevarlo a cabo. Orquestan todo: se comunican con la interfaz de usuario, las herramientas, el modelo y la pasarela (gateway).
Pasarela MCP (MCP gateway): Esto es lo que vincula a tus agentes con el mundo exterior, incluyendo APIs, herramientas y servicios. Proporciona una forma estándar para que los agentes invoquen capacidades a través del Protocolo de Contexto de Modelo (Model Context Protocol o MCP).

Docker hace que esta pila potenciada por IA sea más sencilla, rápida y segura al unificar modelos y pasarelas de herramientas en un flujo de trabajo amigable para el desarrollador que utiliza Docker Compose.

Esta guía te acompaña a través de los componentes principales del desarrollo agéntico y muestra cómo Docker los conecta a todos con las siguientes herramientas:

Docker Model Runner te permite ejecutar LLM localmente con comandos sencillos y APIs compatibles con OpenAI.
Docker MCP Catalog and Toolkit te ayuda a descubrir y ejecutar de forma segura herramientas externas, como APIs y bases de datos, utilizando el Protocolo de Contexto de Modelo (MCP).
Docker MCP Gateway te permite orquestar y gestionar servidores MCP.
Docker Compose es la herramienta que lo une todo, permitiéndote definir y ejecutar aplicaciones multi-contenedor con un solo archivo.

En esta guía, utilizarás el mismo flujo de trabajo de Compose con el que ya estás familiarizado. Luego, profundizarás en el archivo Compose, el Dockerfile y la aplicación para ver cómo funciona todo en conjunto.

Prerrequisitos

Para seguir esta guía, necesitas:

Instalar Docker Desktop 4.43 o posterior
Habilitar Docker Model Runner
Al menos las siguientes especificaciones de hardware:
- VRAM: 3.5 GB
- Almacenamiento: 2.31 GB

Paso 1: Clonar la aplicación de muestra

Utilizarás una aplicación de muestra existente que demuestra cómo conectar un modelo a una herramienta externa utilizando las características de IA de Docker.

$ git clone https://github.com/docker/compose-for-agents.git
$ cd compose-for-agents/adk/

Paso 2: Ejecutar la aplicación localmente

Tu máquina debe cumplir con los requisitos de hardware necesarios para ejecutar toda la pila de la aplicación localmente usando Docker Compose. Esto te permite probar la aplicación de extremo a extremo (end-to-end), incluyendo el modelo y la pasarela MCP, sin necesidad de ejecutarla en la nube. Este ejemplo en particular utiliza el modelo Gemma 3 4B con un tamaño de contexto de 10000.

Requisitos de hardware:

VRAM: 3.5 GB
Almacenamiento: 2.31 GB

Si tu máquina supera esos requisitos, considera ejecutar la aplicación con un tamaño de contexto mayor o un modelo más grande para mejorar el rendimiento del agente. Puedes actualizar fácilmente el modelo y el tamaño del contexto en el archivo compose.yaml.

Para ejecutar la aplicación localmente, sigue estos pasos:

En el directorio adk/ del repositorio clonado, ejecuta el siguiente comando en una terminal para compilar y ejecutar la aplicación:
$ docker compose up
La primera vez que ejecutes este comando, Docker descargará el modelo de Docker Hub, lo cual puede tardar un poco.
Visita http://localhost:8080. Introduce un dato correcto o incorrecto en el prompt y presiona Enter. Un agente buscará en DuckDuckGo para verificarlo y otro agente revisará la salida.
Presiona Ctrl+C en la terminal para detener la aplicación cuando hayas terminado.

Paso 3: Revisar el entorno de la aplicación

Puedes encontrar el archivo compose.yaml en el directorio adk/. Abre el archivo en un editor de texto para ver cómo están definidos los servicios.

compose.yaml

services:
  adk:
    build:
      context: .
    ports:
      # expone el puerto para la interfaz web
      - "8080:8080"
    environment:
      # apunta adk a la pasarela MCP
      - MCPGATEWAY_ENDPOINT=http://mcp-gateway:8811/sse
    depends_on:
      - mcp-gateway
    models:
      gemma3:
        endpoint_var: MODEL_RUNNER_URL
        model_var: MODEL_RUNNER_MODEL

  mcp-gateway:
    # mcp-gateway protege tus servidores MCP
    image: docker/mcp-gateway:latest
    use_api_socket: true
    command:
      - --transport=sse
      # añade cualquier servidor MCP que quieras utilizar
      - --servers=duckduckgo

models:
  gemma3:
    # descarga previamente el modelo al iniciar Docker Model Runner
    model: ai/gemma3:4B-Q4_0
    context_size: 10000 # 3.5 GB de VRAM
    # aumenta el tamaño del contexto para manejar los resultados de búsqueda
    # context_size: 131000 # 7.6 GB de VRAM

La aplicación consta de tres componentes principales:

El servicio adk, que es la aplicación web que ejecuta la aplicación de IA agéntica. Este servicio se comunica con la pasarela MCP y el modelo.
El servicio mcp-gateway, que es la pasarela MCP que conecta la aplicación con herramientas y servicios externos.
El bloque models, que define el modelo que se utilizará con la aplicación.

Al examinar el archivo compose.yaml, notarás dos elementos destacables para el modelo:

Un bloque models a nivel de servicio en el servicio adk
Un bloque models a nivel superior

Estos dos bloques juntos permiten que Docker Compose inicie y conecte automáticamente tu aplicación web ADK al LLM especificado.

Tip
¿Buscas más modelos para usar? Consulta el Catálogo de modelos de IA de Docker.

Al examinar el archivo compose.yaml, notarás que el servicio de pasarela es una imagen mantenida por Docker: docker/mcp-gateway:latest. Esta imagen es la pasarela MCP de código abierto de Docker (MCP Gateway) que permite que tu aplicación se conecte a servidores MCP, los cuales exponen herramientas que los modelos pueden invocar. En este ejemplo, utiliza el servidor MCP de duckduckgo para realizar búsquedas en la web.

Tip
¿Buscas más servidores MCP para usar? Consulta el Catálogo de MCP de Docker.

Con solo unas pocas líneas de instrucciones en un archivo Compose, puedes ejecutar y conectar todos los servicios necesarios de una aplicación de IA agéntica.

Además del archivo Compose, el Dockerfile y el script entrypoint.sh que crea desempeñan un papel fundamental al conectar la pila de IA durante la compilación y el tiempo de ejecución. Puedes encontrar el Dockerfile en el directorio adk/. Abre el archivo en un editor de texto.

Dockerfile

# Usa la imagen slim de Python 3.13 como base
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1

RUN pip install uv

WORKDIR /app
# Instala las dependencias del sistema
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy \
    uv pip install --system .
# Copia el código de la aplicación
COPY agents/ ./agents/
RUN python -m compileall -q .

COPY <<EOF /entrypoint.sh
#!/bin/sh
set -e

if test -f /run/secrets/openai-api-key; then
    export OPENAI_API_KEY=$(cat /run/secrets/openai-api-key)
fi

if test -n "\${OPENAI_API_KEY}"; then
    echo "Using OpenAI with \${OPENAI_MODEL_NAME}"
else
    echo "Using Docker Model Runner with \${MODEL_RUNNER_MODEL}"
    export OPENAI_BASE_URL=\${MODEL_RUNNER_URL}
    export OPENAI_MODEL_NAME=openai/\${MODEL_RUNNER_MODEL}
    export OPENAI_API_KEY=cannot_be_empty
fi
exec adk web --host 0.0.0.0 --port 8080 --log_level DEBUG
EOF
RUN chmod +x /entrypoint.sh

# Crea un usuario no root
RUN useradd --create-home --shell /bin/bash app \
    && chown -R app:app /app
USER app

ENTRYPOINT [ "/entrypoint.sh" ]

El script entrypoint.sh tiene cinco variables de entorno clave:

MODEL_RUNNER_URL: Inyectada por Compose (via el bloque models: a nivel de servicio) para apuntar al endpoint HTTP de tu Docker Model Runner.
MODEL_RUNNER_MODEL: Inyectada por Compose para seleccionar qué modelo iniciar en el Model Runner.
OPENAI_API_KEY: Si defines un secreto openai-api-key en tu archivo Compose, Compose lo montará en /run/secrets/openai-api-key. El script del punto de entrada (entrypoint) lee ese archivo y lo exporta como OPENAI_API_KEY, lo que hace que la aplicación use la API de OpenAI alojada en la nube en lugar de Model Runner.
OPENAI_BASE_URL: Cuando no hay una clave real presente, se establece en MODEL_RUNNER_URL para que el cliente compatible con OpenAI de ADK envíe solicitudes a Docker Model Runner.
OPENAI_MODEL_NAME: Cuando se recurre al Model Runner, el modelo se prefija con openai/ para que el cliente identifique el alias de modelo correcto.

Juntas, estas variables permiten que el mismo código del servidor web ADK apunte sin problemas a:

OpenAI alojado en la nube: si proporcionas OPENAI_API_KEY (y opcionalmente OPENAI_MODEL_NAME)
Model Runner: remapeando MODEL_RUNNER_URL y MODEL_RUNNER_MODEL en las variables esperadas por el cliente de OpenAI

Paso 4: Revisar la aplicación

La aplicación web adk es una implementación de agente que se conecta a la pasarela MCP y a un modelo mediante variables de entorno y llamadas a la API. Utiliza el ADK (Agent Development Kit) para definir un agente raíz llamado Auditor, el cual coordina dos subagentes, Critic y Reviser, para verificar y perfeccionar las respuestas generadas por el modelo.

Los tres agentes son:

Critic: Verifica afirmaciones de hechos utilizando el conjunto de herramientas (toolset), como DuckDuckGo.
Reviser: Edita las respuestas basándose en los veredictos de verificación proporcionados por el Critic.
Auditor: Un agente de nivel superior que secuencia al Critic y al Reviser. Actúa como el punto de entrada, evaluando las respuestas generadas por el LLM, verificándolas y refinando la salida final.

Todo el comportamiento de la aplicación está definido en Python bajo el directorio agents/. Aquí tienes un desglose de los archivos más destacados:

agents/agent.py: Define el Auditor, un SequentialAgent que encadena los agentes Critic y Reviser. Este agente es el punto de entrada principal de la aplicación y se encarga de auditar el contenido generado por el LLM mediante herramientas de verificación del mundo real.
agents/sub_agents/critic/agent.py: Define el agente Critic. Carga el modelo de lenguaje (a través de Docker Model Runner), establece el nombre y comportamiento del agente, y se conecta a las herramientas MCP (como DuckDuckGo).
agents/sub_agents/critic/prompt.py: Contiene el prompt de Critic, que instruye al agente sobre cómo extraer y verificar afirmaciones usando herramientas externas.
agents/sub_agents/critic/tools.py: Define la configuración del conjunto de herramientas MCP, incluyendo el análisis de cadenas mcp/, la creación de conexiones de herramientas y la gestión de la comunicación con la pasarela MCP.
agents/sub_agents/reviser/agent.py: Define el agente Reviser, que toma los hallazgos de Critic y reescribe mínimamente la respuesta original. También incluye callbacks para limpiar la salida del LLM y asegurar que tenga el formato correcto.
agents/sub_agents/reviser/prompt.py: Contiene el prompt de Reviser, que instruye al agente sobre cómo revisar el texto de la respuesta basándose en los veredictos de las afirmaciones verificadas.

La pasarela MCP se configura mediante la variable de entorno MCPGATEWAY_ENDPOINT. En este caso, http://mcp-gateway:8811/sse. Esto permite que la aplicación use Server-Sent Events (SSE) para comunicarse con el contenedor de la pasarela MCP, el cual a su vez actúa como intermediario para acceder a servicios de herramientas externos como DuckDuckGo.

Resumen

Las aplicaciones de IA basadas en agentes están emergiendo como una nueva y potente arquitectura de software. En esta guía, exploraste un sistema modular de cadena de pensamiento (chain-of-thought) donde un agente Auditor coordina el trabajo de un Critic y un Reviser para verificar hechos y refinar las respuestas generadas por el modelo. Esta arquitectura muestra cómo combinar la inferencia de modelos locales con integraciones de herramientas externas de manera estructurada y modular.

También viste cómo Docker simplifica este proceso al proporcionar un conjunto de herramientas que admiten el desarrollo de IA agéntica:

Docker Model Runner: Ejecuta y sirve modelos de código abierto localmente a través de APIs compatibles con OpenAI.
Docker MCP Catalog and Toolkit: Inicia y gestiona integraciones de herramientas que siguen el estándar del Protocolo de Contexto de Modelo (MCP).
Docker MCP Gateway: Orquesta y gestiona servidores MCP para conectar agentes a herramientas y servicios externos.
Docker Compose: Define y ejecuta aplicaciones de IA agéntica multi-contenedor con un solo archivo, utilizando el mismo flujo de trabajo.

Con estas herramientas, puedes desarrollar y probar aplicaciones de IA agéntica de manera eficiente, utilizando el mismo flujo de trabajo consistente en todo momento.

¿En qué te puedo ayudar?

Construir y ejecutar aplicaciones de IA agéntica con Docker

Introducción

Prerrequisitos

Paso 1: Clonar la aplicación de muestra

Paso 2: Ejecutar la aplicación localmente

Paso 3: Revisar el entorno de la aplicación

Paso 4: Revisar la aplicación

Resumen