Il modello degli agenti

Che cos’è un agente?

Un agente è un attore con un nome, un personaggio, un insieme di skill e un adattatore su cui essere eseguito. Gli agenti sono soggetti esattamente come lo sono le persone: scrivono messaggi, possiedono ticket, lasciano revisioni e compaiono nello stesso elenco. Sono le entità che fanno il lavoro.

Ogni agente appartiene esattamente a uno spazio di lavoro. È un invariante rigido: agent.workspaceId non è mai null, è lo spazio di lavoro dell’agente a stabilire in quale file di database finiscono le sue righe, e creare un agente senza spazio di lavoro viene rifiutato.

Un agente è anche una directory. La sua definizione vive in agents/<slug>/AGENTS.md nella directory dati dello spazio di lavoro, con le skill che possiede collegate simbolicamente in agents/<slug>/.agents/skills. La riga nel database e il file vengono scritti insieme. Il popolamento iniziale è idempotente: se la riga dell’agente esiste già, i file su disco e i collegamenti alle skill vengono comunque riscritti. Il chiamante in produzione è la creazione dello spazio di lavoro, non ogni avvio del server.

Che cosa porta con sé un agente

Attributo	Che cosa fa
`name`	Identificatore breve in stile slug (`architect`, `qa`). È anche ciò su cui si risolvono le `@mentions`
`title`	Titolo professionale leggibile da una persona
`persona`	Istruzioni libere su personalità e comportamento, iniettate come sezione del prompt
`systemPrompt`	Istruzioni aggiuntive facoltative, iniettate come sezione «Istruzioni dell’agente» — non sostituiscono il resto del prompt assemblato
`skills`	Insieme di nomi di skill senza distinzione fra maiuscole e minuscole, rispecchiato su disco come collegamenti alle skill
`adapterId`	Quale esecutore l’agente invoca. Se è null, si ricade nel loop integrato
`modelId`	Quale modello all’interno di quell’adattatore
`effort`	Livello di ragionamento, tratto dal vocabolario del modello selezionato
`contextSize`	Override della finestra di contesto
`silenceTimeoutMinutes`	Override per singolo agente (1–240) del watchdog del silenzio
`reportsTo`	Id dell’agente padre — la catena di riporto che l’organigramma disegna

Tutti questi campi si modificano in Impostazioni → Spazio di lavoro → Agenti. Nuovo agente crea un agente senza nome che poi compili tu.

Skill

Le skill sono nomi senza distinzione fra maiuscole e minuscole sull’entità agente. Con esse accadono due cose distinte:

I nomi sono elencati nel prompt assemblato sotto una sezione «Skill». È tutto ciò che l’insieme dell’entità fa da solo — non esiste una raccolta di prompt per singola skill indicizzata da quei nomi.
La directory di ogni skill nominata (skills/<slug>/SKILL.md nello spazio di lavoro) viene collegata nella cartella dell’agente. Sull’harness integrato, il frontmatter delle skill collegate viene caricato automaticamente nel prompt di sistema e l’agente ne legge il corpo su richiesta; digitando /skill:<name> in una conversazione quel corpo viene caricato come direttiva per il turno.

Le skill recuperate dall’esterno passano una scansione fail-closed della catena di fornitura fra il recupero e la scrittura — nessun contenuto di skill arriva su disco o in un prompt senza un verdetto. L’esterno sono i repository GitHub che registri tu come sorgenti di skill: non esiste un catalogo curato, quindi i metadati del repository stesso (la sua descrizione, le sue stelle, il nome della skill) sono dati di visualizzazione non attendibili e il verdetto della scansione è l’unico segnale di sicurezza. Un’installazione recupera l’intera directory della skill, la fissa al commit da cui proviene in skills-lock.json, e un aggiornamento successivo ripassa il controllo prima di sostituire qualsiasi cosa. La procedura è descritta in Installa e gestisci le skill.

Skill con ambito di repository

