Capitulo 6: Agentes Custom

< Volver al Indice del Tutorial

Los agentes built-in cubren los casos de uso generales, pero los proyectos reales tienen necesidades especificas. OpenCode permite crear agentes custom con prompts, herramientas y permisos personalizados.

Por que Crear Agentes Custom

Cada proyecto tiene flujos de trabajo unicos. Con agentes custom puedes:

• Review: un agente de solo lectura especializado en code review
• Debug: un agente con acceso a logs y herramientas de depuracion
• Docs: un agente que solo puede escribir documentacion
• Testing: un agente enfocado en crear y ejecutar tests
• Deploy: un agente con comandos especificos de despliegue

En lugar de explicar el contexto cada vez, lo defines una vez en la configuracion del agente.

Dos Formas de Configurar

OpenCode ofrece dos metodos para definir agentes custom:

1. JSON (opencode.json)

Define agentes directamente en el archivo de configuracion del proyecto. Ideal para agentes simples o cuando quieres toda la configuracion en un solo lugar.

2. Markdown (archivos .md)

Define agentes como archivos Markdown individuales. Mejor para agentes con prompts largos o cuando quieres versionarlos por separado.

Wizard Interactivo

La forma mas facil de crear un agente custom es usando el wizard:

opencode agent create

Este comando te guia paso a paso para configurar:

• Nombre del agente
• Descripcion
• Modo (primario o subagente)
• Herramientas habilitadas
• System prompt
• Ubicacion del archivo

Ubicacion de Archivos Markdown

Los agentes en formato Markdown se pueden ubicar en dos niveles:

Global (todos los proyectos)

~/.config/opencode/agents/mi-agente.md

Disponible en cualquier proyecto donde uses OpenCode.

Por Proyecto

.opencode/agents/mi-agente.md

Solo disponible en ese proyecto. Los agentes de proyecto tienen prioridad sobre los globales si tienen el mismo nombre.

Opciones de Configuracion

Cada agente custom acepta las siguientes opciones:

Opciones Basicas

Opcion	Requerido	Descripcion
description	Si	Descripcion del agente mostrada en la interfaz
mode	No	primary, subagent o all (default: all)
prompt	No	System prompt personalizado

Modelo y Parametros

Opcion	Default	Descripcion
model	Hereda del padre	Override del modelo LLM para este agente
temperature	Depende del modelo	Creatividad de las respuestas (0.0 - 1.0)
top_p	Depende del modelo	Diversidad del muestreo
steps	Sin limite	Numero maximo de iteraciones

Herramientas y Permisos

Opcion	Descripcion
tools	Lista de herramientas habilitadas o deshabilitadas
permission	Permisos por herramienta: ask, allow o deny

Apariencia

Opcion	Descripcion
color	Color del agente en la interfaz
hidden	Si es true, el agente no aparece en la lista visible

Modos de Agente

• primary: Aparece como opcion principal junto a Build y Plan. Se cambia con Tab.
• subagent: Se invoca con @nombre desde otro agente.
• all: Funciona en ambos modos.

Ejemplo: Agente Review (Read-Only)

Un agente de code review que solo puede leer archivos y buscar, sin capacidad de modificar nada:

{
  "agents": {
    "review": {
      "description": "Code reviewer - analiza codigo sin modificar",
      "mode": "primary",
      "prompt": "Eres un reviewer experto. Analiza el codigo buscando bugs, problemas de seguridad, code smells y oportunidades de mejora. NUNCA modifiques archivos.",
      "tools": {
        "read": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "write": "deny",
        "edit": "deny",
        "patch": "deny",
        "bash": "deny"
      }
    }
  }
}

Con este agente, puedes cambiar a el con Tab y pedirle que revise archivos especificos o secciones del codebase con la tranquilidad de que no modificara nada.

Ejemplo: Agente Docs (Solo Escritura de Documentacion)

Un agente especializado en crear y editar documentacion:

{
  "agents": {
    "docs": {
      "description": "Escritor de documentacion tecnica",
      "mode": "subagent",
      "prompt": "Eres un tecnico especializado en documentacion. Crea y actualiza archivos de documentacion. Solo trabaja con archivos .md, .mdx y .txt.",
      "tools": {
        "read": "allow",
        "write": "allow",
        "edit": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "bash": "deny",
        "patch": "deny"
      }
    }
  }
}

Invocar con:

@docs crea la documentacion para el modulo de autenticacion

Formato Markdown

Alternativamente, puedes definir el agente review como archivo .md:

---
description: "Code reviewer - analiza codigo sin modificar"
mode: primary
tools:
  read: allow
  grep: allow
  glob: allow
  list: allow
  write: deny
  edit: deny
  patch: deny
  bash: deny
---

Eres un reviewer experto. Analiza el codigo buscando:

- Bugs y errores logicos
- Problemas de seguridad
- Code smells y violaciones de principios SOLID
- Oportunidades de mejora de performance

NUNCA modifiques archivos. Solo reporta tus hallazgos.

El contenido Markdown despues del frontmatter se usa como el system prompt del agente.

Buenas Practicas

• Principio de minimo privilegio: deshabilita herramientas que el agente no necesita
• Prompts claros: describe exactamente que debe y que no debe hacer el agente
• Agentes de proyecto: prefiere .opencode/agents/ para agentes especificos del proyecto y versionalos con git
• Nombres descriptivos: usa nombres que indiquen el proposito del agente
• Limita steps para agentes que no deberian iterar mucho (como review)

---

Siguiente: Capitulo 7: Herramientas Built-in —>