Definisci il tuo agente

Un agente è una configurazione riutilizzabile e con versioni che definisce persona e capacità. Raggruppa il modello, il prompt di sistema, gli strumenti, i server MCP e le skill che determinano il comportamento di Claude durante una sessione.

Crea l'agente una sola volta come risorsa riutilizzabile e fai riferimento a esso tramite ID ogni volta che avvii una sessione. Gli agenti hanno versioni e sono più facili da gestire su molte sessioni.

Campi di configurazione dell'agente

Puoi anche sovrascrivere model, system, tools, mcp_servers e skills per una singola sessione senza modificare l'agente. Una sovrascrittura di model sostituisce completamente l'oggetto model dell'agente, quindi l'effort proprio dell'agente non viene mantenuto. Per eseguire la sessione a un livello di effort specifico, imposta effort all'interno dell'oggetto model della sovrascrittura. Consulta Sovrascrivi la configurazione dell'agente per una sessione.

Crea un agente

L'esempio seguente definisce un agente di programmazione che usa il modello Claude Opus più recente con accesso al set di strumenti predefinito per agenti. Il set di strumenti consente all'agente di scrivere codice, leggere file, cercare sul web e altro ancora. Consulta il riferimento degli strumenti per agenti per l'elenco completo degli strumenti supportati.

Gli esempi usano curl, la CLI ant o uno degli SDK. Se non ne hai ancora configurato uno, la guida rapida illustra l'installazione e la configurazione del client.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

