Creando y Configurando Agentes Personalizados

Intermedio⏱45 min📖5 min de lecturaLección 2 de 5

Creando y Configurando Agentes Personalizados

Aprende a configurar agentes personalizados en opencode.json, especificando modelos, descripciones, prompts, subagentes, enrutamiento y restricciones.

Configuración de Agentes en opencode.json

Los agentes personalizados se definen en la sección agents de opencode.json. Cada entrada de agente especifica el modelo, comportamiento y capacidades para ese asistente.

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Asistente de codificación de uso general"
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Especialista en revisión de código",
      "prompt": "Eres un revisor de código senior. Enfócate en seguridad, rendimiento y legibilidad."
    }
  }
}

💡Consejo

Usa nombres y descripciones de agentes descriptivos: sirven como el mecanismo principal de enrutamiento. Un agente bien nombrado como "security-auditor" con una descripción clara es más fácil de seleccionar tanto para humanos como para el sistema de enrutamiento.

Flujo de Decisión de Enrutamiento de Agentes

Entender cómo OpenCode decide qué agente maneja una solicitud es clave para diseñar configuraciones multi-agente efectivas.

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

ℹ️Nota

El enrutamiento de agentes usa coincidencia difusa de descripción por defecto. Si necesitas control preciso, usa agentRouting.rules con patrones regex explícitos para garantizar que solicitudes específicas vayan a agentes específicos.

Especificando Modelos

Cada agente puede usar un LLM diferente. OpenCode soporta múltiples proveedores de modelo:

json

{
  "agents": {
    "frontend": {
      "model": "gpt-4o",
      "description": "Agente de desarrollo frontend — React, CSS, TypeScript"
    },
    "backend": {
      "model": "claude-sonnet-4-20250514",
      "description": "Agente de arquitectura backend — APIs, bases de datos, servicios"
    },
    "fast-prototype": {
      "model": "gpt-4o-mini",
      "description": "Prototipado rápido — menor costo, respuestas más rápidas"
    }
  }
}

💡Consejo

Elegir el modelo correcto es un equilibrio entre capacidad, costo y velocidad. Usa gpt-4o-mini o modelos pequeños similares para tareas rutinarias (linting, refactorizaciones simples) y reserva modelos premium para razonamiento complejo (diseño de arquitectura, auditorías de seguridad).

Esquema de Configuración de Agente

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

Definiendo Descripciones de Agentes

Las descripciones ayudan a OpenCode a enrutar tareas al agente correcto. Actúan como metadatos para la selección de agentes.

json

{
  "agents": {
    "docs-writer": {
      "model": "gpt-4o",
      "description": "Especialista en escribir documentación, READMEs y referencias de API"
    },
    "test-generator": {
      "model": "gpt-4o",
      "description": "Crea pruebas unitarias, pruebas de integración y fixtures de prueba"
    }
  }
}

📌Importante

Las descripciones de los agentes no son solo documentación: se usan activamente en tiempo de ejecución para enrutamiento. Una descripción vaga como "ayuda con codificación" puede hacer que las solicitudes se enruten incorrectamente. Sé específico: "Maneja diseño de esquema de base de datos y optimización SQL."

Prompts de Agentes

Los prompts definen el mensaje del sistema y las instrucciones de comportamiento para un agente.

json

{
  "agents": {
    "security-auditor": {
      "model": "claude-opus-4-20250514",
      "description": "Auditor de código enfocado en seguridad",
      "prompt": "Eres un auditor de seguridad. Identifica vulnerabilidades, sugiere correcciones y explica riesgos. Prioriza issues OWASP Top 10. Siempre verifica: SQL injection, XSS, CSRF, deserialización insegura y dependencias vulnerables conocidas."
    },
    "code-formatter": {
      "model": "gpt-4o-mini",
      "description": "Formatea código según guías de estilo del proyecto",
      "prompt": "Formateas código según la guía de estilo del proyecto. Nunca cambies la lógica — solo espacios, indentación y reglas de formato. Ejecuta el linter después de formatear para verificar cumplimiento."
    }
  }
}

⚠️Advertencia

Los prompts de agente se inyectan en el mensaje del sistema de la llamada LLM. La inyección maliciosa de prompts en configuraciones compartidas podría alterar el comportamiento del agente. Siempre revisa el contenido del prompt de fuentes no confiables, especialmente cuando el agente tiene permisos amplios.

typescript

// Los agentes pueden personalizarse programáticamente mediante el SDK de OpenCode
import { OpenCode } from "opencode";

const opencode = new OpenCode();

