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

Crear un agente de codificación

Tabla de contenidos

Este tutorial te enseña cómo crear un agente de codificación que pueda ayudarte con las tareas de desarrollo de software. Comenzarás con un agente básico y añadirás capacidades progresivamente hasta tener un asistente listo para producción que pueda leer código, realizar cambios, ejecutar pruebas e incluso buscar documentación.

Al final, comprenderás cómo estructurar las instrucciones del agente, configurar herramientas y componer múltiples agentes para flujos de trabajo complejos.

Qué vas a construir

Un agente de codificación que puede:

  • Leer y modificar archivos en tu proyecto
  • Ejecutar comandos como pruebas y linters
  • Seguir un flujo de trabajo de desarrollo estructurado
  • Buscar documentación cuando sea necesario
  • Realizar un seguimiento del progreso a través de tareas de varios pasos

Qué vas a aprender

  • Cómo configurar agentes en YAML con Docker Agents
  • Cómo dar acceso a herramientas a los agentes (sistema de archivos, shell, etc.)
  • Cómo escribir instrucciones de agente eficaces
  • Cómo componer múltiples agentes para tareas especializadas
  • Cómo adaptar los agentes para tus propios proyectos

Requisitos previos

Antes de comenzar, necesitas:

  • Docker Agent instalado - Consulta la guía de instalación
  • Clave de API configurada - Configura ANTHROPIC_API_KEY o OPENAI_API_KEY en tu entorno. Obtén claves de Anthropic o OpenAI
  • Un proyecto con el que trabajar - Cualquier base de código donde desees asistencia del agente

Crear tu primer agente

Un agente se define en un archivo de configuración YAML. El agente mínimo solo necesita un modelo e instrucciones que definan su propósito.

Crea un archivo llamado agents.yml:

agents:
  root:
    model: openai/gpt-5
    description: A basic coding assistant
    instruction: |
      You are a helpful coding assistant.
      Help me write and understand code.

Ejecuta tu agente:

$ docker agent run agents.yml

Intenta preguntarle: "¿Cómo leo un archivo en Python?"

El agente puede responder preguntas de codificación, pero aún no puede ver tus archivos ni ejecutar comandos. Para que sea útil para el trabajo de desarrollo real, necesita acceso a herramientas.

Añadir herramientas

Un agente de codificación necesita interactuar con los archivos de tu proyecto y ejecutar comandos. Habilitas estas capacidades añadiendo conjuntos de herramientas (toolsets).

Actualiza agents.yml para añadir acceso al sistema de archivos y al shell:

agents:
  root:
    model: openai/gpt-5
    description: A coding assistant with filesystem access
    instruction: |
      You are a helpful coding assistant.
      You can read and write files to help me develop software.
      Always check if code works before finishing a task.
    toolsets:
      - type: filesystem
      - type: shell

Ejecuta el agente actualizado e intenta: "Lee el archivo README.md y resúmelo".

Tu agente ahora puede:

  • Leer y escribir archivos en el directorio actual
  • Ejecutar comandos de shell
  • Explorar la estructura de tu proyecto
Note

Por defecto, el acceso al sistema de archivos está restringido al directorio de trabajo actual. El agente solicitará permiso si necesita acceder a otros directorios.

El agente ahora puede interactuar con tu código, pero su comportamiento sigue siendo genérico. A continuación, le enseñarás a trabajar de manera eficaz.

Estructurar las instrucciones del agente

Las instrucciones genéricas producen resultados genéricos. Para el uso en producción, deseas que tu agente siga un flujo de trabajo específico y comprenda las convenciones de tu proyecto.

Actualiza tu agente con instrucciones estructuradas. Este ejemplo muestra un agente de desarrollo de Go, pero puedes adaptar el patrón para cualquier lenguaje:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Expert Go developer
    instruction: |
      Your goal is to help with code-related tasks by examining, modifying,
      and validating code changes.

      <TASK>
          # Workflow:
          # 1. Analyze: Understand requirements and identify relevant code.
          # 2. Examine: Search for files, analyze structure and dependencies.
          # 3. Modify: Make changes following best practices.
          # 4. Validate: Run linters/tests. If issues found, return to Modify.
      </TASK>

      Constraints:
      - Be thorough in examination before making changes
      - Always validate changes before considering the task complete
      - Write code to files, don't show it in chat

      ## Development Workflow
      - `go build ./...` - Build the application
      - `go test ./...` - Run tests
      - `golangci-lint run` - Check code quality

    add_date: true
    add_environment_info: true
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo

