---
title: Definisci il tuo agente
url: https://platform.claude.com/docs/it/managed-agents/agent-setup
description: Crea una configurazione di agente riutilizzabile e con versioni.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
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](https://platform.claude.com/docs/it/managed-agents/sessions). Gli agenti hanno versioni e sono più facili da gestire su molte sessioni.
## Campi di configurazione dell'agente
| Campo | Descrizione |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` (csharp, go: `Name`) | Obbligatorio. Un nome leggibile per l'agente. |
| `model` (csharp, go: `Model`) | Obbligatorio. Il [modello](https://platform.claude.com/docs/it/models/overview) Claude che alimenta l'agente. Accetta una stringa con l'ID del modello o un oggetto, ad esempio `{"id": "claude-opus-5-5"}`. Sono supportati i modelli Claude 4.5 e successivi. La forma a oggetto accetta anche i campi `speed`, `effort` e `inference_geo`; consulta i suggerimenti in [Crea un agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#create-an-agent), [Livelli di effort](https://platform.claude.com/docs/it/build-with-claude/effort#effort-levels) e [Fissa l'inference geo](https://platform.claude.com/docs/it/managed-agents/agent-setup#pin-the-inference-geo). |
| `system` (csharp, go: `System`; ruby: `system_`) | Un [prompt di sistema](https://platform.claude.com/docs/it/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) che definisce il comportamento e la persona dell'agente. Il prompt di sistema è distinto dai [messaggi utente](https://platform.claude.com/docs/it/managed-agents/reference#event-types), che dovrebbero descrivere il lavoro da svolgere. |
| `tools` (csharp, go: `Tools`) | Gli strumenti disponibili per l'agente. Combina [strumenti predefiniti per agenti](https://platform.claude.com/docs/it/managed-agents/tools), [strumenti MCP](https://platform.claude.com/docs/it/managed-agents/mcp-connector) e [strumenti personalizzati](https://platform.claude.com/docs/it/managed-agents/tools#custom-tools). |
| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [Server MCP](https://platform.claude.com/docs/it/managed-agents/mcp-connector) che forniscono capacità standardizzate di terze parti. |
| `skills` (csharp, go: `Skills`) | [Skill](https://platform.claude.com/docs/it/managed-agents/skills) che forniscono contesto specifico del dominio con divulgazione progressiva. |
| `multiagent` (csharp, go: `Multiagent`) | Consente all'agente di affidare lavoro ad altri agenti, come subagenti o in [workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#dynamic-workflows), e facoltativamente di consultare un modello [advisor](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Con il tipo `multiagent_20261001`, i workflow dinamici sono attivi a meno che tu non li disabiliti. Consulta [Orchestrazione multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration). |
| `description` (csharp, go: `Description`) | Una descrizione di ciò che fa l'agente. |
| `metadata` (csharp, go: `Metadata`) | Coppie chiave-valore arbitrarie per il tuo tracciamento. |
Puoi anche sovrascrivere `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) e `skills` (csharp, go: `Skills`) per una singola sessione senza modificare l'agente. Una sovrascrittura di `model` (csharp, go: `Model`) sostituisce completamente l'oggetto `model` (csharp, go: `Model`) dell'agente, quindi l'`effort` (csharp, go: `Effort`) proprio dell'agente non viene mantenuto. Per eseguire la sessione a un livello di effort specifico, imposta `effort` (csharp, go: `Effort`) all'interno dell'oggetto `model` (csharp, go: `Model`) della sovrascrittura. Consulta [Sovrascrivi la configurazione dell'agente per una sessione](https://platform.claude.com/docs/it/managed-agents/sessions#override-agent-configuration-for-a-session).
## 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](https://platform.claude.com/docs/it/managed-agents/tools) 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](https://platform.claude.com/docs/it/managed-agents/quickstart#install-the-cli) illustra l'installazione e la configurazione del client.
```bash cURL
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-opus-5-5",
"system": "You are a helpful coding agent.",
"tools": [{"type": "agent_toolset_20260401"}]
}')
AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")
```
```bash CLI
ant apply coding-assistant.md
```
```markdown
---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful coding agent.
```
[`ant apply`](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/apply) crea l'agente da `coding-assistant.md`, ne stampa l'ID e lo registra in `claude-lock.json`. Esegui il commit di `claude-lock.json` in modo che il successivo `ant apply` aggiorni questo agente invece di crearne un secondo.
```python Python
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-opus-5-5",
system="You are a helpful coding agent.",
tools=[
{"type": "agent_toolset_20260401"},
],
)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Coding Assistant",
model: "claude-opus-5-5",
system: "You are a helpful coding agent.",
tools: [{ type: "agent_toolset_20260401" }],
});
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Coding Assistant",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "You are a helpful coding agent.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = "agent_toolset_20260401",
},
],
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Coding Assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
},
System: anthropic.String("You are a helpful coding agent."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
})
if err != nil {
panic(err)
}
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Coding Assistant")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("You are a helpful coding agent.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
.build()
);
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Coding Assistant',
model: 'claude-opus-5-5',
system: 'You are a helpful coding agent.',
tools: [
BetaManagedAgentsAgentToolset20260401Params::with(
type: 'agent_toolset_20260401',
),
],
);
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Coding Assistant",
model: "claude-opus-5-5",
system_: "You are a helpful coding agent.",
tools: [{type: "agent_toolset_20260401"}]
)
```
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.
```json
{
"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](https://platform.claude.com/docs/it/managed-agents/permission-policies) predefinita, `always_allow`, che si applica a meno che tu non ne configuri una.
Per usare Claude Opus 5.5, Claude Opus 5 o Claude Opus 4.8 con la [modalità veloce](https://platform.claude.com/docs/it/build-with-claude/fast-mode), passa `model` come oggetto, ad esempio: `{"id": "claude-opus-5-5", "speed": "fast"}`. Consulta i [modelli supportati](https://platform.claude.com/docs/it/build-with-claude/fast-mode#supported-models) nella pagina della modalità veloce.
Per impostare il livello di effort del modello, passa `model` come oggetto, ad esempio: `{"id": "claude-opus-5-5", "effort": "high"}`. Il campo `effort` accetta una stringa di livello (`low`, `medium`, `high`, `xhigh` o `max`) oppure un oggetto come `{"type": "high"}`. Consulta [Livelli di effort](https://platform.claude.com/docs/it/build-with-claude/effort#effort-levels) per sapere cosa fa ciascun livello.
### Fissa l'inference geo
Come `speed` (csharp, go: `Speed`) ed `effort` (csharp, go: `Effort`), `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) si imposta tramite la forma a oggetto di `model` (csharp, go: `Model`): passa `model` (csharp, go: `Model`) come oggetto e imposta `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) insieme a `id` (csharp, go: `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](https://platform.claude.com/docs/it/manage-claude/data-residency) 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` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) dall'oggetto `model` (csharp, go: `Model`) dell'agente:
```bash cURL
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": "Geo-pinned assistant",
"model": {"id": "claude-opus-5-5", "inference_geo": "us"},
"system": "You are a helpful assistant."
}')
echo "Inference geo: $(jq -r '.model.inference_geo' <<< "$agent")"
```
```bash CLI
ant apply geo-pinned-assistant.md
```
```markdown
---
name: Geo-pinned assistant
model:
id: claude-opus-5-5
inference_geo: us
---
You are a helpful assistant.
```
```python Python
agent = client.beta.agents.create(
name="Geo-pinned assistant",
model={
"id": "claude-opus-5-5",
"inference_geo": "us",
},
system="You are a helpful assistant.",
)
print(f"Inference geo: {agent.model.inference_geo}")
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Geo-pinned assistant",
model: { id: "claude-opus-5-5", inference_geo: "us" },
system: "You are a helpful assistant.",
});
console.log(`Inference geo: ${agent.model.inference_geo}`);
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Geo-pinned assistant",
Model = new BetaManagedAgentsModelConfigParams
{
ID = BetaManagedAgentsModel.ClaudeOpus5_5,
InferenceGeo = "us",
},
System = "You are a helpful assistant.",
});
Console.WriteLine($"Inference geo: {agent.Model.InferenceGeo}");
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Geo-pinned assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
InferenceGeo: anthropic.String("us"),
},
System: anthropic.String("You are a helpful assistant."),
})
if err != nil {
panic(err)
}
fmt.Printf("Inference geo: %s\n", agent.Model.InferenceGeo)
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Geo-pinned assistant")
.model(
BetaManagedAgentsModelConfigParams.builder()
.id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.inferenceGeo("us")
.build()
)
.system("You are a helpful assistant.")
.build()
);
IO.println("Inference geo: " + agent.model().inferenceGeo().orElseThrow());
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Geo-pinned assistant',
model: BetaManagedAgentsModelConfigParams::with(
id: 'claude-opus-5-5',
inferenceGeo: 'us',
),
system: 'You are a helpful assistant.',
);
echo "Inference geo: {$agent->model->inferenceGeo}\n";
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Geo-pinned assistant",
model: {id: "claude-opus-5-5", inference_geo: "us"},
system_: "You are a helpful assistant."
)
puts "Inference geo: #{agent.model.inference_geo}"
```
Un vincolo `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) viene convalidato rispetto agli [`allowed_inference_geos`](https://platform.claude.com/docs/it/manage-claude/data-residency#workspace-level-restrictions) 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` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) su un modello che non supporta il vincolo geografico dell'inferenza restituisce un errore 400; consulta [Disponibilità dei modelli](https://platform.claude.com/docs/it/manage-claude/data-residency#model-availability) per i modelli che lo supportano. In una configurazione `multiagent` (csharp, go: `Multiagent`), il vincolo dell'agente e il vincolo di ogni agente elencato nella lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) o `workflows` (csharp, go: `Workflows`) devono essere tutti impostati sullo stesso valore o tutti non impostati; consulta [Orchestrazione multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration). Per modificare o rimuovere il vincolo in seguito, aggiorna l'oggetto `model` (csharp, go: `Model`) dell'agente; fornire `model` (csharp, go: `Model`) senza `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) lo rimuove, come descritto in [Semantica degli aggiornamenti](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-semantics).
## Aggiorna un agente
L'aggiornamento di un agente genera una nuova versione quando la configurazione cambia. Il campo `version` (csharp, go: `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.
```bash cURL
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 '{
"version": '"$AGENT_VERSION"',
"system": "You are a helpful coding agent. Always write tests."
}'
)
echo "New version: $(jq -r '.version' <<< "$updated_agent")"
```
```bash CLI
ant apply coding-assistant.md
```
```markdown
---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful coding agent. Always write tests.
```
```python Python
updated_agent = client.beta.agents.update(
agent.id,
version=agent.version,
system="You are a helpful coding agent. Always write tests.",
)
print(f"New version: {updated_agent.version}")
```
```typescript TypeScript
const updatedAgent = await client.beta.agents.update(agent.id, {
version: agent.version,
system: "You are a helpful coding agent. Always write tests.",
});
console.log(`New version: ${updatedAgent.version}`);
```
```csharp C#
var updatedAgent = await client.Beta.Agents.Update(agent.ID, new()
{
Version = agent.Version,
System = "You are a helpful coding agent. Always write tests.",
});
Console.WriteLine($"New version: {updatedAgent.Version}");
```
```go Go
updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Version: anthropic.Int(agent.Version),
System: anthropic.String("You are a helpful coding agent. Always write tests."),
})
if err != nil {
panic(err)
}
fmt.Printf("New version: %d\n", updatedAgent.Version)
```
```java Java
var updatedAgent = client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.version(agent.version())
.system("You are a helpful coding agent. Always write tests.")
.build()
);
IO.println("New version: " + updatedAgent.version());
```
```php PHP
$updatedAgent = $client->beta->agents->update(
$agent->id,
version: $agent->version,
system: 'You are a helpful coding agent. Always write tests.',
);
echo "New version: {$updatedAgent->version}\n";
```
```ruby Ruby
updated_agent = client.beta.agents.update(
agent.id,
version: agent.version,
system_: "You are a helpful coding agent. Always write tests."
)
puts "New version: #{updated_agent.version}"
```
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:
```bash cURL
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")"
```
```bash CLI
ant beta:agents update \
--agent-id "$AGENT_ID" \
--description "Writes and reviews code."
```
```python Python
unconditional_agent = client.beta.agents.update(
agent.id,
description="Writes and reviews code.",
)
print(f"New version: {unconditional_agent.version}")
```
```typescript TypeScript
const unconditionalAgent = await client.beta.agents.update(agent.id, {
description: "Writes and reviews code.",
});
console.log(`New version: ${unconditionalAgent.version}`);
```
```csharp C#
var unconditionalAgent = await client.Beta.Agents.Update(agent.ID, new()
{
Description = "Writes and reviews code.",
});
Console.WriteLine($"New version: {unconditionalAgent.Version}");
```
```go Go
unconditionalAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Description: anthropic.String("Writes and reviews code."),
})
if err != nil {
panic(err)
}
fmt.Printf("New version: %d\n", unconditionalAgent.Version)
```
```java Java
var unconditionalAgent = client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.description("Writes and reviews code.")
.build()
);
IO.println("New version: " + unconditionalAgent.version());
```
```php PHP
$unconditionalAgent = $client->beta->agents->update(
$agent->id,
description: 'Writes and reviews code.',
);
echo "New version: {$unconditionalAgent->version}\n";
```
```ruby Ruby
unconditional_agent = client.beta.agents.update(
agent.id,
description: "Writes and reviews code."
)
puts "New version: #{unconditional_agent.version}"
```
### Semantica degli aggiornamenti
* **`version` (csharp, go: `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` (csharp, go: `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` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `name` (csharp, go: `Name`), `description` (csharp, go: `Description`)) vengono sostituiti con il nuovo valore. `system` (csharp, go: `System`; ruby: `system_`) e `description` (csharp, go: `Description`) possono essere cancellati passando `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`). `model` (csharp, go: `Model`) e `name` (csharp, go: `Name`) sono obbligatori e non possono essere cancellati. All'interno di un oggetto `model` (csharp, go: `Model`) che fornisci, `effort` (csharp, go: `Effort`) è l'unica eccezione: se l'`id` (csharp, go: `ID`) del modello non cambia, omettere `effort` (csharp, go: `Effort`) lascia invariato il livello di effort memorizzato. Se modifichi l'`id` (csharp, go: `ID`) del modello, un `effort` (csharp, go: `Effort`) omesso viene reimpostato al valore predefinito del nuovo modello. Gli altri campi di `model` (csharp, go: `Model`) vengono sostituiti insieme all'oggetto: fornire `model` (csharp, go: `Model`) senza `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) rimuove il vincolo di inference geo dell'agente.
* **I campi array** (`tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (csharp, go: `Skills`)) vengono completamente sostituiti dal nuovo array. Per cancellare completamente un campo array, passa `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) o un array vuoto.
* **`multiagent` (csharp, go: `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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) che invii sostituisce la lista memorizzata. Qualsiasi altro aggiornamento che invia `multiagent` (csharp, go: `Multiagent`) sostituisce il blocco memorizzato nella sua interezza, e le impostazioni che omette assumono i valori predefiniti. Passa `"multiagent": null` (python: `multiagent=None`; typescript: `multiagent: null`; ruby: `multiagent: nil`; go: `Multiagent: param.NullStruct[anthropic.BetaManagedAgentsMultiagentParamsUnion]()`; java: `.multiagent(Optional.empty())`; csharp: `Multiagent = null`; php: `requestOptions: ['extraBodyParams' => ['multiagent' => null]]`) per cancellare l'intero blocco. All'interno del blocco, `null` reimposta un'impostazione al suo valore predefinito, quindi impostare `workflows` (csharp, go: `Workflows`) su `null` attiva i workflow dinamici. Consulta [Attiva i workflow dinamici](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
* **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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) degli altri agenti non vengono aggiornate.** Gli agenti che elencano questo agente nella lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) o `workflows` (csharp, go: `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` (csharp, go: `Version`). Per delegare alla nuova versione, [aggiorna l'agente che lo elenca](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#list-the-subagents) in modo che la lista faccia riferimento alla nuova versione.
L'aggiornamento seguente cancella la descrizione, elimina la chiave `team` da `metadata` (csharp, go: `Metadata`) e imposta `workflows` (csharp, go: `Workflows`) su `null`, il che attiva i workflow dinamici:
```bash cURL
cleared_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": null,
"metadata": {"team": null},
"multiagent": {"type": "multiagent_20261001", "workflows": null}
}')
echo "Description: $(jq -r '.description' <<< "$cleared_agent")"
```
```bash CLI
ant apply code-reviewer.md
```
```markdown
---
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.
```
Il file non contiene più `description` né la chiave `team`, quindi `ant apply` invia `null` per essi. Eliminare un'impostazione all'interno di `multiagent` ne mantiene il valore memorizzato, quindi il file imposta `workflows` su `null`.
```python Python
cleared_agent = client.beta.agents.update(
agent.id,
description=None,
metadata={"team": None},
multiagent={"type": "multiagent_20261001", "workflows": None},
)
print(f"Description: {cleared_agent.description}")
```
```typescript TypeScript
const clearedAgent = await client.beta.agents.update(agent.id, {
description: null,
metadata: { team: null },
multiagent: { type: "multiagent_20261001", workflows: null },
});
console.log(`Description: ${clearedAgent.description}`);
```
```csharp C#
var clearedAgent = await client.Beta.Agents.Update(agent.ID, new()
{
Description = null,
Metadata = new Dictionary { ["team"] = null },
Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null },
});
Console.WriteLine($"Description: {clearedAgent.Description}");
```
```go Go
// Metadata è una map[string]string, quindi invia il null per team come opzione della richiesta.
clearedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Description: param.Null[string](),
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Workflows: param.NullStruct[anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion](),
},
},
}, option.WithJSONSet("metadata.team", nil))
if err != nil {
panic(err)
}
fmt.Printf("Description: %q\n", clearedAgent.Description)
```
```java Java
var clearedAgent = client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.description(Optional.empty())
.metadata(
AgentUpdateParams.Metadata.builder()
.putAdditionalProperty("team", JsonValue.from(null))
.build()
)
.multiagent(
BetaManagedAgentsMultiagent20261001Params.builder()
.workflows(Optional.empty())
.build()
)
.build()
);
IO.println("Description: " + clearedAgent.description().orElse(null));
```
```php PHP
// update() scarta gli argomenti null, quindi passa i null in extraBodyParams.
$clearedAgent = $client->beta->agents->update(
$agent->id,
requestOptions: [
'extraBodyParams' => [
'description' => null,
'metadata' => ['team' => null],
'multiagent' => ['type' => 'multiagent_20261001', 'workflows' => null],
],
],
);
echo 'Description: ' . json_encode($clearedAgent->description) . "\n";
```
```ruby Ruby
cleared_agent = client.beta.agents.update(
agent.id,
description: nil,
metadata: {team: nil},
multiagent: {type: :multiagent_20261001, workflows: nil}
)
puts "Description: #{cleared_agent.description.inspect}"
```
## Ciclo di vita dell'agente
| Operazione | Comportamento |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Aggiornamento** | Genera una nuova versione dell'agente quando la configurazione cambia. |
| **Elenco delle versioni** | Restituisce la cronologia completa delle versioni in modo da poter tracciare le modifiche nel tempo. |
| **Archiviazione** | Rende l'agente di sola lettura. Le nuove sessioni non possono farvi riferimento, ma le sessioni esistenti continuano a essere eseguite. |
### 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.
```bash cURL
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)"'
```
```bash CLI
ant beta:agents:versions list --agent-id "$AGENT_ID"
```
```python Python
for version in client.beta.agents.versions.list(agent.id):
print(f"Version {version.version}: {version.updated_at.isoformat()}")
```
```typescript TypeScript
for await (const version of client.beta.agents.versions.list(agent.id)) {
console.log(`Version ${version.version}: ${version.updated_at}`);
}
```
```csharp C#
var versions = await client.Beta.Agents.Versions.List(agent.ID);
await foreach (var version in versions.Paginate())
{
Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}");
}
```
```go Go
iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{})
for iter.Next() {
version := iter.Current()
fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
}
if err := iter.Err(); err != nil {
panic(err)
}
```
```java Java
for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
IO.println("Version " + version.version() + ": " + version.updatedAt());
}
```
```php PHP
foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
echo "Version {$version->version}: {$version->updatedAt->format(\DateTimeInterface::ATOM)}\n";
}
```
```ruby Ruby
client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version|
puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}"
end
```
### 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` (java, php: `archivedAt`; csharp, go: `ArchivedAt`) sul timestamp di archiviazione.
```bash cURL
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")"
```
```bash CLI
ant beta:agents archive --agent-id "$AGENT_ID"
```
```python Python
archived = client.beta.agents.archive(agent.id)
print(f"Archived at: {archived.archived_at.isoformat()}")
```
```typescript TypeScript
const archived = await client.beta.agents.archive(agent.id);
console.log(`Archived at: ${archived.archived_at}`);
```
```csharp C#
var archived = await client.Beta.Agents.Archive(agent.ID);
Console.WriteLine($"Archived at: {archived.ArchivedAt:O}");
```
```go Go
archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})
if err != nil {
panic(err)
}
fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339))
```
```java Java
var archived = client.beta().agents().archive(agent.id());
IO.println("Archived at: " + archived.archivedAt().orElseThrow());
```
```php PHP
$archived = $client->beta->agents->archive($agent->id);
echo "Archived at: {$archived->archivedAt->format(\DateTimeInterface::ATOM)}\n";
```
```ruby Ruby
archived = client.beta.agents.archive(agent.id)
puts "Archived at: #{archived.archived_at.iso8601}"
```
## Passaggi successivi
Configura gli strumenti disponibili per il tuo agente.
Collega al tuo agente competenze riutilizzabili basate sul filesystem per workflow specifici del dominio.
Crea una sessione per eseguire il tuo agente e iniziare a svolgere attività.
Tipi di eventi, flag della CLI per worker self-hosted, tipi di server MCP supportati, limiti di velocità e linee guida sul branding per Claude Managed Agents.