Un repository può fornire le proprie skill, in uno qualsiasi dei percorsi convenzionali (.agents/skills/, .claude/skills/, .opencode/skills/). Uno spazio fa il checkout di ogni repository collegato fianco a fianco sotto repos/<name>/, ma un agente lavora in un repository alla volta — quindi porta con sé solo le skill di quel repository, che cambiano quando si sposta.

Quale repository è attivo si deduce dai file che l’agente tocca: scrivere un file sotto repos/<name>/ rende quello il repository attivo, mentre limitarsi a leggere attraverso più repository no, così inseguire un simbolo in un servizio affine non fa mai cambiare l’insieme sotto a un’attività in corso. In uno spazio con un solo repository la risposta è nota prima del primo turno.

La scelta dell’ambito è una decisione di budget di contesto. L’indice delle skill sta nel prompt a ogni turno, mentre i corpi no, quindi elencare in una volta le skill di tutti i repository costa token di continuo — e una skill testing di un servizio trae attivamente in inganno quando il lavoro è in un altro. Lo stesso ragionamento spiega perché l’indice di un agente porta un solo repository ma il composer non è limitato in quel modo: nominare tu una skill è un atto esplicito, quindi /skill:<repo>:<name> raggiunge qualsiasi repository dello spazio.

Le skill di repository vengono caricate per ogni adattatore, non solo per l’harness integrato. Le skill del repository attivo vengono materializzate nella directory di lavoro dell’agente, che è il percorso che Claude Code già analizza; lo stesso indice viene composto nell’AGENTS.md che l’harness integrato legge. Le skill di un repository passano la stessa scansione fail-closed di una skill installata prima che tutto questo avvenga — un repository di cui è stato fatto il checkout è contenuto clonato, e il suo frontmatter arriva a un prompt.

Permessi

Un agente non porta flag di permesso propri. Se può creare un commit, eseguire un push, aprire una pull request, scrivere su un tracker o raggiungere la rete lo decidono i guardrail delle azioni — consenti, chiedi prima o nega, nell’ambito dello spazio di lavoro, dell’agente o dello spazio — e le stesse regole valgono qualunque sia l’adapter che lo esegue.

Ciò che viene fornito a un’esecuzione non cambia con queste regole. Un’esecuzione in un worktree GitHub riceve sempre un token GitHub di sola lettura, e per un push la domanda arriva nel momento in cui avviene: la configurazione git dell’agente fa passare ogni push verso GitHub da Control Center, che applica la regola Eseguire il push a un remoto prima di inoltrarlo.

Vedi Sandbox e sicurezza per come funziona, compreso ciò che viene e ciò che non viene imposto a livello di filesystem.

L’adattatore decide che cosa si può imporre

Il campo più determinante di un agente è il suo adattatore, perché il trasporto dell’adattatore determina quanta parte delle policy di Control Center è realmente applicabile.

Trasporto	Adattatori	Che cosa impone Control Center
Harness integrato	Control Center (built-in)	Tutto. La superficie degli strumenti viene costruita a partire dalla modalità, quindi uno strumento non consentito è invisibile invece che semplicemente negato; ogni chiamata passa dal controllo di approvazione e dai guardrail delle azioni; il contratto di completamento può sollecitare e poi far fallire un’esecuzione che termina senza il suo risultato
Claude CLI	Claude Code	Gli strumenti `mcp__*` che gli vengono serviti, più i suoi comandi `Bash`, che un hook invia alla policy delle azioni prima che vengano eseguiti. Gli strumenti di lettura, scrittura e modifica di Claude vivono nel suo processo e vengono eseguiti senza essere visti — ed è avviato con `--dangerously-skip-permissions`, perché `claude -p` non interattivo altrimenti resterebbe bloccato per sempre sul proprio prompt

In concreto, solo l’harness integrato supporta i sottoagenti, la guida durante l’esecuzione, la pausa e la ripresa (e quindi la possibilità di prendere il controllo) e l’applicazione strutturale della modalità. Claude Code non ha nulla di tutto questo.

