# Crear un agente de codificación


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](/ai/docker-agent/#instalacion)
- **Clave de API configurada** - Configura `ANTHROPIC_API_KEY` o `OPENAI_API_KEY` en tu
  entorno. Obtén claves de [Anthropic](https://console.anthropic.com/) o
  [OpenAI](https://platform.openai.com/api-keys)
- **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`:

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

```console
$ 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:

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

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

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

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

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

- Aprende las [mejores prácticas](/ai/docker-agent/tutorial/best-practices/) para manejar salidas grandes, estructurar
  equipos de agentes y optimizar el rendimiento
- Integra Docker Agent con tu [editor](/ai/docker-agent/tutorial/integrations/acp/) o utiliza agentes como [herramientas en
  clientes MCP](/ai/docker-agent/tutorial/integrations/mcp/)
- Revisa la [Referencia de configuración](/ai/docker-agent/tutorial/reference/config/) para ver todas las opciones
  disponibles
- Explora la [Referencia de herramientas](/ai/docker-agent/tutorial/reference/toolsets/) para ver qué capacidades puedes
  habilitar
- Echa un vistazo a las [configuraciones de ejemplo](https://github.com/docker/docker-agent/tree/main/examples)
  para diferentes casos de uso
- Consulta el
  [golang_developer.yaml](https://github.com/docker/docker-agent/blob/main/golang_developer.yaml)
  completo que utiliza el equipo de Docker para desarrollar Docker Agent