# Divulgação Progressiva: Janelas de CLI para Sistemas de Agentes Canonical source: https://maguyva.ai/pt-br/blog/progressive-disclosure-cli-into-agents License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license). Date: 2026-01-20 · Author: Maguyva Team > Sistemas de agentes são opacos por padrão. A divulgação progressiva dá aos operadores visões em camadas via CLI, de verificações rápidas de status até os detalhes internos completos dos agentes e o rastreamento de decisões. > *Os números neste post refletem o sistema no momento da publicação (janeiro de 2026). Consulte nossa [página da equipe](/pt-br/team) 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 ` | 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? ```bash $ orkestra system status ``` ```json { "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? ```bash $ 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: ```bash $ 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: ```bash $ 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: Análise Detalhada do Agente Encontrou um agente que parece relevante? O comando `info` revela tudo: ```bash $ 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ê: ```jsonc { "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. ```bash $ orkestra decisions search "agent" ``` Isso retorna as decisões arquiteturais correspondentes: ```json { "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: ```bash $ orkestra decisions info DEC-SR-049 ``` ```json { "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 levam o grafo em conta, 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: ```bash $ orkestra search "database" --summary ``` ```json { "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 mais simples.** 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.** Mais cedo ou mais tarde, 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.