# Progressive disclosure: finestre CLI sui sistemi ad agenti Canonical source: https://maguyva.ai/it/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 > I sistemi ad agenti sono opachi per default. La progressive disclosure offre agli operatori viste CLI a livelli, dai controlli rapidi di stato fino ai dettagli interni completi degli agenti e alle tracce delle decisioni. > *I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra [pagina del team](/it/team) per le cifre attuali.* I sistemi ad agenti sono opachi per design. Prendono decisioni, invocano strumenti, e coordinano lavoro attraverso dozzine di specialisti. Ma quando qualcosa va storto — o quando semplicemente vuoi capire cosa sta succedendo — dove guardi? La risposta è la progressive disclosure: un'interfaccia a livelli che rivela esattamente tanta complessità quanta te ne serve, esattamente quando ti serve. ## Il problema dell'opacità Un moderno sistema di orchestrazione ad agenti potrebbe avere: - 40+ agenti specialisti, ciascuno con capacità distinte - 700+ skill che spaziano tra automazione interna e integrazioni con vendor - 470+ decisioni architetturali che plasmano il comportamento - Dozzine di server di strumenti MCP che forniscono capacità esterne Questa complessità è intenzionale. Gli agenti hanno bisogno di accesso a un contesto ricco — conoscenza di dominio, intelligenza del codice, schemi di database — per prendere buone decisioni. Ma quella stessa ricchezza crea un problema di visibilità. Come fai a sapere quale agente gestisce le migrazioni di database? Quali decisioni hanno plasmato il comportamento di ranking del sistema di ricerca? A quali strumenti ha accesso il consulente di architettura? Senza un accesso strutturato, ti ritrovi a leggere il codice sorgente o a sperare che la documentazione sia aggiornata. ## La progressive disclosure come architettura La progressive disclosure non è solo un pattern di UI. È un principio architetturale: organizza le informazioni in livelli, ciascuno più profondo del precedente, così gli utenti possono fermarsi al livello che risponde alla loro domanda. Per i sistemi ad agenti, questo si traduce in comandi CLI a profondità crescenti: | Livello | Comando | Domanda a cui risponde | |-------|---------|-------------------| | 1 | `orkestra system status` | Va tutto bene? | | 2 | `orkestra agents list` | Quali agenti esistono? | | 3 | `orkestra agents info ` | Cosa fa questo agente? | | 4 | `orkestra decisions search` | Perché funziona in questo modo? | | 5 | Strumenti MCP di Maguyva | Mostrami il codice. | Ogni livello risponde a una naturale domanda di follow-up. Raramente devi saltare direttamente al livello 5. ## Livello 1: salute del sistema La prima domanda è sempre: funziona tutto? ```bash $ orkestra system status ``` ```json { "agents": 40, "skills_internal": 466, "skills_vendor": 240, "skills_total": 706, "commands": 17 } ``` Un comando. Quattro numeri. Sufficiente per sapere che il sistema è configurato e i registri sono popolati. Se il conteggio degli agenti scende inaspettatamente o le skill non si caricano, lo vedi qui per primo. Nessun bisogno di scavare nei log. ## Livello 2: inventario degli agenti Una volta che sai che il sistema è in salute, la prossima domanda è: cosa è disponibile? ```bash $ orkestra agents list ``` Questo restituisce dati strutturati — nomi degli agenti, descrizioni, preferenze di modello, copertura di dominio. L'output è JSON per default, il che rende facile incanalarlo in `jq` per il filtraggio: ```bash $ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name' ``` Vuoi agenti che gestiscono lavoro sui database? Il comando di ricerca restringe i risultati: ```bash $ orkestra agents search "database" ``` Questo scansiona nomi, descrizioni, e capacità. Trovi lo specialista giusto senza leggere 40 definizioni di agenti. ## Livello 3: approfondimento sull'agente Hai trovato un agente che sembra rilevante? Il comando `info` rivela tutto: ```bash $ orkestra agents info architecture-advisor ``` L'output include: - **Metadati**: nome, categoria, preferenza di modello, descrizione - **Domini**: quali aree di conoscenza copre questo agente - **Identità**: tratti caratteriali (architect, strategist, knowledge-architect) - **Guide agli strumenti**: quale documentazione degli strumenti viene iniettata nel contesto - **Strumenti**: l'elenco completo degli strumenti MCP disponibili per questo agente Ecco un campione di ciò che vedi: ```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", ... ] } } ``` Questo ti dice esattamente cosa può fare l'agente. Nessun codice sorgente richiesto. ## Livello 4: archeologia delle decisioni Gli agenti si comportano secondo decisioni documentate. Quando hai bisogno di capire *perché* qualcosa funziona in un modo particolare, il registro delle decisioni è la fonte di verità. ```bash $ orkestra decisions search "agent" ``` Questo restituisce le decisioni architetturali corrispondenti: ```json { "results": [ { "id": "DEC-SR-049", "title": "AI-Agent-First Defaults with Graph Intelligence", "domain": "search", "status": "active" } ] } ``` Ogni decisione ha una provenienza completa — quando è stata presa, perché, quali trade-off sono stati considerati, quali commit l'hanno implementata: ```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..." } ] } ``` Questa è documentazione architetturale che rimane aggiornata perché viene estratta dai commit, non mantenuta manualmente. ## Livello 5: intelligenza del codice diretta Quando hai bisogno di vedere l'implementazione reale — non i metadati su di essa — gli strumenti MCP di Maguyva forniscono accesso diretto. Dall'interno di una sessione agente: ``` mcp__maguyva__intelligent_search query: "agent context loading" ``` Questo instrada automaticamente tra ricerca semantica, testuale, e AST per trovare codice rilevante. Per simboli specifici: ``` mcp__maguyva__find_symbol symbol_name: "load_agent_context" ``` Per l'analisi delle dipendenze: ``` mcp__maguyva__analyze_dependencies target: "packages/orchestration/core/agents.py" ``` Questi non sono solo sostituti di grep. Sono consapevoli del grafo, indicizzati semanticamente, e integrati con la stessa intelligenza del codice che alimenta gli agenti stessi. ## Ricerca unificata tra i registri A volte non sai quale registro contiene la risposta. La ricerca unificata copre tutto: ```bash $ orkestra search "database" --summary ``` ```json { "query": "database", "total": 254, "counts": { "agents": 40, "skills": 59, "decisions": 476, "truths": 2, "packages": 1 } } ``` 254 corrispondenze su cinque registri. Il riepilogo ti dice dove approfondire. Rimuovi `--summary` per risultati dettagliati, o aggiungi `--limit 5` per mantenere l'output gestibile. ## Perché questo conta La progressive disclosure non riguarda solo la comodità. Cambia il modo in cui interagisci con sistemi complessi. **Il debugging diventa gestibile.** Quando un agente prende una decisione inaspettata, non fai grep nei log. Controlli a quali strumenti ha accesso (`agents info`), quali decisioni plasmano il suo comportamento (`decisions search`), e tracci l'implementazione se necessario (`intelligent_search`). **L'onboarding accelera.** I nuovi membri del team non devono leggere l'intero codebase. Iniziano con `system status`, esplorano con `agents list`, e vanno più a fondo solo quando incontrano qualcosa che non capiscono. **La documentazione resta aggiornata.** Poiché la CLI legge dagli stessi registri che configurano gli agenti, l'output è sempre accurato. Non c'è disallineamento tra ciò che dice la documentazione e ciò che fa il sistema. ## La CLI come interfaccia Avremmo potuto costruire una dashboard web. Avremmo potuto scrivere documentazione estesa. Invece, abbiamo costruito una CLI che legge dalla fonte di verità. La CLI ha dei vantaggi: - **Componibile**: incanala l'output attraverso `jq`, integra con gli script - **Scriptabile**: automatizza controlli, genera report - **Veloce**: nessun caricamento di pagina, nessun flusso di autenticazione - **Accurata**: legge la configurazione reale, non una rappresentazione in cache Per i sistemi dove la correttezza conta più dell'estetica, vince la CLI. ## Costruire la tua progressive disclosure Se stai costruendo sistemi ad agenti, considera come gli utenti li ispezioneranno: 1. **Inizia con i controlli di salute.** Un comando che ti dice se le cose funzionano. 2. **Fornisci viste di inventario.** Elenca cosa esiste prima di spiegare cosa fa. 3. **Abilita query mirate.** La ricerca batte la navigazione su larga scala. 4. **Esponi la provenienza.** Lascia che gli utenti traccino le decisioni fino alle loro origini. 5. **Connetti all'intelligenza del codice.** Alla fine, gli utenti devono vedere l'implementazione. Ogni livello risponde a una domanda di follow-up. Costruiscili in ordine di frequenza — la maggior parte degli utenti si ferma al livello 2 o 3. Solo gli utenti esperti raggiungono il livello 5. L'obiettivo non è esporre tutto. È esporre esattamente ciò che serve, esattamente quando serve. Questa è la progressive disclosure applicata all'architettura degli agenti.