Definisci il tuo agente

Un agente è una configurazione riutilizzabile e versionata che definisce persona e capacità. Raggruppa il modello, il "system prompt" (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 ad esso tramite ID ogni volta che avvii una sessione. Gli agenti sono versionati e 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 interamente 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 Sovrascrivere la configurazione dell'agente per una sessione.

Crea un agente

L'esempio seguente definisce un agente di programmazione che usa Claude Opus 5 con accesso al set di strumenti agente predefinito. Il set di strumenti consente all'agente di scrivere codice, leggere file, cercare sul web e altro ancora. Consulta il riferimento degli strumenti agente 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 copre 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 i campi model che ometti, come effort, con i loro valori predefiniti. 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": "high" },
    "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 sul set di strumenti mostra la sua policy di autorizzazione predefinita, always_allow, che si applica a meno che tu non ne configuri una.

Fissa la geo di inferenza

Come speed ed effort, inference_geo viene impostato tramite la forma a oggetto di model: passa model come oggetto e imposta inference_geo accanto a id. Il campo accetta "us" o "global". Quando non è impostato, ogni richiesta al modello segue la geo di inferenza predefinita del workspace al momento in cui viene servita. Consulta Residenza dei dati per i controlli geo 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 pin inference_geo viene validato 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 allowlist del workspace si restringe in modo che un pin non sia più consentito, non è possibile creare nuove sessioni dall'agente e le sessioni in esecuzione rifiutano ulteriori turni; i pin non vengono mai esentati, perché i workspace si affidano a essi per la conformità e la residenza dei dati.

Impostare inference_geo su un modello che non supporta il pinning geografico dell'inferenza restituisce un errore 400; consulta Disponibilità dei modelli per i modelli che lo supportano. In una configurazione multiagent, il pin del coordinatore e quello di ogni membro del roster devono essere tutti impostati sullo stesso valore oppure tutti non impostati; consulta Orchestrazione multiagente. Per modificare o rimuovere il pin 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:

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

Semantica degli aggiornamenti

• version è facoltativo e, quando fornito, deve essere almeno 1. 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 due chiamanti. Fornire version è l'impostazione predefinita consigliata per i chiamanti interattivi, mentre ometterlo si adatta ai cicli di applicazione dichiarativi, come un job CI che sincronizza definizioni di agenti versionate 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 null. 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 è invariato, omettere effort lascia invariato il livello di effort memorizzato. Se cambi l'id del modello, un effort omesso viene reimpostato al valore predefinito del nuovo modello. Gli altri campi model vengono sostituiti insieme all'oggetto: fornire model senza inference_geo rimuove il pin della geo di inferenza dell'agente.

• I campi array (tools, mcp_servers, skills) vengono completamente sostituiti dal nuovo array. Per svuotare del tutto un campo array, passa null o un array vuoto.

• multiagent viene sostituito nel suo insieme, incluso il suo roster agents. Passa null per cancellarlo.

• I metadata 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 no-op. Se l'aggiornamento non produce alcuna modifica rispetto alla versione corrente, non viene creata alcuna nuova versione e viene restituita la versione esistente.

• I roster dei coordinatori non vengono aggiornati. I coordinatori che fanno riferimento a questo agente nel loro roster multiagent.agents mantengono la versione fissata quando il coordinatore è stato creato o aggiornato l'ultima volta, anche se il riferimento omette version. Per delegare alla nuova versione, aggiorna il coordinatore in modo che il suo roster vi faccia riferimento.

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 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 al timestamp di archiviazione.

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

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

Passaggi successivi