Saltearse al contenido
OpenCode
HomeDocs

Agents

Configure y use agentes especializados.

Los agentes son asistentes de IA especializados que se pueden configurar para tareas y flujos de trabajo especificos. Le permiten crear herramientas enfocadas con avisos personalizados, modelos y acceso a herramientas.

Puede cambiar entre agentes durante una sesion o invocarlos con la mencion @.

Tipos

Hay dos tipos de agentes en OpenCode; agentes primarios y subagentes.

Agentes primarios

Los agentes primarios son los asistentes principales con los que interactua directamente. Puede cycling a traves de ellos usando la tecla Tab o su enlace de teclado switch_agent configurado. Estos agentes manejan su conversacion principal y pueden acceder a todas las herramientas configuradas.

OpenCode viene con dos agentes primarios integrados, Build y Plan. Los veremos a continuacion.

Subagentes

Los subagentes son asistentes especializados que los agentes primarios pueden invocar para tareas especificas. Tambien puede invocarlos manualmente @ mencionandolos en sus mensajes.

OpenCode viene con dos subagentes integrados, General y Explore. Veremos esto a continuacion.

Integrados

OpenCode viene con dos agentes primarios integrados y dos subagentes integrados.

Build

Modo: primary

Build es el agente primario por defecto con todas las herramientas habilitadas. Este es el agente estandar para trabajo de desarrollo donde necesita acceso completo a operaciones de archivos y comandos del sistema.

Plan

Modo: primary

Un agente restringido diseñado para planificacion y analisis. Usamos un sistema de permisos para darle mas control y prevenir cambios no deseados. Por defecto, todo lo siguiente esta configurado en ask:

  • ediciones de archivos: Todas las escrituras, parches y ediciones
  • bash: Todos los comandos bash

Este agente es util cuando desea que el LLM analice el codigo, sugiera cambios o cree planes sin hacer cambios reales en su base de codigo.

General

Modo: subagent

Un agente de proposito general para investigar preguntas complejas, buscar codigo y ejecutar tareas de multiples pasos. Use al buscar palabras clave o archivos y no esta seguro de encontrar la coincidencia correcta en los primeros intentos.

Explore

Modo: subagent

Un agente rapido especializado en explorar bases de codigo. Use esto cuando necesite encontrar archivos rapidamente por patrones, buscar codigo por palabras clave o responder preguntas sobre la base de codigo.

Uso

  1. Para agentes primarios, use la tecla Tab para cycling a traves de ellos durante una sesion. Tambien puede usar su enlace de teclado switch_agent configurado.

  2. Los subagentes se pueden invocar:

    • Automaticamente por agentes primarios para tareas especializadas basadas en sus descripciones.

    • Manualmente por @ mencionar un subagente en su mensaje. Por ejemplo.

      @general ayudame a buscar esta funcion

  3. Navegacion entre sesiones: Cuando los subagentes crean sus propias sesiones hijas, puede navegar entre la sesion principal y todas las sesiones hijas usando:

    • <Leader>+Right (o su enlace de teclado session_child_cycle configurado) para cycling hacia adelante a traves de parent -> child1 -> child2 -> … -> parent
    • <Leader>+Left (o su enlace de teclado session_child_cycle_reverse configurado) para cycling hacia atras a traves de parent <- child1 <- child2 <- … <- parent

    Esto le permite cambiar sin problemas entre la conversacion principal y el trabajo de subagente especializado.

Configurar

Puede personalizar los agentes integrados o crear los suyos propios a traves de la configuracion. Los agentes se pueden configurar de dos maneras:

JSON

Configure agentes en su archivo de configuracion opencode.json:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Revisa el codigo para mejores practicas y problemas potenciales",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "Eres un revisor de codigo. Enfocate en seguridad, rendimiento y mantenibilidad.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Tambien puede definir agentes usando archivos markdown. Colocalos en:

  • Global: ~/.config/opencode/agent/
  • Por proyecto: .opencode/agent/
