Arquitectura de OpenCode: Agentes, Skills y MCP

Principiante⏱30 min📖6 min de lecturaLección 1 de 5

Arquitectura de OpenCode: Agentes, Skills y MCP

Comprende la arquitectura central de OpenCode: su sistema de agentes, framework de skills, protocolo MCP, configuración y registro de herramientas.

¿Qué es OpenCode?

OpenCode es un framework CLI de código abierto para ingeniería de software asistida por IA. Conecta modelos de lenguaje de gran tamaño (LLMs) con entornos de desarrollo a través de un sistema estructurado de agentes, skills y el Model Context Protocol (MCP).

ℹ️Nota

OpenCode se configura mediante un único archivo: opencode.json en la raíz del proyecto o .opencode/config.json dentro del directorio .opencode/. Ambas ubicaciones son equivalentes, aunque .opencode/config.json mantiene tu configuración aislada.

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

💡Consejo

Piensa en OpenCode como un sistema operativo para asistentes de codificación de IA. Los agentes son los usuarios, las skills son los programas instalados, los servidores MCP son dispositivos periféricos y los permisos son las políticas de seguridad.

Ciclo de Vida de la Solicitud

Cada interacción del usuario fluye a través de un pipeline bien definido. Comprender este ciclo de vida es crucial para la depuración y optimización.

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

💡Consejo

Cuando un agente se comporta inesperadamente, traza el ciclo de vida de la solicitud. A menudo el problema está en el sistema de permisos (una herramienta denegada) o en el enrutamiento de agentes (agente incorrecto seleccionado).

Visión General del Sistema de Agentes

Los agentes son asistentes basados en IA configurados con modelos, prompts y capacidades específicas. OpenCode soporta múltiples tipos de agentes:

Agente primario: El asistente de codificación principal que interactúa con el usuario
Subagentes: Agentes especializados (ej.: customize-opencode) para tareas específicas
Agentes personalizados: Agentes definidos por el usuario con configuraciones a medida

Cada agente opera dentro de un ámbito de permisos y tiene acceso a un conjunto definido de herramientas y skills.

⚠️Advertencia

Los subagentes heredan el ámbito de permisos del padre a menos que se sobrescriba explícitamente. Esto significa que un subagente con un padre poderoso podría realizar accidentalmente operaciones destructivas. Siempre revisa los permisos del subagente al delegar tareas sensibles.

Sistema de Skills

Las skills son paquetes reutilizables de instrucciones que enseñan a un agente cómo realizar tareas específicas. Una skill incluye:

Instrucciones: Guía en lenguaje natural para el agente
Herramientas: Definiciones opcionales de herramientas o restricciones
Recursos: Archivos empaquetados (scripts, plantillas, referencias)

Las skills se cargan automáticamente cuando un agente detecta un patrón de tarea correspondiente.

yaml

# skill.yaml
name: customize-opencode
description: Editar o crear configuración de OpenCode
instructions: |
  Cuando el usuario pida editar opencode.json o archivos de
  configuración relacionados, sigue estos pasos:
  1. Lee la configuración existente
  2. Valida la sintaxis JSON/YAML
  3. Aplica los cambios de forma segura
tools:
  - read
  - write
  - edit
resources:
  - schema/opencode-schema.json

bash

# Las skills se cargan automáticamente cuando la consulta coincide con la descripción
# Ejemplo: escribir "editar mi configuración opencode" activa customize-opencode
# También puedes forzar la carga con: opencode --skill customize-opencode

MCP (Model Context Protocol)

MCP es un protocolo estándar para conectar LLMs con herramientas externas y fuentes de datos. Permite que OpenCode se integre con:

Sistemas de archivos (locales y remotos)
Bases de datos (SQL, vectoriales)
APIs web (REST, GraphQL)
Servicios personalizados (herramientas internas)

Los servidores MCP se ejecutan como procesos separados y se comunican mediante JSON-RPC sobre stdin/stdout o HTTP.

Cómo Funciona la Comunicación MCP

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

json

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["mcp-server-fs.js"],
      "env": {
        "ALLOWED_PATHS": "/home/usuario/proyectos"
      }
    }
  }
}

📌Importante

Los servidores MCP son procesos de larga duración. Se inician cuando OpenCode se lanza y se apagan cuando la sesión termina. Los servidores con uso intensivo de recursos deben gestionarse cuidadosamente para evitar inflado de memoria.

Configuración mediante opencode.json

