Definisci il tuo agente

Un agente è una configurazione riutilizzabile e versionata che definisce la personalità e le capacità. Raggruppa il modello, il prompt di sistema, gli strumenti, i server MCP e le competenze che modellano il comportamento di Claude durante una sessione.

Crea l'agente una 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 in molte sessioni.

Campi di configurazione dell'agente

Crea un agente

L'esempio seguente definisce un agente di codifica che utilizza Claude Sonnet 4.6 con accesso al set di strumenti agente precostruito. 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.

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -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 '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

La risposta ripete la tua configurazione e aggiunge i campi id, version, created_at, updated_at e archived_at. La version inizia da 1 e si incrementa ogni volta che aggiorni l'agente.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

Aggiorna un agente

L'aggiornamento di un agente genera una nuova versione. Passa la version corrente per assicurarti di aggiornare da uno stato noto.

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 @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

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

Semantica di aggiornamento

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

• I campi scalari (model, system, name, ecc.) vengono sostituiti con il nuovo valore. system e description possono essere cancellati passando null. model e name sono obbligatori e non possono essere cancellati.

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

• 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 una stringa vuota.

• Rilevamento no-op. Se l'aggiornamento non produce alcun cambiamento rispetto alla versione corrente, non viene creata una nuova versione e viene restituita la versione esistente.

Ciclo di vita dell'agente

Elenca versioni

Recupera la cronologia completa delle versioni per tracciare come un agente è cambiato nel tempo.

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

Archivia un agente

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

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"

Passaggi successivi

• Configura strumenti per personalizzare quali capacità l'agente può utilizzare.
• Allega competenze per competenze specifiche del dominio.
• Avvia una sessione che fa riferimento al tuo agente.