Divulgation progressive : des fenêtres CLI sur les systèmes d'agents

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Les systèmes d’agents sont opaques par conception. Ils prennent des décisions, invoquent des outils et coordonnent le travail entre des dizaines de spécialistes. Mais quand quelque chose tourne mal — ou quand vous voulez simplement comprendre ce qui se passe — où regarder ?

La réponse, c’est la divulgation progressive : une interface en couches qui révèle exactement autant de complexité que nécessaire, exactement au moment où c’est nécessaire.

Le problème de l’opacité

Un système moderne d’orchestration d’agents peut compter :

• Plus de 40 agents spécialistes, chacun doté de capacités distinctes
• Plus de 700 compétences couvrant l’automatisation interne et les intégrations tierces
• Plus de 470 décisions architecturales façonnant le comportement
• Des dizaines de serveurs d’outils MCP fournissant des capacités externes

Cette complexité est intentionnelle. Les agents ont besoin d’accéder à un contexte riche — savoir de domaine, intelligence du code, schémas de base de données — pour prendre de bonnes décisions. Mais cette même richesse crée un problème de visibilité.

Comment savoir quel agent gère les migrations de base de données ? Quelles décisions ont façonné le comportement de classement du système de recherche ? À quels outils le conseiller en architecture a-t-il accès ?

Sans accès structuré, il ne vous reste plus qu’à lire le code source ou espérer que la documentation est à jour.

La divulgation progressive comme architecture

La divulgation progressive n’est pas qu’un schéma d’interface utilisateur. C’est un principe architectural : organiser l’information en couches, chacune plus profonde que la précédente, pour que les utilisateurs puissent s’arrêter au niveau qui répond à leur question.

Pour les systèmes d’agents, cela se traduit par des commandes CLI à des profondeurs croissantes :

Niveau	Commande	Question à laquelle on répond
1	orkestra system status	Tout va-t-il bien ?
2	orkestra agents list	Quels agents existent ?
3	orkestra agents info <name>	Que fait cet agent ?
4	orkestra decisions search	Pourquoi fonctionne-t-il ainsi ?
5	Outils MCP de Maguyva	Montrez-moi le code.

Chaque niveau répond à une question de suivi naturelle. Vous avez rarement besoin de sauter directement au niveau 5.

Niveau 1 : santé du système

La première question est toujours : tout fonctionne-t-il ?

$ orkestra system status

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

Une seule commande. Quatre chiffres. Suffisant pour savoir que le système est configuré et que les registres sont peuplés.

Si le nombre d’agents chute de façon inattendue, ou si des compétences échouent à se charger, vous le voyez ici en premier. Pas besoin de plonger dans les logs.

Niveau 2 : inventaire des agents

Une fois que vous savez que le système est en bonne santé, la question suivante est : qu’y a-t-il de disponible ?

$ orkestra agents list

Cela renvoie des données structurées — noms d’agents, descriptions, préférences de modèle, couverture de domaine. La sortie est en JSON par défaut, ce qui la rend facile à faire transiter par jq pour du filtrage :

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

Vous voulez des agents qui gèrent le travail base de données ? La commande de recherche réduit le champ :

$ orkestra agents search "database"

Cela scanne les noms, descriptions et capacités. Vous trouvez le bon spécialiste sans lire 40 définitions d’agents.

Niveau 3 : plongée dans un agent

Vous avez trouvé un agent qui semble pertinent ? La commande info révèle tout :

$ orkestra agents info architecture-advisor

La sortie inclut :

• Métadonnées : nom, catégorie, préférence de modèle, description
• Domaines : quelles zones de savoir cet agent couvre
• Identité : traits de caractère (architecte, stratège, architecte-connaissances)
• Guides d’outils : quelle documentation d’outil est injectée dans le contexte
• Outils : la liste complète des outils MCP disponibles pour cet agent

Voici un échantillon de ce que vous voyez :

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

Cela vous indique exactement ce que l’agent peut faire. Aucun code source requis.

Niveau 4 : archéologie des décisions

