Orkestra: orchestrare agenti AI su larga scala

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

Quando abbiamo iniziato a costruire con Claude Code, ci siamo imbattuti in un problema che ogni team che usa assistenti AI per il coding finisce per affrontare: un singolo agente non può fare tutto bene.

Puoi istruire un agente a essere uno specialista di database. O un auditor di sicurezza. O un ingegnere frontend. Ma nel momento in cui gli chiedi di essere tutti e tre insieme, la qualità ne risente. Il contesto si diluisce. Le istruzioni entrano in conflitto. L’agente diventa un generalista mediocre in tutto.

Quindi abbiamo costruito Orkestra.

Cos’è Orkestra?

Orkestra è un sistema di orchestrazione di agenti per Claude Code e strumenti AI di coding simili. Coordina più agenti specializzati, ciascuno con competenze distinte, sotto un unico orchestratore che instrada il lavoro allo specialista giusto.

Pensalo come un’agenzia di collocamento per agenti AI. L’orchestratore riceve un task, identifica quale specialista dovrebbe gestirlo, e delega con il contesto giusto. Quando il lavoro è finito, i risultati rifluiscono verso l’orchestratore per la sintesi.

I numeri raccontano la storia:

Componente	Conteggio
Agenti specialisti	46
Skill riutilizzabili	466
Archetipi di identità	27
Mindset	11
Stili di comunicazione	10
Domini di conoscenza	21

Il sistema dei personaggi: D&D per gli agenti

L’intuizione centrale dietro Orkestra è che il comportamento dell’agente emerge da tre primitive componibili:

L’identità definisce cosa è l’agente. Un architetto progetta strutture di sistema. Un debugger risale dai fallimenti alle cause profonde. Un guardiano fa rispettare compliance e confini di sicurezza. Abbiamo 27 archetipi di identità che possono essere combinati.

Il mindset definisce come pensa l’agente. Un mindset analitico ancora le asserzioni alle prove e quantifica l’incertezza. Un mindset scettico mette in discussione le assunzioni e cerca prove che le smentiscano. Un mindset esplorativo abbraccia l’ambiguità e prova approcci multipli.

Lo stile definisce come comunica l’agente. Uno stile tecnico include valori esatti e fa riferimento a file specifici. Uno stile conciso taglia i fronzoli e parte dalla risposta. Uno stile diplomatico bilancia onestà e tatto.

Un agente combina queste primitive:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Questa composizione crea un agente che progetta sistemi (architect), connette conoscenza tra domini (knowledge-architect), fissa la direzione strategica (strategist), pensa in prove e dati (analytical), e comunica senza fronzoli (concise).

La potenza sta nell’esplosione combinatoria. 27 identità per 11 mindset per 10 stili producono quasi 3.000 possibili personalità di agente. Ma definisci solo le combinazioni che contano per il tuo lavoro.

Skill: moduli di capacità riutilizzabili

Le skill sono la conoscenza e i workflow che gli agenti possono invocare. Seguono un sistema a livelli basato sull’ambito:

Livello	Nome	Ambito	Esempio
K0	Fondamenta	Metodologia universale	Disciplina test-first, completamento basato su prove
K1	Identità	Workflow basati sul ruolo	Standard di interfaccia CLI, performance playbook
K2	Domini	Conoscenza specifica del dominio	Pattern di migrazione database, validazione dell’autenticazione
K3	Stack	Specifico per tecnologia	Deployment su Cloudflare, operazioni Supabase
K4	Progetto	Solo questo codebase	Workflow e convenzioni specifici del progetto

Le skill sono caricate in modo lazy. Un agente vede nomi e descrizioni delle skill all’avvio, ma il contenuto completo della skill si carica solo quando viene attivato. Questo mantiene il contesto snello rendendo al contempo centinaia di skill scopribili.

Ogni skill include:

• Condizioni di attivazione chiare (“Usa quando fai la migrazione degli schemi database”)
• Guida passo per passo
• Strumenti consentiti per il workflow
• Criteri di successo e percorsi di recupero dal fallimento

Le 466 skill nel nostro registro coprono tutto, dall’isolamento dei worktree git ai workflow di ricerca web fino alla validazione della salute dei deployment.

Perché l’orchestrazione conta

Le architetture a singolo agente sbattono contro muri rapidamente:

Diluizione del contesto. Una finestra di contesto da 200k token sembra grande finché non ci carichi schemi di database, documentazione API, fixture di test, e conoscenza di dominio. Gli specialisti possono lavorare con contesto mirato.

Conflitti di istruzioni. Dire a un agente di “essere approfondito ma veloce” e “verificare tutto ma senza over-engineering” crea tensione. Gli specialisti risolvono questo avendo un ambito chiaro.

Profondità di competenza. Un agente generalista sa un po’ di tutto. Un agente specialista, composto con l’identità e le skill giuste, conosce il suo dominio a fondo.

Orkestra implementa un’orchestrazione piatta: un orchestratore coordina più specialisti. Gli specialisti non possono generare sub-specialisti. Questo previene l’esplosione di complessità permettendo al contempo il lavoro parallelo.

