Orkestra: orquestando agentes de IA a gran escala

Las cifras de esta publicación reflejan el sistema al momento de su publicación (enero de 2026). Consulta nuestra página del equipo para ver las cifras actuales.

Cuando empezamos a construir con Claude Code, nos topamos con un problema que todo equipo que usa asistentes de codificación con IA termina enfrentando: un solo agente no puede hacer todo bien.

Puedes indicarle a un agente que sea un especialista en bases de datos. O un auditor de seguridad. O un ingeniero de frontend. Pero en el momento en que le pides ser los tres a la vez, la calidad sufre. El contexto se diluye. Las instrucciones entran en conflicto. El agente se convierte en un generalista que es mediocre en todo.

Así que construimos Orkestra.

¿Qué es Orkestra?

Orkestra es un sistema de orquestación de agentes para Claude Code y herramientas de codificación con IA similares. Coordina múltiples agentes especializados, cada uno con experticia distinta, bajo un único orquestador que enruta el trabajo hacia el especialista correcto.

Piénsalo como una agencia de personal para agentes de IA. El orquestador recibe una tarea, identifica qué especialista debería encargarse de ella, y delega con el contexto correcto. Cuando el trabajo está terminado, los resultados vuelven al orquestador para su síntesis.

Los números cuentan la historia:

Componente	Cantidad
Agentes especialistas	46
Skills reutilizables	466
Arquetipos de identidad	27
Mentalidades	11
Estilos de comunicación	10
Dominios de conocimiento	21

El sistema de personajes: D&D para agentes

La idea central detrás de Orkestra es que el comportamiento de un agente emerge de tres primitivas componibles:

Identidad define qué es el agente. Un arquitecto diseña estructuras de sistemas. Un depurador rastrea fallos hasta sus causas raíz. Un guardián hace cumplir el cumplimiento normativo y los límites de seguridad. Tenemos 27 arquetipos de identidad que se pueden combinar.

Mentalidad define cómo piensa el agente. Una mentalidad analítica fundamenta las afirmaciones en evidencia y cuantifica la incertidumbre. Una mentalidad escéptica cuestiona los supuestos y busca evidencia que los desmienta. Una mentalidad exploratoria abraza la ambigüedad y prueba múltiples enfoques.

Estilo define cómo se comunica el agente. Un estilo técnico incluye valores exactos y hace referencia a archivos específicos. Un estilo conciso elimina el relleno y va directo a la respuesta. Un estilo diplomático equilibra la honestidad con el tacto.

Un agente combina estas primitivas:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Esta composición crea un agente que diseña sistemas (architect), conecta conocimiento entre dominios (knowledge-architect), fija la dirección estratégica (strategist), piensa en evidencia y datos (analytical), y se comunica sin relleno (concise).

El poder está en la explosión combinatoria. 27 identidades por 11 mentalidades por 10 estilos arrojan casi 3,000 personalidades de agente posibles. Pero solo defines las combinaciones que importan para tu trabajo.

Skills: módulos de capacidades reutilizables

Las skills son el conocimiento y los flujos de trabajo que los agentes pueden invocar. Siguen un sistema por niveles basado en el alcance:

Nivel	Nombre	Alcance	Ejemplo
K0	Fundamentos	Metodología universal	Disciplina test-first, finalización basada en evidencia
K1	Identidades	Flujos basados en rol	Estándares de interfaz CLI, guía de rendimiento
K2	Dominios	Conocimiento específico de dominio	Patrones de migración de bases de datos, validación de autenticación
K3	Stacks	Específico de tecnología	Despliegue en Cloudflare, operaciones de Supabase
K4	Proyecto	Solo esta base de código	Flujos y convenciones específicos del proyecto

Las skills se cargan de forma perezosa (lazy-loaded). Un agente ve los nombres y descripciones de las skills al iniciar, pero el contenido completo de una skill solo se carga cuando se activa. Esto mantiene el contexto ligero mientras hace que cientos de skills sean descubribles.

Cada skill incluye:

• Condiciones de activación claras («Usar al migrar esquemas de bases de datos»)
• Guía paso a paso
• Herramientas permitidas para el flujo de trabajo
• Criterios de éxito y rutas de recuperación ante fallos

Las 466 skills de nuestro registro cubren de todo, desde el aislamiento de worktrees de Git hasta flujos de investigación web y validación de salud de despliegues.

Por qué importa la orquestación

Las arquitecturas de un solo agente chocan con paredes rápidamente:

Dilución de contexto. Una ventana de contexto de 200k tokens suena grande hasta que cargas esquemas de bases de datos, documentación de API, fixtures de pruebas y conocimiento de dominio. Los especialistas pueden trabajar con contexto acotado.

Conflictos de instrucciones. Decirle a un agente que sea «minucioso pero rápido» y que «verifique todo pero sin sobrediseñar» crea tensión. Los especialistas resuelven esto teniendo un alcance claro.

Profundidad de experticia. Un agente generalista sabe un poco de todo. Un agente especialista, compuesto con la identidad y las skills correctas, conoce su dominio a fondo.