Les agents se comportent selon des décisions documentées. Quand vous devez comprendre pourquoi quelque chose fonctionne d’une manière particulière, le registre des décisions est la source de vérité.

$ orkestra decisions search "agent"

Cela renvoie les décisions architecturales correspondantes :

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

Chaque décision dispose d’une provenance complète — quand elle a été prise, pourquoi, quels compromis ont été considérés, quels commits l’ont mise en œuvre :

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

C’est de la documentation architecturale qui reste à jour, parce qu’elle est minée à partir des commits, pas maintenue manuellement.

Niveau 5 : intelligence du code directe

Quand vous devez voir l’implémentation réelle — pas des métadonnées à son sujet — les outils MCP de Maguyva fournissent un accès direct.

Depuis une session d’agent :

mcp__maguyva__intelligent_search
  query: "agent context loading"

Cela route automatiquement entre recherche sémantique, textuelle et AST pour trouver le code pertinent. Pour des symboles spécifiques :

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Pour l’analyse de dépendances :

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

Ce ne sont pas de simples remplacements de grep. Ils sont conscients du graphe, indexés sémantiquement, et intégrés à la même intelligence du code qui alimente les agents eux-mêmes.

Recherche unifiée entre registres

Parfois, vous ne savez pas quel registre détient la réponse. La recherche unifiée couvre tout :

$ orkestra search "database" --summary

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

254 correspondances sur cinq registres. Le résumé vous indique où creuser. Retirez --summary pour des résultats détaillés, ou ajoutez --limit 5 pour garder une sortie maniable.

Pourquoi cela compte

La divulgation progressive ne concerne pas que la commodité. Elle change la façon dont vous interagissez avec des systèmes complexes.

Le débogage devient traitable. Quand un agent prend une décision inattendue, vous ne grep-ez pas dans des logs. Vous vérifiez à quels outils il a accès (agents info), quelles décisions façonnent son comportement (decisions search), et tracez l’implémentation si nécessaire (intelligent_search).

L’intégration s’accélère. Les nouveaux membres de l’équipe n’ont pas besoin de lire toute la base de code. Ils commencent avec system status, explorent avec agents list, et n’approfondissent que quand ils tombent sur quelque chose qu’ils ne comprennent pas.

La documentation reste à jour. Parce que la CLI lit dans les mêmes registres qui configurent les agents, la sortie est toujours exacte. Il n’y a pas de dérive entre ce que dit la documentation et ce que fait le système.

La CLI comme interface

Nous aurions pu construire un tableau de bord web. Nous aurions pu écrire une documentation exhaustive. Au lieu de cela, nous avons construit une CLI qui lit directement dans la source de vérité.

La CLI a des avantages :

• Composable : faire transiter la sortie par jq, s’intégrer à des scripts
• Scriptable : automatiser des vérifications, générer des rapports
• Rapide : pas de chargement de page, pas de flux d’authentification
• Exacte : lit la configuration réelle, pas une représentation mise en cache

Pour les systèmes où la justesse compte plus que l’esthétique, la CLI l’emporte.

Construire votre propre divulgation progressive

Si vous construisez des systèmes d’agents, réfléchissez à la façon dont les utilisateurs les inspecteront :

1. Commencez par des contrôles de santé. Une commande qui vous dit si tout fonctionne.
2. Fournissez des vues d’inventaire. Listez ce qui existe avant d’expliquer ce que cela fait.
3. Activez des requêtes ciblées. La recherche l’emporte sur la navigation à grande échelle.
4. Exposez la provenance. Laissez les utilisateurs tracer les décisions jusqu’à leurs origines.
5. Connectez-vous à l’intelligence du code. Au bout du compte, les utilisateurs doivent voir l’implémentation.

Chaque couche répond à une question de suivi. Construisez-les par ordre de fréquence — la plupart des utilisateurs s’arrêtent au niveau 2 ou 3. Seuls les utilisateurs avancés atteignent le niveau 5.

L’objectif n’est pas de tout exposer. C’est d’exposer exactement ce qui est nécessaire, exactement quand c’est nécessaire. C’est la divulgation progressive appliquée à l’architecture d’agents.