opencode.registerAgent({
  name: "security-auditor",
  model: "claude-opus-4-20250514",
  description: "Auditor de código enfocado en seguridad",
  prompt: `Eres un auditor de seguridad. Enfócate en OWASP Top 10.`,
  constraints: {
    allowedTools: ["read", "grep", "glob", "bash"],
    deniedTools: ["write", "edit"],
    temperature: 0.3
  }
});

await opencode.run();

Tipos de Subagentes

Los subagentes son agentes anidados que manejan subtareas especializadas. Se invocan cuando un agente primario delega trabajo.

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Asistente principal de codificación — orquesta flujos complejos",
      "subagents": {
        "customize-opencode": {
          "model": "gpt-4o",
          "description": "Maneja cambios en la configuración de OpenCode"
        },
        "deployment": {
          "model": "gpt-4o-mini",
          "description": "Gestiona pipelines de despliegue y CI/CD",
          "prompt": "Eres un ingeniero de despliegue. Siempre verifica el destino del despliegue antes de proceder."
        }
      }
    }
  }
}

⚠️Advertencia

Los subagentes heredan el ámbito de permisos del padre a menos que se sobrescriba explícitamente. Siempre revisa los permisos del subagente al delegar operaciones sensibles. Un subagente de escritura de código no debería tener acceso a herramientas de despliegue de producción a menos que sea específicamente intencionado.

Enrutamiento de Agentes

El enrutamiento de agentes controla cómo se despachan las tareas al agente apropiado. OpenCode usa coincidencia basada en descripción para seleccionar el mejor agente para una tarea determinada.

json

{
  "agentRouting": {
    "mode": "auto",
    "defaultAgent": "default",
    "rules": [
      {
        "pattern": "seguridad|vulnerabilidad|CVE|OWASP",
        "agent": "security-auditor"
      },
      {
        "pattern": "documentación|readme|docs api|wiki",
        "agent": "docs-writer"
      },
      {
        "pattern": "despliegue|release|CI/CD|pipeline",
        "agent": "deployment"
      },
      {
        "pattern": "prueba|prueba unitaria|prueba integración|jest|pytest",
        "agent": "test-generator"
      }
    ]
  }
}

📌Importante

Las reglas de enrutamiento se evalúan en orden. La primera regla coincidente gana. Coloca reglas más específicas antes que las generales. Por ejemplo, una regla que coincide con "despliegue producción" debería venir antes de una regla genérica "despliegue".

Restricciones de Agentes

Las restricciones limitan lo que un agente puede hacer, previniendo mal uso o daños accidentales.

json

{
  "agents": {
    "sandboxed": {
      "model": "gpt-4o-mini",
      "description": "Agente restringido para experimentación segura",
      "constraints": {
        "maxTokens": 4096,
        "allowedTools": ["read", "grep", "glob", "websearch"],
        "deniedTools": ["bash", "write", "edit"],
        "maxFileSize": 1048576,
        "temperature": 0.7
      }
    },
    "production-deployer": {
      "model": "gpt-4o",
      "description": "Agente de despliegue de producción — requiere aprobación",
      "constraints": {
        "allowedTools": ["bash", "read", "glob"],
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}

💡Consejo

Usa restricciones de temperature para controlar la creatividad del agente. Valores bajos (0.1 to 0.3) producen salidas determinísticas y enfocadas, ideales para revisión de código y despliegue. Valores más altos (0.7 to 1.0) fomentan soluciones creativas para lluvia de ideas y diseño de arquitectura.

Comparación: Opciones de Configuración de Agentes

Opción	Tipo	Obligatorio	Valor Pred.	Descripción
`model`	string	Sí	:	Identificador del modelo (ej.: `gpt-4o`)
`description`	string	Sí	:	Descripción para enrutamiento
`prompt`	string	No	Prompt por def.	Mensaje del sistema / instrucciones
`subagents`	object	No	`{}`	Agentes especializados anidados
`constraints`	object	No	`{}`	Límites de recursos y herramientas
`allowedTools`	string[]	No	Todas	Lista blanca de herramientas permitidas
`deniedTools`	string[]	No	`[]`	Lista negra de herramientas prohibidas
`maxTokens`	integer	No	Por defecto	Máximo de tokens de respuesta
`temperature`	float	No	Por defecto	Aleatoriedad de respuesta (0.0 to 2.0)
`maxFileSize`	integer	No	10MB	Tamaño máximo de archivo que el agente lee

📌Importante

allowedTools y deniedTools son patrones mutuamente excluyentes. Si especificas allowedTools, todas las demás herramientas están implícitamente denegadas. Si especificas deniedTools, todas las herramientas excepto las listadas están implícitamente permitidas. No uses ambos en el mismo bloque de restricciones: el comportamiento es indefinido.