# Mejores prácticas


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:**

```yaml
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:**

```yaml
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**

```yaml
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](/ai/docker-agent/reference/config/#task-delegation-versus-conversation-handoff).

**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.

```yaml
# 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.

```yaml
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.

```yaml
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:**

```yaml
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:

```yaml
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?

- Revisa la [referencia de configuración](/ai/docker-agent/reference/config/) para ver todas las opciones disponibles
- Consulta la [referencia de conjuntos de herramientas (toolsets)](/ai/docker-agent/reference/toolsets/) para comprender qué herramientas pueden usar los agentes
- Consulta las [configuraciones de ejemplo](https://github.com/docker/docker-agent/tree/main/examples) para ver agentes en funcionamiento completos
- Lee la [guía de RAG](/ai/docker-agent/rag/) para una optimización detallada de la recuperación