Orkestra implementa una orquestación plana: un orquestador coordina múltiples especialistas. Los especialistas no pueden generar subespecialistas. Esto evita una explosión de complejidad mientras habilita el trabajo en paralelo.

El orquestador tiene acceso a 2.2 millones de tokens de capacidad efectiva: su propia ventana de 200k más 10 subagentes concurrentes con 200k cada uno. Trabajo que agotaría a un solo agente corre cómodamente a través de la flota.

El pipeline de renderizado

Las definiciones de agentes viven en YAML. Claude Code lee Markdown. Orkestra tiende un puente sobre esa brecha con un pipeline de renderizado determinista:

YAML Registries → Jinja Templates → .claude/agents/*.md

Los operadores editan la fuente YAML. Ejecutan orkestra sync. El Markdown renderizado aparece en .claude/agents/. Claude Code recoge los cambios.

Esta separación sirve a audiencias distintas:

• La fuente YAML incluye metadatos de ciclo de vida, etiquetas, reglas de validación y notas de desuso para las herramientas
• El Markdown renderizado incluye solo lo que el modelo necesita: descripción, herramientas, skills y guía de comportamiento

El pipeline compone identidades, mentalidades, estilos y skills en un solo prompt coherente. Un agente architect-analytical-concise recibe un system prompt muy distinto al de un agente debugger-skeptical-technical, incluso si comparten algunas skills subyacentes.

Conocimiento de dominio: el patrón de cuatro archivos

Cada dominio de conocimiento sigue una estructura consistente:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Esta estructura sirve para la carga de contexto de los agentes. Un agente que trabaja en autenticación carga authentication/patterns.md para orientarse y authentication/anti-patterns.md para evitar errores conocidos. Los archivos tienen un tamaño pensado para una carga de contexto eficiente: lo bastante enfocados para ser útiles, lo bastante completos para ser autoritativos.

Mantenemos 21 dominios de nivel superior que incluyen analítica, autenticación, ciencia de datos, infraestructura, machine learning, rendimiento, seguridad y más. Cada dominio puede tener subdominios para una granularidad más fina.

Valores: el sistema operativo

Todos los agentes comparten una capa base de valores que define cómo operan:

La simplicidad primero. Usa la solución más simple que funcione. Agrega complejidad solo cuando esté justificada.

Corrige las causas raíz. Nunca parches alrededor de los fallos. Si un pipeline falla, depura el pipeline. Si una prueba falla, corrige el código o la prueba.

Basado en evidencia. Etiqueta las afirmaciones como «verificadas» (con benchmarks) o «estimadas» (con supuestos). Un patrón detectado no equivale a un problema confirmado.

Economía de contexto. Las herramientas MCP cuestan 0.1% del contexto. Las lecturas de archivos cuestan 2% cada una. Aplica experticia de dominio antes de explorar el código.

Estos valores se propagan a cada especialista a través del pipeline de renderizado. Un agente no puede eludirlos mediante composición.

CLI: el plano de control

Orkestra viene con una CLI para gestionar el ecosistema de agentes:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

La CLI es la fuente de verdad sobre qué agentes existen, qué skills tienen, y si el sistema está sano. Ejecuta la validación antes de la sincronización para detectar problemas temprano.

Consideraciones sobre código abierto

Construimos Orkestra para resolver nuestro propio problema: coordinar agentes de IA a gran escala para una base de código compleja. Los patrones que descubrimos no son específicos de nuestro dominio.

El sistema de composición de personajes (identidad + mentalidad + estilo) aplica a cualquier equipo que defina personalidades de agentes.

El sistema de niveles de skills (K0-K4) ofrece un modelo mental para organizar capacidades reutilizables por alcance.

El patrón del pipeline de renderizado (fuente YAML + plantillas + artefactos generados) separa las responsabilidades entre las herramientas y el consumo del modelo.

El modelo de orquestación plana (un coordinador, muchos especialistas) evita la complejidad mientras habilita el paralelismo.

Si Orkestra se vuelve código abierto depende de si estos patrones tienen valor para otros que construyen con Claude Code. Si estás chocando con las paredes que describimos, la arquitectura podría ayudar.

Lo que aprendimos

Construir Orkestra nos enseñó que la orquestación no se trata de hacer a los agentes más inteligentes. Se trata de hacerlos más enfocados.

Un solo agente con instrucciones perfectas de todas formas se queda sin contexto. Un solo agente con todas las skills de todas formas se confunde sobre cuál aplicar. Un solo agente que intenta ser todo produce resultados mediocres en todas partes.

Cuarenta especialistas, cada uno excelente en su dominio, coordinados por un orquestador que sabe cuándo delegar: así es como lanzamos.

Los números importan menos que la arquitectura. Podrías necesitar cinco agentes o cincuenta. El principio se mantiene: composición sobre capacidad, especialización sobre generalización, coordinación sobre heroísmos individuales.

---

Orkestra impulsa el ecosistema de agentes detrás de Maguyva, nuestra plataforma de inteligencia de código. ¿Quieres saber más? Contacta al equipo.