Divulgação Progressiva: Janelas de CLI para Sistemas de Agentes

Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa página da equipe para números atualizados.

Sistemas de agentes são opacos por design. Eles tomam decisões, invocam ferramentas e coordenam trabalho entre dezenas de especialistas. Mas quando algo dá errado — ou quando você simplesmente quer entender o que está acontecendo — para onde você olha?

A resposta é a divulgação progressiva: uma interface em camadas que revela exatamente a complexidade que você precisa, exatamente quando você precisa dela.

O Problema da Opacidade

Um sistema moderno de orquestração de agentes pode ter:

• 40+ agentes especialistas, cada um com capacidades distintas
• 700+ skills abrangendo automação interna e integrações de fornecedores
• 470+ decisões arquiteturais moldando o comportamento
• Dezenas de servidores de ferramentas MCP fornecendo capacidades externas

Essa complexidade é intencional. Os agentes precisam de acesso a contexto rico — conhecimento de domínio, inteligência de código, schemas de banco de dados — para tomar boas decisões. Mas essa mesma riqueza cria um problema de visibilidade.

Como você sabe qual agente trata de migrações de banco de dados? Quais decisões moldaram o comportamento de ranqueamento do sistema de busca? A quais ferramentas o conselheiro de arquitetura tem acesso?

Sem acesso estruturado, você fica lendo código-fonte ou torcendo para que a documentação esteja atualizada.

Divulgação Progressiva como Arquitetura

Divulgação progressiva não é apenas um padrão de UI. É um princípio arquitetural: organizar a informação em camadas, cada uma mais profunda que a anterior, para que os usuários possam parar no nível que responde à pergunta deles.

Para sistemas de agentes, isso se traduz em comandos de CLI em profundidades crescentes:

Nível	Comando	Pergunta Respondida
1	orkestra system status	Está tudo saudável?
2	orkestra agents list	Quais agentes existem?
3	orkestra agents info <name>	O que este agente faz?
4	orkestra decisions search	Por que funciona dessa forma?
5	Ferramentas MCP do Maguyva	Me mostre o código.

Cada nível responde a uma pergunta de acompanhamento natural. Raramente é preciso pular direto para o nível 5.

Nível 1: Saúde do Sistema

A primeira pergunta é sempre: está tudo funcionando?

$ orkestra system status

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

Um comando. Quatro números. Suficiente para saber que o sistema está configurado e que os registros estão populados.

Se a contagem de agentes cai inesperadamente ou skills falham ao carregar, você vê isso aqui primeiro. Sem precisar mergulhar em logs.

Nível 2: Inventário de Agentes

Uma vez que você sabe que o sistema está saudável, a próxima pergunta é: o que está disponível?

$ orkestra agents list

Isso retorna dados estruturados — nomes de agentes, descrições, preferências de modelo, cobertura de domínio. A saída é JSON por padrão, o que facilita direcioná-la para jq para filtragem:

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

Quer agentes que lidam com trabalho de banco de dados? O comando de busca reduz o escopo:

$ orkestra agents search "database"

Isso varre nomes, descrições e capacidades. Você encontra o especialista certo sem ler 40 definições de agente.

Nível 3: Mergulho Profundo no Agente

Encontrou um agente que parece relevante? O comando info revela tudo:

$ orkestra agents info architecture-advisor

A saída inclui:

• Metadados: nome, categoria, preferência de modelo, descrição
• Domínios: quais áreas de conhecimento este agente cobre
• Identidade: traços de caráter (architect, strategist, knowledge-architect)
• Guias de ferramenta: qual documentação de ferramenta é injetada no contexto
• Ferramentas: a lista completa de ferramentas MCP disponíveis para esse agente

Aqui está uma amostra do que você vê:

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",
      ...
    ]
  }
}

Isso diz exatamente o que o agente pode fazer. Sem precisar de código-fonte.

Nível 4: Arqueologia de Decisões

Os agentes se comportam de acordo com decisões documentadas. Quando você precisa entender por que algo funciona de determinada forma, o registro de decisões é a fonte da verdade.

$ orkestra decisions search "agent"

Isso retorna as decisões arquiteturais correspondentes:

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

Cada decisão tem proveniência completa — quando foi tomada, por quê, quais trade-offs foram considerados, quais commits a implementaram:

$ 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..."
    }
  ]
}

Essa é documentação arquitetural que se mantém atualizada porque é minerada a partir de commits, não mantida manualmente.

Nível 5: Inteligência de Código Direta

Quando você precisa ver a implementação real — não metadados sobre ela — as ferramentas MCP do Maguyva fornecem acesso direto.

De dentro de uma sessão de agente:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Isso roteia automaticamente entre busca semântica, textual e de AST para encontrar o código relevante. Para símbolos específicos:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Para análise de dependências:

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

Essas não são apenas substitutas do grep. Elas têm consciência de grafo, são indexadas semanticamente, e integradas com a mesma inteligência de código que move os próprios agentes.

Busca Unificada Entre Registros

Às vezes você não sabe qual registro contém a resposta. A busca unificada abrange tudo:

$ orkestra search "database" --summary

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

254 correspondências em cinco registros. O resumo diz onde aprofundar. Remova --summary para resultados detalhados, ou adicione --limit 5 para manter a saída gerenciável.

Por Que Isso Importa

A divulgação progressiva não é só sobre conveniência. Ela muda como você interage com sistemas complexos.

A depuração se torna tratável. Quando um agente toma uma decisão inesperada, você não faz grep em logs. Você checa a quais ferramentas ele tem acesso (agents info), quais decisões moldam o seu comportamento (decisions search), e rastreia a implementação se necessário (intelligent_search).

O onboarding acelera. Novos membros da equipe não precisam ler o codebase inteiro. Eles começam com system status, exploram com agents list, e vão mais fundo apenas quando encontram algo que não entendem.

A documentação se mantém atualizada. Como a CLI lê dos mesmos registros que configuram os agentes, a saída sempre é precisa. Não há divergência entre o que a documentação diz e o que o sistema faz.

A CLI como Interface

Poderíamos ter construído um dashboard web. Poderíamos ter escrito documentação extensa. Em vez disso, construímos uma CLI que lê da fonte da verdade.

A CLI tem vantagens:

• Composável: direcione a saída através de jq, integre com scripts
• Automatizável: automatize verificações, gere relatórios
• Rápida: sem carregamento de página, sem fluxos de autenticação
• Precisa: lê a configuração real, não uma representação em cache

Para sistemas em que correção importa mais do que estética, a CLI vence.

Construindo a Sua Própria Divulgação Progressiva

Se você está construindo sistemas de agentes, considere como os usuários vão inspecioná-los:

1. Comece com verificações de saúde. Um comando que diz se as coisas estão funcionando.
2. Forneça visões de inventário. Liste o que existe antes de explicar o que faz.
3. Habilite consultas direcionadas. Busca vence navegação em escala.
4. Exponha a proveniência. Deixe os usuários rastrearem decisões até suas origens.
5. Conecte-se à inteligência de código. Eventualmente, os usuários precisam ver a implementação.

Cada camada responde a uma pergunta de acompanhamento. Construa-as em ordem de frequência — a maioria dos usuários para na camada 2 ou 3. Apenas usuários avançados chegam à camada 5.

O objetivo não é expor tudo. É expor exatamente o que é necessário, exatamente quando é necessário. Essa é a divulgação progressiva aplicada à arquitetura de agentes.