La risposta riporta la tua configurazione e aggiunge i campi id, type, version, created_at, updated_at e archived_at, e compila con i valori predefiniti i campi di model che ometti, come effort. Il campo version parte da 1 e si incrementa ogni volta che un aggiornamento modifica l'agente.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5-5",
    "effort": { "type": "medium" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

Il default_config del set di strumenti mostra la sua policy di autorizzazione predefinita, always_allow, che si applica a meno che tu non ne configuri una.

Fissa l'inference geo

Come speed ed effort, inference_geo si imposta tramite la forma a oggetto di model: passa model come oggetto e imposta inference_geo insieme a id. Il campo accetta "us" o "global". Quando non è impostato, ogni richiesta al modello segue l'inference geo predefinita del workspace al momento in cui viene servita. Consulta Residenza dei dati per i controlli geografici a livello di workspace e i prezzi.

L'esempio seguente fissa un agente all'inferenza negli Stati Uniti e stampa il valore di inference_geo dall'oggetto model dell'agente:

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

You are a helpful assistant.

Un vincolo inference_geo viene convalidato rispetto agli allowed_inference_geos del workspace quando l'agente viene salvato, quando viene creata una sessione a partire da esso e a ogni turno servito dalla sessione. Se la lista consentita del workspace si restringe in modo che un vincolo non sia più consentito, non è possibile creare nuove sessioni dall'agente e le sessioni in esecuzione rifiutano ulteriori turni; i vincoli non vengono mai esentati, perché i workspace vi fanno affidamento per la conformità e la residenza dei dati.

Impostare inference_geo su un modello che non supporta il vincolo geografico dell'inferenza restituisce un errore 400; consulta Disponibilità dei modelli per i modelli che lo supportano. In una configurazione multiagent, il vincolo dell'agente e il vincolo di ogni agente elencato nella lista predefined_agents di subagents o workflows devono essere tutti impostati sullo stesso valore o tutti non impostati; consulta Orchestrazione multiagente. Per modificare o rimuovere il vincolo in seguito, aggiorna l'oggetto model dell'agente; fornire model senza inference_geo lo rimuove, come descritto in Semantica degli aggiornamenti.

Aggiorna un agente

L'aggiornamento di un agente genera una nuova versione quando la configurazione cambia. Il campo version è facoltativo: forniscilo per la concorrenza ottimistica (una mancata corrispondenza restituisce un 409), oppure omettilo per applicare l'aggiornamento incondizionatamente (vince l'ultima scrittura). Gli aggiornamenti agli agenti archiviati vengono rifiutati.

Con la CLI, modifica il file dell'agente ed esegui di nuovo ant apply; apply fornisce version al posto tuo.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

L'esempio precedente fornisce version dalla risposta di creazione, quindi l'aggiornamento si applica solo se nient'altro ha modificato l'agente da quando lo hai letto. Per applicare un aggiornamento incondizionatamente, ometti version dalla richiesta:

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

Semantica degli aggiornamenti

• version è facoltativo e deve essere almeno 1 quando fornito. Quando fornito, la richiesta restituisce un 409 se non corrisponde alla versione corrente dell'agente, anche quando i campi che invii corrispondono già ai valori memorizzati; rileggi l'agente e riprova. Quando omesso, l'aggiornamento si applica incondizionatamente e l'aggiornamento più recente sostituisce silenziosamente qualsiasi aggiornamento concorrente, senza errori per nessuno dei chiamanti. Fornire version è l'impostazione predefinita consigliata per i chiamanti interattivi, mentre ometterlo è adatto ai cicli di apply dichiarativi, come un job di CI che sincronizza le definizioni degli agenti presenti nel repository, in cui il ciclo è proprietario dell'agente.

• I campi omessi vengono preservati. Devi includere solo i campi che vuoi modificare.

• I campi scalari (model, system, name, description) vengono sostituiti con il nuovo valore. system e description possono essere cancellati passando None. model e name sono obbligatori e non possono essere cancellati. All'interno di un oggetto model che fornisci, effort è l'unica eccezione: se l'id del modello non cambia, omettere effort lascia invariato il livello di effort memorizzato. Se modifichi l'id del modello, un effort omesso viene reimpostato al valore predefinito del nuovo modello. Gli altri campi di model vengono sostituiti insieme all'oggetto: fornire model senza inference_geo rimuove il vincolo di inference geo dell'agente.

• I campi array (tools, mcp_servers, skills) vengono completamente sostituiti dal nuovo array. Per cancellare completamente un campo array, passa None o un array vuoto.

• multiagent viene unito al blocco memorizzato livello per livello quando l'aggiornamento mantiene il tipo multiagent_20261001. Un'impostazione che ometti mantiene il suo valore memorizzato, e una lista predefined_agents che invii sostituisce la lista memorizzata. Qualsiasi altro aggiornamento che invia multiagent sostituisce il blocco memorizzato nella sua interezza, e le impostazioni che omette assumono i valori predefiniti. Passa multiagent=None per cancellare l'intero blocco. All'interno del blocco, null reimposta un'impostazione al suo valore predefinito, quindi impostare workflows su null attiva i workflow dinamici. Consulta Attiva i workflow dinamici.

• I metadati vengono uniti a livello di chiave. Le chiavi che fornisci vengono aggiunte o aggiornate. Le chiavi che ometti vengono preservate. Per eliminare una chiave specifica, imposta il suo valore su null.

• Rilevamento delle operazioni nulle. Se l'aggiornamento non produce alcuna modifica rispetto alla versione corrente, non viene creata alcuna nuova versione e viene restituita la versione esistente.

• Le liste predefined_agents degli altri agenti non vengono aggiornate. Gli agenti che elencano questo agente nella lista predefined_agents di subagents o workflows mantengono la versione che era fissata quando sono stati creati o quando un aggiornamento ha inviato per l'ultima volta quella lista, anche se il riferimento omette version. Per delegare alla nuova versione, aggiorna l'agente che lo elenca in modo che la lista faccia riferimento alla nuova versione.

L'aggiornamento seguente cancella la descrizione, elimina la chiave team da metadata e imposta workflows su null, il che attiva i workflow dinamici:

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

Ciclo di vita dell'agente

Elenca le versioni

Recupera la cronologia completa delle versioni per tracciare come un agente è cambiato nel tempo. I risultati sono paginati e gli esempi degli SDK recuperano automaticamente ogni pagina.

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

Archivia un agente

L'archiviazione rende l'agente di sola lettura e non può essere annullata. Le sessioni esistenti continuano a essere eseguite, ma le nuove sessioni non possono fare riferimento all'agente. La risposta imposta archived_at sul timestamp di archiviazione.

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

Passaggi successivi