Intenta preguntar: "Añade manejo de errores a la función parseConfig en main.go"

Las instrucciones estructuradas le dan a tu agente:

  • Un flujo de trabajo claro a seguir (analizar, examinar, modificar, validar)
  • Comandos específicos del proyecto para ejecutar
  • Restricciones que previenen errores comunes
  • Contexto sobre el entorno (add_date y add_environment_info)

El conjunto de herramientas todo ayuda al agente a realizar un seguimiento del progreso a través de tareas de varios pasos. Cuando solicites cambios complejos, el agente dividirá el trabajo y actualizará su progreso a medida que avance.

Componer múltiples agentes

Las tareas complejas a menudo se benefician de agentes especializados. Puedes añadir subagentes que se encarguen de responsabilidades específicas, como investigar documentación mientras tu agente principal se mantiene enfocado en programar.

Añade un agente bibliotecario (librarian) que pueda buscar documentación:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Expert Go developer
    instruction: |
      Your goal is to help with code-related tasks by examining, modifying,
      and validating code changes.

      When you need to look up documentation or research how something works,
      ask the librarian agent.

      (rest of instructions from previous section...)
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo
    sub_agents:
      - librarian

  librarian:
    model: anthropic/claude-haiku-4-5
    description: Documentation researcher
    instruction: |
      You are the librarian. Your job is to find relevant documentation,
      articles, or resources to help the developer agent.

      Search the internet and fetch web pages as needed.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
      - type: fetch

Intenta preguntar: "¿Cómo uso context.Context en Go? Luego añádelo al código de mi servidor."

Tu agente principal delegará la investigación en el bibliotecario, luego utilizará esa información para modificar tu código. Esto mantiene el contexto del agente principal enfocado en la tarea de codificación mientras sigue teniendo acceso a documentación actualizada.

El uso de un modelo más pequeño y rápido (Haiku) para el bibliotecario ahorra costos, ya que la búsqueda de documentación no necesita la misma profundidad de razonamiento que los cambios de código.

Adaptar para tu proyecto

Ahora que comprendes los conceptos principales, adapta el agente para tu proyecto específico:

Actualiza los comandos de desarrollo

Reemplaza los comandos de Go con el flujo de trabajo de tu proyecto:

## Development Workflow
- `npm test` - Run tests
- `npm run lint` - Check code quality
- `npm run build` - Build the application

Añade restricciones específicas del proyecto

Si tu agente sigue cometiendo los mismos errores, añade restricciones explícitas:

Constraints:
  - Always run tests before considering a task complete
  - Follow the existing code style in src/ directories
  - Never modify files in the generated/ directory
  - Use TypeScript strict mode for new files

Elige los modelos adecuados

Para tareas de codificación, utiliza modelos enfocados en el razonamiento:

  • anthropic/claude-sonnet-4-5 - Razonamiento fuerte, bueno para código complejo
  • openai/gpt-5 - Rápido, buena capacidad general de codificación

Para tareas auxiliares como la búsqueda de documentación, los modelos más pequeños funcionan bien:

  • anthropic/claude-haiku-4-5 - Rápido y rentable
  • openai/gpt-5-mini - Bueno para tareas simples

Itera en función del uso

La mejor manera de mejorar a tu agente es usarlo. Cuando notes problemas:

  1. Añade instrucciones específicas para prevenir el problema.
  2. Actualiza las restricciones para guiar el comportamiento.
  3. Añade comandos relevantes al flujo de trabajo de desarrollo.
  4. Considera añadir subagentes especializados para áreas complejas.

Qué has aprendido

Ahora sabes cómo:

  • Crear una configuración básica de Docker Agent
  • Añadir herramientas para habilitar capacidades del agente
  • Escribir instrucciones estructuradas para un comportamiento consistente
  • Componer múltiples agentes para tareas especializadas
  • Adaptar agentes para diferentes lenguajes de programación y flujos de trabajo

Pasos siguientes