Compartir comentarios
Las respuestas se generan en base a la documentación.

Mejores prácticas

Tabla de contenidos

Patrones que se aprenden al construir y ejecutar agentes con Docker Agent. Estas no son características ni opciones de configuración; son enfoques que funcionan bien en la práctica.

Manejar salidas de comandos grandes

Los comandos de shell que producen salidas muy grandes pueden desbordar la ventana de contexto de tu agente. Las herramientas de validación, las suites de pruebas y los registros de compilación a menudo generan miles de líneas. Si capturas esta salida directamente, consume todo el contexto disponible y el agente falla.

La solución: redirigir la salida a un archivo y luego leer el archivo. La herramienta de lectura (Read tool) trunca automáticamente los archivos grandes a 2000 líneas, y tu agente puede navegar a través de ellos si es necesario.

No hagas esto:

reviewer:
  instruction: |
    Ejecuta la validación: `docker buildx bake validate`
    Revisa la salida en busca de errores.
  toolsets:
    - type: shell

La salida de la validación va directamente al contexto. Si es muy grande, el agente falla con un error de desbordamiento de contexto.

Haz esto:

reviewer:
  instruction: |
    Ejecuta la validación y guarda la salida:
    `docker buildx bake validate > validation.log 2>&1`

    Lee el archivo validation.log para revisar si hay errores.
    El archivo puede ser grande: lee las primeras 2000 líneas.
    Los errores suelen aparecer al principio.
  toolsets:
    - type: filesystem
    - type: shell

La salida se guarda en un archivo, no en el contexto. El agente lee lo que necesita utilizando el conjunto de herramientas del sistema de archivos (filesystem).

Estructurar equipos de agentes

Un solo agente que maneja múltiples responsabilidades hace que las instrucciones sean complejas y el comportamiento impredecible. Dividir el trabajo entre agentes especializados produce mejores resultados.

El patrón de coordinador funciona bien: un agente root comprende la tarea general y delega en especialistas. Cada especialista se enfoca en una sola cosa.

Ejemplo: Equipo de redacción de documentación

agents:
  root:
    description: Coordinador de redacción técnica
    instruction: |
      Coordina el trabajo de documentación:
      1. Delega al escritor (writer) la creación de contenido.
      2. Delega al editor la edición y el pulido del estilo.
      3. Delega al revisor (reviewer) la validación.
      4. Regresa al editor si el revisor encuentra problemas.
    sub_agents: [writer, editor, reviewer]
    toolsets: [filesystem, todo]

  writer:
    description: Crea y edita contenido de documentación
    instruction: |
      Escribe documentación clara y práctica.
      Enfócate en la calidad del contenido; el editor se encargará del formato.
    toolsets: [filesystem, think]

  editor:
    description: Pule el formato y el estilo
    instruction: |
      Corrige problemas de formato, ajusta líneas, ejecuta prettier.
      Elimina expresiones típicas de IA y pule el estilo.
      No cambies el significado ni añadas contenido.
    toolsets: [filesystem, shell]

  reviewer:
    description: Ejecuta herramientas de validación
    instruction: |
      Ejecuta la suite de validación y reporta fallas.
    toolsets: [filesystem, shell]

Cada agente tiene responsabilidades claras. El escritor no se preocupa por el ajuste de línea. El editor no genera contenido. El revisor solo ejecuta herramientas.

Este ejemplo utiliza sub_agents donde el root delega tareas discretas y recibe los resultados de vuelta. El agente root mantiene el control y coordina todo el trabajo. Para diferentes patrones de coordinación donde los agentes deben transferirse el control entre sí, consulta el mecanismo de transferencias (handoffs) en la referencia de configuración.

Cuándo usar equipos:

  • Múltiples pasos distintos en tu flujo de trabajo
  • Se requieren diferentes habilidades (redacción ↔ edición ↔ pruebas)
  • Un paso podría necesitar reintentarse basándose en comentarios posteriores