~/.config/opencode/agent/review.md
---
description: Revisa el codigo para calidad y mejores practicas
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---


Estas en modo de revision de codigo. Enfocate en:


- Calidad de codigo y mejores practicas
- Bugs potenciales y casos extremos
- Implicaciones de rendimiento
- Consideraciones de seguridad


Proporciona comentarios constructivos sin hacer cambios directos.

El nombre del archivo markdown se convierte en el nombre del agente. Por ejemplo, review.md crea un agente review.

Opciones

Veamos estas opciones de configuracion en detalle.

Descripcion

Use la opcion description para proporcionar una breve descripcion de lo que hace el agente y cuando usarlo.

opencode.json
{
  "agent": {
    "review": {
      "description": "Revisa el codigo para mejores practicas y problemas potenciales"
    }
  }
}

Esta es una opcion de configuracion requerida.

Temperature

Controle la aleatoriedad y creatividad de las respuestas del LLM con la configuracion temperature.

Valores mas bajos hacen las respuestas mas enfocadas y deterministas, mientras que valores mas altos aumentan la creatividad y variabilidad.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Los valores de temperatura generalmente varian de 0.0 a 1.0:

  • 0.0-0.2: Respuestas muy enfocadas y deterministas, ideal para analisis de codigo y planificacion
  • 0.3-0.5: Respuestas equilibradas con cierta creatividad, bueno para tareas de desarrollo general
  • 0.6-1.0: Respuestas mas creativas y variadas, util para lluvia de ideas y exploracion
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Si no se especifica una temperatura, OpenCode usa valores predeterminados especificos del modelo; generalmente 0 para la mayoria de los modelos, 0.55 para modelos Qwen.

Pasos maximos

Controle el numero maximo de iteraciones de agente que un agente puede realizar antes de verse obligado a responder solo con texto. Esto permite a los usuarios que desean controlar los costos establecer un limite en las acciones del agente.

Si esto no se establece, el agente continuara iterando hasta que el modelo elija detenerse o el usuario interrumpa la sesion.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Razonamiento rapido con iteraciones limitadas",
      "prompt": "Eres un pensador rapido. Resuelve problemas con pasos minimos.",
      "maxSteps": 5
    }
  }
}

Cuando se alcanza el limite, el agente recibe un aviso del sistema especial instru yendole que responda con un resumen de su trabajo y tareas restantes recomendadas.

Deshabilitar

Establezca en true para deshabilitar el agente.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Especifique un archivo de aviso del sistema personalizado para este agente con la configuracion prompt. El archivo de aviso debe contener instrucciones especificas para el proposito del agente.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Esta ruta es relativa a donde se encuentra el archivo de configuracion. Asi que esto funciona tanto para la configuracion global de OpenCode como para la configuracion especifica del proyecto.

Modelo

Use la configuracion model para anular el modelo para este agente. Util para usar diferentes modelos optimizados para diferentes tareas. Por ejemplo, un modelo mas rapido para planificacion, un modelo mas capaz para implementacion.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

La ID del modelo en su configuracion de OpenCode usa el formato proveedor/id-modelo. Por ejemplo, si esta usando OpenCode Zen, usaria opencode/gpt-5.1-codex para GPT 5.1 Codex.

Herramientas

Controle que herramientas estan disponibles en este agente con la configuracion tools. Puede habilitar o deshabilitar herramientas especificas estableciendolas en true o false.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Tambien puede usar comodines para controlar multiples herramientas a la vez. Por ejemplo, para deshabilitar todas las herramientas de un servidor MCP:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Mas informacion sobre herramientas.

Permisos

Puede configurar permisos para administrar las acciones que un agente puede tomar. Actualmente, los permisos para las herramientas edit, bash y webfetch se pueden configurar para:

  • "ask" - Solicitar aprobacion antes de ejecutar la herramienta
  • "allow" - Permitir todas las operaciones sin aprobacion
  • "deny" - Deshabilitar la herramienta
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Puede anular estos permisos por agente.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Tambien puede establecer permisos en agentes Markdown.