L’orchestratore ha accesso a 2,2 milioni di token di capacità effettiva: la propria finestra da 200k più 10 subagent concorrenti da 200k ciascuno. Lavoro che esaurirebbe un singolo agente gira comodamente attraverso la flotta.

La pipeline di rendering

Le definizioni degli agenti vivono in YAML. Claude Code legge Markdown. Orkestra colma questo divario con una pipeline di rendering deterministica:

YAML Registries → Jinja Templates → .claude/agents/*.md

Gli operatori modificano la sorgente YAML. Eseguono orkestra sync. Il Markdown renderizzato appare in .claude/agents/. Claude Code recepisce le modifiche.

Questa separazione serve pubblici diversi:

• La sorgente YAML include metadati di ciclo di vita, tag, regole di validazione, e note di deprecazione per il tooling
• Il Markdown renderizzato include solo ciò di cui il modello ha bisogno: descrizione, strumenti, skill, e guida comportamentale

La pipeline compone identità, mindset, stili, e skill in un unico prompt coerente. Un agente architect-analytical-concise ottiene un system prompt molto diverso da un agente debugger-skeptical-technical, anche se condividono alcune skill sottostanti.

Conoscenza di dominio: il pattern a quattro file

Ogni dominio di conoscenza segue una struttura coerente:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Questa struttura serve il caricamento del contesto dell’agente. Un agente che lavora sull’autenticazione carica authentication/patterns.md per la guida e authentication/anti-patterns.md per evitare le insidie conosciute. I file sono dimensionati per un caricamento efficiente del contesto: abbastanza mirati da essere utili, abbastanza completi da essere autorevoli.

Manteniamo 21 domini di primo livello tra cui analytics, autenticazione, data science, infrastruttura, machine learning, performance, sicurezza, e altro ancora. Ogni dominio può avere sotto-domini per una granularità più fine.

Valori: il sistema operativo

Tutti gli agenti condividono un livello di base di valori che definisce come operano:

Semplicità prima di tutto. Usa la soluzione più semplice che funziona. Aggiungi complessità solo quando è giustificata.

Correggi le cause profonde. Non applicare mai toppe intorno ai fallimenti. Se una pipeline fallisce, fai debug della pipeline. Se un test fallisce, correggi il codice o il test.

Basato su prove. Etichetta le affermazioni come “verificate” (con benchmark) o “stimate” (con assunzioni). Un pattern rilevato non equivale a un problema confermato.

Economia del contesto. Gli strumenti MCP costano lo 0,1% del contesto. Le letture di file costano il 2% ciascuna. Applica la competenza di dominio prima di esplorare il codice.

Questi valori si propagano a ogni specialista attraverso la pipeline di rendering. Un agente non può aggirarli tramite composizione.

CLI: il piano di controllo

Orkestra include una CLI per gestire l’ecosistema di agenti:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

La CLI è la fonte di verità su quali agenti esistono, quali skill hanno, e se il sistema è in salute. Esegue la validazione prima della sincronizzazione per intercettare i problemi in anticipo.

Considerazioni sull’open source

Abbiamo costruito Orkestra per risolvere il nostro stesso problema: coordinare agenti AI su larga scala per un codebase complesso. I pattern che abbiamo scoperto non sono specifici del nostro dominio.

Il sistema di composizione dei personaggi (identità + mindset + stile) si applica a qualsiasi team che definisce personalità di agente.

Il sistema a livelli delle skill (K0-K4) fornisce un modello mentale per organizzare capacità riutilizzabili per ambito.

Il pattern della pipeline di rendering (sorgente YAML + template + artefatti generati) separa le responsabilità tra tooling e consumo da parte del modello.

Il modello di orchestrazione piatta (un coordinatore, molti specialisti) evita la complessità pur abilitando il parallelismo.

Se Orkestra diventerà open source dipende dal fatto che questi pattern abbiano valore per altri che costruiscono con Claude Code. Se stai sbattendo contro i muri che abbiamo descritto, l’architettura potrebbe aiutare.

Cosa abbiamo imparato

Costruire Orkestra ci ha insegnato che l’orchestrazione non riguarda il rendere gli agenti più intelligenti. Riguarda il renderli più focalizzati.

Un singolo agente con istruzioni perfette esaurisce comunque il contesto. Un singolo agente con tutte le skill si confonde comunque su quale applicare. Un singolo agente che cerca di essere tutto produce risultati mediocri ovunque.

Quaranta specialisti, ciascuno eccellente nel proprio dominio, coordinati da un orchestratore che sa quando delegare: è così che spediamo.

I numeri contano meno dell’architettura. Potresti aver bisogno di cinque agenti o cinquanta. Il principio resta: composizione sopra capacità, specializzazione sopra generalizzazione, coordinazione sopra le imprese eroiche individuali.

---

Orkestra alimenta l’ecosistema di agenti dietro Maguyva, la nostra piattaforma di Code Intelligence. Vuoi saperne di più? Contatta il team.