Divulgación progresiva: ventanas CLI hacia los sistemas de agentes

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.

Los sistemas de agentes son opacos por diseño. Toman decisiones, invocan herramientas y coordinan trabajo entre decenas de especialistas. Pero cuando algo sale mal, o cuando simplemente quieres entender qué está pasando, ¿dónde miras?

La respuesta es la divulgación progresiva: una interfaz en capas que revela exactamente tanta complejidad como necesitas, exactamente cuando la necesitas.

El problema de la opacidad

Un sistema moderno de orquestación de agentes puede tener:

• Más de 40 agentes especialistas, cada uno con capacidades distintas
• Más de 700 skills que abarcan automatización interna e integraciones con proveedores
• Más de 470 decisiones arquitectónicas que moldean el comportamiento
• Decenas de servidores de herramientas MCP que proporcionan capacidades externas

Esta complejidad es intencional. Los agentes necesitan acceso a contexto rico — conocimiento de dominio, inteligencia de código, esquemas de bases de datos — para tomar buenas decisiones. Pero esa misma riqueza crea un problema de visibilidad.

¿Cómo sabes qué agente maneja las migraciones de bases de datos? ¿Qué decisiones moldearon el comportamiento de clasificación del sistema de búsqueda? ¿A qué herramientas tiene acceso el asesor de arquitectura?

Sin acceso estructurado, te queda leer el código fuente o esperar que la documentación esté al día.

La divulgación progresiva como arquitectura

La divulgación progresiva no es solo un patrón de interfaz de usuario. Es un principio arquitectónico: organizar la información en capas, cada una más profunda que la anterior, para que los usuarios puedan detenerse en el nivel que responde su pregunta.

Para los sistemas de agentes, esto se traduce en comandos de CLI con profundidad creciente:

Nivel	Comando	Pregunta que responde
1	orkestra system status	¿Todo está sano?
2	orkestra agents list	¿Qué agentes existen?
3	orkestra agents info <name>	¿Qué hace este agente?
4	orkestra decisions search	¿Por qué funciona así?
5	Herramientas MCP de Maguyva	Muéstrame el código.

Cada nivel responde una pregunta de seguimiento natural. Rara vez necesitas saltar directo al nivel 5.

Nivel 1: salud del sistema

La primera pregunta siempre es: ¿todo está funcionando?

$ orkestra system status

on
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Un comando. Cuatro números. Suficiente para saber que el sistema está configurado y que los registros están poblados.

Si el conteo de agentes cae inesperadamente o las skills fallan al cargar, lo ves aquí primero. No hace falta bucear en los logs.

Nivel 2: inventario de agentes

Una vez que sabes que el sistema está sano, la siguiente pregunta es: ¿qué hay disponible?

$ orkestra agents list

Esto devuelve datos estructurados — nombres de agentes, descripciones, preferencias de modelo, cobertura de dominio. La salida es JSON por defecto, lo que facilita canalizarla hacia jq para filtrar:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

¿Quieres agentes que manejen trabajo de bases de datos? El comando de búsqueda lo acota:

$ orkestra agents search "database"

Esto escanea nombres, descripciones y capacidades. Encuentras al especialista correcto sin leer 40 definiciones de agentes.

Nivel 3: análisis profundo del agente

¿Encontraste un agente que parece relevante? El comando info lo revela todo:

$ orkestra agents info architecture-advisor

La salida incluye:

• Metadatos: nombre, categoría, preferencia de modelo, descripción
• Dominios: qué áreas de conocimiento cubre este agente
• Identidad: rasgos de carácter (architect, strategist, knowledge-architect)
• Guías de herramientas: qué documentación de herramientas se inyecta en el contexto
• Herramientas: la lista completa de herramientas MCP disponibles para este agente

Aquí tienes una muestra de lo que ves:

on
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Esto te dice exactamente qué puede hacer el agente. No hace falta leer el código fuente.

Nivel 4: arqueología de decisiones

Los agentes se comportan de acuerdo con decisiones documentadas. Cuando necesitas entender por qué algo funciona de una manera particular, el registro de decisiones es la fuente de verdad.

$ orkestra decisions search "agent"

Esto devuelve las decisiones arquitectónicas que coinciden:

on
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Cada decisión tiene procedencia completa — cuándo se tomó, por qué, qué compromisos se consideraron, qué commits la implementaron:

$ orkestra decisions info DEC-SR-049

on
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Esta es documentación arquitectónica que se mantiene al día porque se extrae de los commits, no se mantiene manualmente.

Nivel 5: inteligencia de código directa

Cuando necesitas ver la implementación real — no metadatos sobre ella — las herramientas MCP de Maguyva dan acceso directo.

Desde dentro de una sesión de agente:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Esto enruta automáticamente entre búsqueda semántica, de texto y AST para encontrar código relevante. Para símbolos específicos:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Para análisis de dependencias:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Estas no son solo reemplazos de grep. Tienen conciencia del grafo, están indexadas semánticamente, y están integradas con la misma inteligencia de código que impulsa a los propios agentes.

Búsqueda unificada entre registros

A veces no sabes qué registro tiene la respuesta. La búsqueda unificada abarca todo:

$ orkestra search "database" --summary

on
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 coincidencias en cinco registros. El resumen te dice dónde profundizar. Elimina --summary para resultados detallados, o agrega --limit 5 para mantener la salida manejable.

Por qué esto importa

La divulgación progresiva no se trata solo de conveniencia. Cambia cómo interactúas con sistemas complejos.

La depuración se vuelve manejable. Cuando un agente toma una decisión inesperada, no haces grep en los logs. Verificas a qué herramientas tiene acceso (agents info), qué decisiones moldean su comportamiento (decisions search), y rastreas la implementación si hace falta (intelligent_search).

La incorporación se acelera. Los nuevos integrantes del equipo no necesitan leer toda la base de código. Empiezan con system status, exploran con agents list, y profundizan solo cuando se topan con algo que no entienden.

La documentación se mantiene al día. Como la CLI lee de los mismos registros que configuran a los agentes, la salida siempre es precisa. No hay desfase entre lo que dice la documentación y lo que hace el sistema.

La CLI como interfaz

Podríamos haber construido un dashboard web. Podríamos haber escrito documentación extensa. En cambio, construimos una CLI que lee de la fuente de verdad.

La CLI tiene ventajas:

• Componible: canaliza la salida a través de jq, intégrala con scripts
• Automatizable: automatiza verificaciones, genera reportes
• Rápida: sin cargas de página, sin flujos de autenticación
• Precisa: lee la configuración real, no una representación en caché

Para sistemas donde la corrección importa más que la estética, la CLI gana.

Construyendo tu propia divulgación progresiva

Si estás construyendo sistemas de agentes, considera cómo los usuarios los van a inspeccionar:

1. Empieza con verificaciones de salud. Un comando que te diga si las cosas están funcionando.
2. Ofrece vistas de inventario. Lista lo que existe antes de explicar qué hace.
3. Habilita consultas dirigidas. La búsqueda le gana a la navegación a gran escala.
4. Expón la procedencia. Deja que los usuarios rastreen las decisiones hasta sus orígenes.
5. Conecta con la inteligencia de código. Eventualmente, los usuarios necesitan ver la implementación.

Cada capa responde una pregunta de seguimiento. Constrúyelas en orden de frecuencia — la mayoría de los usuarios se detienen en la capa 2 o 3. Solo los usuarios avanzados llegan a la capa 5.

El objetivo no es exponer todo. Es exponer exactamente lo necesario, exactamente cuando se necesita. Eso es la divulgación progresiva aplicada a la arquitectura de agentes.