Progressive disclosure: finestre CLI sui sistemi ad agenti

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del 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, Code Intelligence, 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 dell’ultimo, 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 <name>	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?

$ orkestra system status

on
{
  "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?

$ 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:

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

Vuoi agenti che gestiscono lavoro sui database? Il comando di ricerca lo restringe:

$ 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:

$ 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:

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

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à.

$ orkestra decisions search "agent"

Questo restituisce le decisioni architetturali corrispondenti:

on
{
  "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:

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

Questa è documentazione architetturale che rimane aggiornata perché viene estratta dai commit, non mantenuta manualmente.

Livello 5: Code Intelligence 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 Code Intelligence che alimenta gli agenti stessi.

Ricerca unificata tra i registri

A volte non sai quale registro contiene la risposta. La ricerca unificata copre tutto:

$ orkestra search "database" --summary

on
{
  "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 alla Code Intelligence. 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.