Definisci il tuo agente

Un agente è una configurazione riutilizzabile e versionata 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 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. Vedi Sovrascrivere la configurazione dell'agente per una sessione.



Creare un agente

L'esempio seguente definisce un agente di coding che utilizza Claude Opus 4.8 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 agli strumenti agente per l'elenco completo degli strumenti supportati.

Gli esempi utilizzano 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.

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

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

La risposta riproduce la tua configurazione e aggiunge i campi id, type, version, created_at, updated_at e archived_at. Il campo version inizia da 1 e viene incrementato ogni volta che un aggiornamento modifica l'agente.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "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
}

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.



Aggiornare un agente

L'aggiornamento di un agente genera una nuova versione quando la configurazione cambia. Il campo version è obbligatorio e deve corrispondere alla versione corrente dell'agente, in modo da aggiornare sempre da uno stato noto. Una mancata corrispondenza di versione restituisce un errore 409, e gli aggiornamenti ad agenti archiviati vengono rifiutati.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



Semantica di aggiornamento

• 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.

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

• multiagent viene sostituito nella sua interezza, incluso il suo elenco agents. Passa null per cancellarlo.

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

• Gli elenchi dei coordinatori non vengono aggiornati. I coordinatori che fanno riferimento a questo agente nel loro elenco multiagent.agents mantengono la versione che era stata 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 elenco vi faccia riferimento.



Ciclo di vita dell'agente



Elencare 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.

ant beta:agents:versions list --agent-id "$AGENT_ID"



Archiviare un agente

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

ant beta:agents archive --agent-id "$AGENT_ID"



Passaggi successivi