~/.config/opencode/agent/review.md
---
description: Revision de codigo sin ediciones
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
  webfetch: deny
---


Solo analiza el codigo y sugiere cambios.

Puede establecer permisos para comandos bash especificos.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask"
        }
      }
    }
  }
}

Esto puede tomar un patron glob.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

Y tambien puede usar el comodin * para administrar permisos para todos los comandos. Dado que la ultima regla coincidente tiene prioridad, coloque el comodin * primero y las reglas especificas despues.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status": "allow"
        }
      }
    }
  }
}

Mas informacion sobre permisos.

Modo

Controle el modo del agente con la configuracion mode. La opcion mode se usa para determinar como se puede usar el agente.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

La opcion mode se puede establecer en primary, subagent o all. Si no se especifica un mode, el predeterminado es all.

Oculto

Oculte un subagente del menu de autocompletado @ con hidden: true. Util para subagentes internos que solo deben invocarse programaticamente por otros agentes a traves de la herramienta Task.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Esto solo afecta la visibilidad del usuario en el menu de autocompletado. Los agentes ocultos aun pueden ser invocados por el modelo a traves de la herramienta Task si los permisos lo permiten.

Permisos de tarea

Controle que subagentes puede invocar un agente a traves de la herramienta Task con permission.task. Usa patrones glob para coincidencia flexible.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Cuando se establece en deny, el subagente se elimina por completo de la descripcion de la herramienta Task, por lo que el modelo no intentara invocarlo.

Adicional

Cualquier otra opcion que especifique en su configuracion de agente se pasara directamente al proveedor como opciones de modelo. Esto le permite usar caracteristicas y parametros especificos del proveedor.

Por ejemplo, con los modelos de razonamiento de OpenAI, puede controlar el esfuerzo de razonamiento:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agente que usa alto esfuerzo de razonamiento para problemas complejos",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Estas opciones adicionales son especificas del modelo y proveedor. Consulte la documentacion de su proveedor para parametros disponibles.

Crear agentes

Puede crear nuevos agentes usando el siguiente comando:

Ventana de terminal
opencode agent create

Este comando interactivo:

  1. Preguntara donde guardar el agente; global o especifico del proyecto.
  2. Descripcion de lo que debe hacer el agente.
  3. Generara un aviso del sistema apropiado e identificador.
  4. Le permitira seleccionar a que herramientas puede acceder el agente.
  5. Finalmente, creara un archivo markdown con la configuracion del agente.

Casos de uso

Aqui hay algunos casos de uso comunes para diferentes agentes.

  • Agente Build: Trabajo de desarrollo completo con todas las herramientas habilitadas
  • Agente Plan: Analisis y planificacion sin hacer cambios
  • Agente Review: Revision de codigo con acceso de solo lectura mas herramientas de documentacion
  • Agente Debug: Enfocado en investigacion con herramientas bash y read habilitadas
  • Agente Docs: Escritura de documentacion con operaciones de archivo pero sin comandos del sistema

Ejemplos

Aqui hay algunos agentes de ejemplo que puede encontrar utiles.

Agente de documentacion

~/.config/opencode/agent/docs-writer.md
---
description: Escribe y mantiene la documentacion del proyecto
mode: subagent
tools:
  bash: false
---


Eres un escritor tecnico. Crea documentacion clara y completa.


Enfocate en:


- Explicaciones claras
- Estructura apropiada
- Ejemplos de codigo
- Lenguaje amigable para el usuario

Auditor de seguridad

~/.config/opencode/agent/security-auditor.md
---
description: Realiza auditorias de seguridad e identifica vulnerabilidades
mode: subagent
tools:
  write: false
  edit: false
---


Eres un experto en seguridad. Enfocate en identificar problemas de seguridad potenciales.


Busca:


- Vulnerabilidades de validacion de entrada
- Fallos de autenticacion y autorizacion
- Riesgos de exposicion de datos
- Vulnerabilidades de dependencias
- Problemas de seguridad de configuracion