Cuándo usar un solo agente:

  • Tareas simples y enfocadas
  • Todo el trabajo ocurre en un solo paso
  • Añadir la sobrecarga de coordinación no aporta valor

Optimizar el rendimiento de RAG

El indexado de RAG requiere tiempo cuando tienes muchos archivos. Una configuración que indexes todo tu código fuente puede tardar minutos en iniciarse. Optimiza para lo que tu agente realmente necesita.

Limita el alcance:

No indexes todo. Indexa lo que sea relevante para el trabajo del agente.

# Demasiado amplio: indexes todo el código fuente
rag:
  codebase:
    docs: [./]

# Mejor: indexes solo los directorios relevantes
rag:
  codebase:
    docs: [./src/api, ./docs, ./examples]

Si tu agente solo trabaja con código de API, no indexes pruebas, directorios de proveedores (vendor) ni archivos generados.

Aumenta el procesamiento por lotes y la concurrencia:

Procesa más fragmentos (chunks) por llamada a la API y realiza solicitudes en paralelo.

strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    batch_size: 50 # Más fragmentos por llamada a la API
    max_embedding_concurrency: 10 # Solicitudes en paralelo
    chunking:
      size: 2000 # Fragmentos más grandes = menos fragmentos totales
      overlap: 150

Esto reduce tanto las llamadas a la API como el tiempo de indexación.

Considera BM25 para una búsqueda local rápida:

Si necesitas coincidencias exactas de términos (nombres de funciones, mensajes de error, identificadores), BM25 es rápido y se ejecuta localmente sin llamadas a la API.

strategies:
  - type: bm25
    database: ./bm25.db
    chunking:
      size: 1500

Combínalo con incrustaciones (embeddings) utilizando la recuperación híbrida cuando necesites tanto comprensión semántica como coincidencias exactas.

Preservar el alcance del documento

Al construir agentes que actualizan la documentación, surge un problema común: el agente transforma guías mínimas en tutoriales completos. Añade requisitos previos, solución de problemas, mejores prácticas, ejemplos y explicaciones detalladas a todo.

Estas adiciones pueden ser buenas por separado, pero cambian el carácter del documento. Una guía práctica (how-to) de 90 líneas se convierte en una referencia de 200 líneas.

Integra esto en las instrucciones:

writer:
  instruction: |
    Al actualizar la documentación:

    1. Comprende el alcance y la longitud del documento actual.
    2. Mantén ese carácter: no transformes guías mínimas en tutoriales.
    3. Añade solo lo que realmente falte.
    4. Valora la brevedad: no todos los temas necesitan una cobertura exhaustiva.

    Las buenas adiciones llenan vacíos. Las malas adiciones cambian el carácter del documento.
    En caso de duda, añade menos en lugar de más.

Diles explícitamente a tus agentes que preserven el alcance del documento existente. Sin esta guía, por defecto intentarán ser exhaustivos.

Selección de modelo

Elige modelos según el rol y la complejidad del agente.

Usa modelos más grandes (Sonnet, GPT-5) para:

  • Razonamiento y planificación complejos
  • Redacción y edición de contenido
  • Coordinación de múltiples agentes
  • Tareas que requieren juicio y creatividad

Usa modelos más pequeños (Haiku, GPT-5 Mini) para:

  • Ejecución de herramientas de validación
  • Tareas estructuradas sencillas
  • Lectura de registros y reporte de errores
  • Trabajo de alto volumen y baja complejidad

Ejemplo del equipo de redacción de documentación:

agents:
  root:
    model: anthropic/claude-sonnet-4-5 # Coordinación compleja
  writer:
    model: anthropic/claude-sonnet-4-5 # Trabajo de contenido creativo
  editor:
    model: anthropic/claude-sonnet-4-5 # Criterio sobre el estilo
  reviewer:
    model: anthropic/claude-haiku-4-5 # Solo ejecuta validación

El revisor utiliza Haiku porque ejecuta comandos y comprueba errores. No se necesita un razonamiento complejo, y Haiku es más rápido y económico.

¿Qué sigue?