Todo el comportamiento de OpenCode se controla a través de opencode.json (o .opencode/config.json).

ℹ️Nota

El enfoque del directorio .opencode/ es preferido para proyectos en equipo porque puedes agregarlo a .gitignore selectivamente o versionar solo el archivo de configuración sin saturar la raíz del proyecto.

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Asistente principal de codificación"
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Especialista en revisión de código",
      "prompt": "Eres un revisor de código senior enfocado en seguridad y rendimiento."
    }
  },
  "skills": {
    "customize-opencode": {
      "manifest": "skills/customize-opencode/skill.yaml"
    },
    "react-component": {
      "manifest": "skills/react-component/skill.yaml",
      "autoLoad": true,
      "matchPattern": "react component|jsx"
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["mcp-server-fs.js", "/home/usuario/proyectos"]
    },
    "github": {
      "command": "node",
      "args": ["mcp-github-server.js"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  },
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pip *"],
      "deny": ["rm -rf /", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "docs/**"],
      "deny": [".env", "secrets/**"]
    }
  ],
  "agentRouting": {
    "mode": "auto",
    "defaultAgent": "default",
    "rules": [
      {
        "pattern": "seguridad|vulnerabilidad|CVE",
        "agent": "reviewer"
      }
    ]
  }
}

Registro de Herramientas

El registro de herramientas gestiona todas las herramientas disponibles y sus capacidades:

Herramienta	Propósito	Requiere Permiso	Categoría
`bash`	Ejecutar comandos shell	Sí	Ejecución
`read`	Leer archivos	No	Lectura
`write`	Escribir archivos	Sí	Escritura
`edit`	Editar archivos	Sí	Escritura
`grep`	Buscar contenido	No	Lectura
`glob`	Buscar archivos por patrón	No	Lectura
`webfetch`	Obtener URLs	Opcional	Red
`websearch`	Buscar en la web	Opcional	Red
`task`	Delegar a subagente/skill	Sí	Orquestación
`question`	Preguntar al usuario	No	Interacción

⚠️Advertencia

Las herramientas marcadas como "Opcional" para permisos pueden usarse sin reglas, pero su comportamiento puede estar restringido. Por ejemplo, webfetch sin reglas allow puede limitarse a ciertos dominios.

typescript

// Las herramientas se registran programáticamente en el SDK de OpenCode
import { ToolRegistry } from "opencode";

const registry = new ToolRegistry();

registry.register({
  name: "bash",
  description: "Ejecutar comandos shell",
  requiresPermission: true,
  handler: async (args: { command: string }) => {
    // Lógica de ejecución con verificaciones de permisos
  }
});

registry.register({
  name: "grep",
  description: "Buscar contenido con regex",
  requiresPermission: false,
  handler: async (args: { pattern: string; path?: string }) => {
    // Lógica de búsqueda
  }
});

Sistema de Permisos

Los permisos controlan qué acciones pueden realizar los agentes. Las reglas se definen en opencode.json:

json

{
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *"],
      "deny": ["rm -rf *", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "docs/**"],
      "deny": [".env", "secrets/**"]
    }
  ]
}

⚠️Advertencia

Las reglas de permiso se evalúan en orden: las reglas deny se verifican primero, luego las reglas allow. Si un comando coincide tanto con un patrón allow como deny, la regla deny tiene prioridad. Esto evita desvíos accidentales a través de patrones superpuestos.

Comparación: Agentes vs Skills vs Plugins

Aspecto	Agente	Skill	Plugin (MCP)
Propósito	Instancia de asistente	Paquete de instrucciones	Herramienta/servicio externo
Config	`opencode.json`	Manifiesto YAML/JSON	Entrada MCP en config
Ciclo	Basado en sesión	Carga bajo demanda	Proceso de larga duración
Ámbito	Conversación completa	Tarea específica	Acceso a herramientas
Lenguaje	Dependiente del modelo	Lenguaje natural	Cualquiera (Node, Python, Go)
Estado	Stateful (conversación)	Stateless (instrucciones)	Stateful (proceso)
Ejemplo	Agente de codificación	`customize-opencode`	Servidor MCP filesystem
Dependencias	Ninguna	Ninguna (autocontenido)	Runtime (Node, Python, etc.)

💡Consejo

Elige un agente cuando necesites un compañero de conversación persistente con experiencia específica. Elige una skill cuando quieras enseñar a cualquier agente un procedimiento repetible. Elige un plugin cuando necesites conectarte a un sistema o API externa.