La matrice qui sopra riguarda ciò che Control Center riesce a vedere e a controllare. Sotto di essa, cc_server avvolge la CLI di Claude Code nel sandbox del sistema operativo dell’host dove ne esiste uno — Seatbelt su macOS, bubblewrap su Linux e WSL2 — così un rm non visto o una scrittura non vista restano comunque limitati dal sistema operativo. Su Windows non esiste alcun backend e su Linux o WSL2 senza bwrap e socat la sonda non ne segnala nessuno, quindi lì quelle esecuzioni ricadono sulla sanificazione dell’ambiente, sulle credenziali fornite tramite broker, sui guardrail delle chiamate che Control Center riesce a vedere e sul worktree della conversazione stessa (copy-on-write dove rift è disponibile; git worktree su Windows).

Ciò che il sandbox non è, è un punto di controllo. Delimita dove un processo può leggere, scrivere e connettersi — una modalità di sola lettura lo raggiunge davvero, sotto forma di bind mount in sola lettura — ma non può intercettare una chiamata, richiedere un’approvazione o dirti in seguito che cosa ha tentato la CLI. Questo, più le quattro capacità appena nominate, è ancora ciò che l’harness integrato ha e gli altri no. Vedi Sandbox e sicurezza.

Un agente senza adattatore ricade su Control Center (built-in) — il loop dentro il server, quindi non c’è nessuna CLI da installare — e il suo log di esecuzione registra cc-harness. Ogni agente creato dal popolamento iniziale nasce senza adattatore né modello, quindi i cinque agenti di uno spazio di lavoro nuovo vengono eseguiti tutti lì, sul modello predefinito di Anthropic, finché non imposti un adattatore e un modello per agente. La scelta «adattatore predefinito» dell’onboarding è una preferenza lato client che il server non legge mai e che non viene applicata retroattivamente agli agenti già creati.

Da dove vengono gli agenti

Creati insieme allo spazio di lavoro. Ogni spazio di lavoro — non solo il primo — riceve un CEO più quattro specialisti (qa, architect, engineer, librarian) che rispondono a lui, creati in modo idempotente in background quando lo spazio di lavoro viene creato. Vedi Spazi di lavoro e isolamento.
Aggiunti a mano in Impostazioni → Spazio di lavoro → Agenti. Chiedere a un agente di assumere un collega non crea una riga; usa quella schermata.

Stato in tempo reale

Un agente non ha una colonna di stato memorizzata. Il suo stato in tempo reale viene ricavato dai log delle sue esecuzioni più recenti ogni volta che viene letto:

Stato	Significato
`neverRun`	Non esiste alcun log di esecuzione
`running`	Almeno un’esecuzione è attualmente in corso
`failed`	L’ultima esecuzione ha dato errore, oppure la sua vitalità è failed o dead
`blocked`	La vitalità dell’ultima esecuzione è blocked, stalled o looping
`idle`	Tutto il resto — l’agente ha già eseguito e non ha nulla in volo

Altri due stati, queued e succeeded, esistono per le singole esecuzioni nell’albero delle esecuzioni della conversazione; l’elenco degli agenti non li produce mai, perché un’esecuzione conclusa che è verde è un fatto dell’esecuzione, non dell’agente.

L’elenco delle presenze mostra un quadro parallelo e più grossolano, sintetizzato lato server dagli eventi di esecuzione in tempo reale — sta pensando, sta eseguendo, bloccato in attesa di approvazione, ha finito — ed è ciò che fa comparire gli agenti accanto agli esseri umani. Vedi Multigiocatore.

Concetti correlati

Ciclo di vita dell’invio degli agenti: che cosa succede quando un agente viene effettivamente eseguito
Modalità: l’impostazione per conversazione che determina la superficie degli strumenti di un agente
Multigiocatore: gli agenti come soggetti, la presenza e il quadrante dell’autonomia
Sandbox e sicurezza: che cosa vincola oggi un’esecuzione
Configurazione degli agenti: l’elenco completo dei campi