---
title: Avviare una sessione
url: https://platform.claude.com/docs/it/managed-agents/sessions
description: Crea una sessione per eseguire il tuo agente e iniziare a svolgere attività.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Una sessione è un'istanza di agente all'interno di un ambiente. Ogni sessione fa riferimento a un [agente](https://platform.claude.com/docs/it/managed-agents/agent-setup) e a un [ambiente](https://platform.claude.com/docs/it/managed-agents/environments) (entrambi creati separatamente) e mantiene la cronologia della conversazione attraverso più interazioni. Le sessioni seguono un ciclo di vita in due fasi: prima [crea la sessione](https://platform.claude.com/docs/it/managed-agents/sessions#creating-a-session), poi [invia un evento utente](https://platform.claude.com/docs/it/managed-agents/sessions#starting-the-session) per avviare il lavoro. Puoi anche unire entrambe le fasi in un'unica chiamata con [`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)](https://platform.claude.com/docs/it/managed-agents/sessions#seed-the-session-with-initial-events).

## Creare una sessione

Una sessione richiede un ID `agent` e un ID `environment`. Gli agenti sono risorse con versioni; passare l'ID `agent` (csharp, go: `Agent`) come stringa crea la sessione con l'ultima versione dell'agente.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

Per vincolare una sessione a una versione specifica dell'agente, passa un oggetto. Questo ti consente di controllare esattamente quale versione viene eseguita e di distribuire gradualmente le nuove versioni in modo indipendente.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": {"type": "agent", "id": "'"$AGENT_ID"'", "version": 1},
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent:
    type: agent
    id: $AGENT_ID
    version: 1
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  pinned_session = client.beta.sessions.create(
      agent={"type": "agent", "id": agent.id, "version": 1},
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const pinnedSession = await client.beta.sessions.create({
    agent: { type: "agent", id: agent.id, version: 1 },
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var pinnedSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentParams
      {
          Type = BetaManagedAgentsAgentParamsType.Agent,
          ID = agent.ID,
          Version = 1,
      },
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
  			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
  			ID:      agent.ID,
  			Version: anthropic.Int(1),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentParams.builder()
          .type(BetaManagedAgentsAgentParams.Type.AGENT)
          .id(agent.id())
          .version(1)
          .build())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $pinnedSession = $client->beta->sessions->create(
      agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  pinned_session = client.beta.sessions.create(
    agent: {type: :agent, id: agent.id, version: 1},
    environment_id: environment.id
  )
  ```
</CodeGroup>

### Inizializzare la sessione con eventi iniziali

Puoi creare una sessione e avviarne il lavoro in un'unica chiamata. `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) è un array opzionale di [eventi](https://platform.claude.com/docs/it/managed-agents/reference#event-types) iniziali da inviare alla sessione al momento della creazione, elaborati in ordine. Supporta gli eventi `user.message` e [`user.define_outcome`](https://platform.claude.com/docs/it/managed-agents/define-outcomes) e accetta un massimo di 50 eventi. Un elenco non vuoto avvia il ciclo dell'agente nella stessa chiamata: la sessione viene creata direttamente nello stato `running`, senza ulteriori richieste.

L'esempio seguente crea una sessione con un singolo `user.message` in `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`):

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  initial_events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  seeded_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      initial_events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  # gli initial_events non vengono restituiti nella risposta di creazione; rileggili
  # dall'elenco eventi della sessione.
  for event in client.beta.sessions.events.list(seeded_session.id):
      if event.type == "user.message":
          for block in event.content:
              if block.type == "text":
                  print(f"Seeded event: {block.text}")
  ```

  ```typescript TypeScript
  const seededSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });

  // gli initial_events non vengono riportati nella risposta di create; elenca gli eventi
  // della sessione per rileggere il messaggio inserito.
  for await (const event of client.beta.sessions.events.list(seededSession.id)) {
    if (event.type === "user.message") {
      for (const block of event.content) {
        if (block.type === "text") {
          console.log(`Seeded event: ${block.text}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  var seededSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  // gli initial_events non vengono restituiti nella risposta di creazione; rileggili
  // dall'elenco eventi della sessione.
  var seededEvents = await client.Beta.Sessions.Events.List(seededSession.ID);
  await foreach (var sessionEvent in seededEvents.Paginate())
  {
      if (sessionEvent.TryPickUserMessage(out var userMessage))
      {
          foreach (var contentBlock in userMessage.Content)
          {
              if (contentBlock.TryPickBetaManagedAgentsTextBlock(out var textBlock))
              {
                  Console.WriteLine($"Seeded event: {textBlock.Text}");
              }
          }
      }
  }
  ```

  ```go Go
  seededSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  // gli initial_events non vengono restituiti nella risposta di creazione, quindi elenca gli
  // eventi della sessione per rileggere lo user.message iniziale.
  seededEvents, err := client.Beta.Sessions.Events.List(ctx, seededSession.ID, anthropic.BetaSessionEventListParams{})
  if err != nil {
  	panic(err)
  }
  for _, event := range seededEvents.Data {
  	if event.Type != "user.message" {
  		continue
  	}
  	for _, contentBlock := range event.AsUserMessage().Content {
  		if contentBlock.Type == "text" {
  			fmt.Printf("Seeded event: %s\n", contentBlock.AsText().Text)
  		}
  	}
  }
  ```

  ```java Java
  var seededSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
          .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
          .addTextContent("List the files in the working directory.")
          .build())
      .build());
  // initial_events non vengono restituiti nella risposta di creazione; elenca gli
  // eventi della sessione per rileggere lo user.message inserito.
  for (var event : client.beta().sessions().events().list(seededSession.id()).autoPager()) {
      if (event.isUserMessage()) {
          for (var contentBlock : event.asUserMessage().content()) {
              if (contentBlock.isText()) {
                  IO.println("Seeded event: " + contentBlock.asText().text());
              }
          }
      }
  }
  ```

  ```php PHP
  $seededSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );

  // gli initial_events non vengono restituiti nella risposta di creazione; rileggili
  // dall'elenco eventi della sessione.
  $seededEvents = $client->beta->sessions->events->list($seededSession->id);
  foreach ($seededEvents->getItems() as $event) {
      if ($event->type === 'user.message') {
          echo "Seeded event: {$event->content[0]->text}\n";
      }
  }
  ```

  ```ruby Ruby
  seeded_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )

  # gli initial_events non vengono restituiti nella risposta di creazione; rileggili
  # dall'elenco eventi della sessione.
  client.beta.sessions.events.list(seeded_session.id).auto_paging_each do |event|
    next unless event.type == :"user.message"
    event.content.each do |block|
      puts "Seeded event: #{block.text}" if block.type == :text
    end
  end
  ```
</CodeGroup>

Nessun altro tipo di evento è accettato. Gli eventi che rispondono a un turno dell'agente (`user.tool_confirmation`, `user.tool_result` e `user.custom_tool_result`) non sono accettati perché non esiste ancora alcun turno dell'agente, e `user.interrupt` non è accettato perché non c'è alcun turno da interrompere. A differenza di `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) in un deployment pianificato, gli `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) di una sessione non accettano `system.message`.

Ogni evento in `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) viene convalidato e salvato prima che venga restituita la risposta di creazione, nell'ordine dell'elenco, con un ID assegnato dal server, esattamente come se lo avessi inviato all'endpoint di [invio eventi](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#send-events) subito dopo la creazione. Anche le regole sul contenuto di ciascun evento sono le stesse di quell'endpoint. Un elenco vuoto equivale a omettere il campo. La convalida è del tipo tutto o niente: se un qualsiasi evento non supera la convalida, l'intera richiesta viene rifiutata e nessuna sessione viene creata.

La richiesta di creazione viene rifiutata nei seguenti casi:

| Condizione                                                                                                                                                       | Stato |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| Più di un evento `user.define_outcome`                                                                                                                           | 400   |
| Un evento `user.define_outcome` senza `rubric`                                                                                                                   | 400   |
| Più di 100 [blocchi di contenuto `document`](https://platform.claude.com/docs/it/build-with-claude/files#document-blocks) provenienti da file nell'intero elenco | 400   |
| Un corpo della richiesta superiore a 32 MB                                                                                                                       | 413   |

Un evento `user.define_outcome` in `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) viene accettato alle stesse condizioni previste per l'invio a una sessione esistente; consulta [Definire i risultati](https://platform.claude.com/docs/it/managed-agents/define-outcomes).

### Sovrascrivere la configurazione dell'agente per una sessione

Puoi passare `agent` (csharp, go: `Agent`) in tre forme: una stringa con l'ID dell'agente, un oggetto con versione vincolata (`type: "agent"`) oppure un oggetto di override. La forma con override modifica parti della configurazione dell'agente per una singola sessione. Usala per provare un modello diverso o concedere uno strumento aggiuntivo in una sessione senza creare una nuova versione dell'agente. Per la forma con override, imposta `type` su `agent_with_overrides` e passa l'`id` (csharp, go: `ID`) dell'agente e, facoltativamente, una `version` (csharp, go: `Version`) (ometti `version` (csharp, go: `Version`) per usare l'ultima versione dell'agente). Quindi includi uno qualsiasi tra `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) o `skills` (csharp, go: `Skills`) con i valori che la sessione deve usare.

Ogni campo sovrascrivibile segue le stesse tre regole:

* **Ometti il campo:** la sessione eredita il valore dalla versione dell'agente a cui fa riferimento.

* **Imposta il campo su `null`, o su un array vuoto per i campi di tipo elenco:** la sessione viene eseguita con quel campo svuotato. Questa regola si applica integralmente a `system` (csharp, go: `System`; ruby: `system_`) e `skills` (csharp, go: `Skills`). Ci sono tre eccezioni:

  * `model` non può mai essere svuotato. Una sessione ha sempre bisogno di un modello, quindi `model: null` restituisce un errore 400 `agent_model_required`.
  * Svuotare `tools` restituisce un errore 400 quando le `skills` (csharp, go: `Skills`) effettive della sessione non sono vuote, perché le skill richiedono lo strumento `read`. Altrimenti, `tools: null` e `tools: []` svuotano il campo.
  * Svuotare `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) restituisce un errore 400 quando i `tools` (csharp, go: `Tools`) effettivi della sessione contengono ancora un `mcp_toolset` che fa riferimento a uno dei server dell'agente. Sovrascrivi `tools` (csharp, go: `Tools`) nella stessa richiesta per rimuovere quelle voci `mcp_toolset`, quindi svuota `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).

* **Imposta il campo su un valore:** il valore sostituisce integralmente quello dell'agente. Gli override non vengono mai uniti alla configurazione dell'agente, quindi un override di `tools` (csharp, go: `Tools`) deve elencare ogni strumento che la sessione deve avere. Allo stesso modo, un override di `model` (csharp, go: `Model`) sostituisce integralmente 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`) dell'override. Un livello non supportato dal modello restituisce un errore 400, e un override di `model` (csharp, go: `Model`) senza `effort` (csharp, go: `Effort`) viene eseguito al livello di effort predefinito di quel modello.

Gli override si applicano solo alla sessione che crei. Non modificano la risorsa agente né creano una nuova versione dell'agente, quindi le altre sessioni che fanno riferimento allo stesso agente non sono interessate.

Nella risposta, l'oggetto `agent` (csharp, go: `Agent`) riflette la configurazione con cui la sessione viene eseguita dopo l'applicazione degli override. Il suo `id` (csharp, go: `ID`) e la sua `version` (csharp, go: `Version`) identificano comunque l'agente e la versione a cui vengono applicati gli override. Questo ti consente di risalire dalla sessione al suo agente di base.

L'esempio seguente avvia una sessione che sovrascrive il modello e svuota il prompt di sistema:

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-sonnet-5-5"},
        "system": null
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # The response's `agent` is the resolved snapshot: each override replaces that
  # field for this session only, and the agent resource keeps its id and version.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-sonnet-5-5
    system: null
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  override_session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          "model": {"id": "claude-sonnet-5-5"},
          "system": None,  # clear the agent's system prompt for this session
      },
      environment_id=environment.id,
  )
  # L'agente nella risposta è lo snapshot risolto con gli override applicati.
  print(f"Model: {override_session.agent.model.id}")
  print(f"System: {override_session.agent.system}")
  ```

  ```typescript TypeScript
  const overrideSession = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      model: { id: "claude-sonnet-5-5" },
      system: null // clear the agent's system prompt for this session
    },
    environment_id: environment.id
  });
  // L'agente nella risposta è lo snapshot risolto con gli override applicati.
  console.log(`Model: ${overrideSession.agent.model.id}`);
  console.log(`System: ${overrideSession.agent.system}`);
  ```

  ```csharp C#
  var overrideSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeSonnet5_5,
          },
          System = null, // clear the agent's system prompt for this session
      },
      EnvironmentID = environment.ID,
  });
  // L'agente nella risposta è lo snapshot risolto con gli override applicati.
  Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
  Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
  ```

  ```go Go
  overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID: anthropic.BetaManagedAgentsModelClaudeSonnet5_5,
  			},
  			// Cancella il prompt di sistema dell'agente per questa sessione.
  			System: param.Null[string](),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  // L'agente nella risposta è lo snapshot risolto con gli override applicati.
  fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
  fmt.Printf("System: %q\n", overrideSession.Agent.System)
  ```

  ```java Java
  var overrideSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_SONNET_5_5)
              .build())
          .system((String) null) // clear the agent's system prompt for this session
          .build())
      .environmentId(environment.id())
      .build());
  // L'agente nella risposta è lo snapshot risolto con gli override applicati.
  IO.println("Model: " + overrideSession.agent().model().id());
  IO.println("System: " + overrideSession.agent().system().orElse("null"));
  ```

  ```php PHP
  $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
      id: $agent->id,
      type: 'agent_with_overrides',
      model: ['id' => 'claude-sonnet-5-5'],
  );
  // Azzera il prompt di sistema per questa sessione. L'accesso come array è essenziale qui:
  // create() rimuove i null dagli array raw e ::with() tratta gli argomenti null come omessi.
  $overrides['system'] = null;

  $overrideSession = $client->beta->sessions->create(
      agent: $overrides,
      environmentID: $environment->id,
  );
  // L'agente nella risposta è lo snapshot risolto con gli override applicati.
  echo "Model: {$overrideSession->agent->model->id}\n";
  echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
  ```

  ```ruby Ruby
  # L'override del prompt di sistema è `system_` (underscore finale) perché il semplice
  # `system` è Kernel#system di Ruby. Impostarlo a nil cancella il prompt.
  override_session = client.beta.sessions.create(
    agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
      type: :agent_with_overrides,
      id: agent.id,
      model: {id: "claude-sonnet-5-5"},
      system_: nil
    ),
    environment_id: environment.id
  )
  # L'agente nella risposta è lo snapshot risolto con gli override applicati.
  puts "Model: #{override_session.agent.model.id}"
  puts "System: #{override_session.agent.system_.inspect}"
  ```
</CodeGroup>

#### Vincolare l'area geografica di inferenza per una sessione

Poiché un override di `model` (csharp, go: `Model`) sostituisce integralmente l'oggetto `model` (csharp, go: `Model`) dell'agente, imposta o rimuove anche il vincolo dell'["inference geo"](https://platform.claude.com/docs/it/manage-claude/data-residency) (area geografica di inferenza) del modello per la sessione: un override che include `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) vincola l'area geografica che serve le richieste al modello della sessione, mentre uno che lo omette rimuove il vincolo dell'agente, così la sessione segue il `default_inference_geo` del workspace. Il valore sovrascritto viene convalidato rispetto agli `allowed_inference_geos` del workspace al momento della creazione della sessione.

L'esempio seguente avvia una sessione da un agente il cui modello non ha alcun vincolo geografico, vincola le richieste al modello della sessione all'inferenza negli Stati Uniti includendo `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) nell'override di `model` (csharp, go: `Model`) e stampa il valore restituito in `agent.model` (csharp, go: `Agent.Model`) nella risposta:

<CodeGroup>
  ```bash cURL
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"}
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-opus-5-5
      inference_geo: us
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          # Sostituisce interamente il `model` dell'agente: ripeti `id`, aggiungi `inference_geo` per fissare.
          "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      },
      environment_id=environment.id,
  )
  print(f"Inference geo: {session.agent.model.inference_geo}")
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      // Sostituisce interamente il `model` dell'agente: ridichiara `id`, aggiungi `inference_geo` per fissare.
      model: { id: "claude-opus-5-5", inference_geo: "us" }
    },
    environment_id: environment.id
  });
  console.log(`Inference geo: ${session.agent.model.inference_geo}`);
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          // Sostituisce interamente il `model` dell'agente: ripeti `id`, aggiungi `inference_geo` per fissare.
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeOpus5_5,
              InferenceGeo = "us",
          },
      },
      EnvironmentID = environment.ID,
  });
  Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			// Sostituisce interamente il `model` dell'agente: ripeti `id`, aggiungi `inference_geo` per fissare.
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID:           anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  				InferenceGeo: anthropic.String("us"),
  			},
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          // Sostituisce interamente il `model` dell'agente: ridichiara `id`, aggiungi `inference_geo` per fissare.
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
              .inferenceGeo("us")
              .build())
          .build())
      .environmentId(environment.id())
      .build());
  IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: BetaManagedAgentsAgentWithOverridesParams::with(
          id: $agent->id,
          type: 'agent_with_overrides',
          // Sostituisce interamente il `model` dell'agente: ripeti `id`, aggiungi `inference_geo` per fissarlo.
          model: BetaManagedAgentsModelConfigParams::with(
              id: 'claude-opus-5-5',
              inferenceGeo: 'us',
          ),
      ),
      environmentID: $environment->id,
  );
  echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: {
      type: :agent_with_overrides,
      id: agent.id,
      # Sostituisce interamente il `model` dell'agente: ripeti `id`, aggiungi `inference_geo` per fissare.
      model: {id: "claude-opus-5-5", inference_geo: "us"}
    },
    environment_id: environment.id
  )
  puts "Inference geo: #{session.agent.model.inference_geo}"
  ```
</CodeGroup>

<Tip>
  L'agente definisce il comportamento di Claude all'interno della sessione, inclusi il modello, il prompt di sistema, gli strumenti e i server MCP. Consulta [Definire il tuo agente](https://platform.claude.com/docs/it/managed-agents/agent-setup) per i dettagli.
</Tip>

### Impostare un budget per la sessione

Per limitare quanto può spendere una sessione, passa l'oggetto opzionale `budget` (csharp, go: `Budget`) quando la crei. Un budget è un tetto massimo rigido sul costo di listino della sessione: la piattaforma calcola il prezzo di tutto ciò che la sessione consuma alle tariffe di listino pubbliche, e la sessione smette di inviare nuove richieste al modello quando il totale progressivo raggiunge `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). Imposta `type` (csharp, go: `Type`) su `limit` e assegna a `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) un `amount` (csharp, go: `Amount`) e una `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) è un numero intero di centesimi di dollaro statunitense scritto come stringa, ad esempio `"125"` per $1,25. L'API accetta una stringa anziché un numero, così non viene mai applicato alcun arrotondamento in virgola mobile. `USD` è attualmente l'unica valuta supportata. Quando la sessione raggiunge il limite, si mette in pausa e diventa inattiva con il motivo di arresto `budget_reached`. Il limite viene applicato tra una richiesta al modello e l'altra, quindi la richiesta che lo supera viene completata prima e il costo di listino finale della sessione può risultare [leggermente superiore al limite](https://platform.claude.com/docs/it/managed-agents/budgets#when-a-session-reaches-its-budget). Un budget può essere associato solo al momento della creazione: puoi [modificarlo o rimuoverlo](https://platform.claude.com/docs/it/managed-agents/session-operations#updating-the-session-budget) in seguito, ma non puoi aggiungerne uno a una sessione creata senza.

L'esempio seguente crea una sessione con un budget di $1,25:

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"}
      }
    }'
  ```

  ```bash CLI
  # Mantieni l'importo tra virgolette così viene inviato come stringa, non come numero.
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID" \
    --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "125", "currency": "USD"},
      },
  )
  print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: { amount: "125", currency: "USD" }
    }
  });
  console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}");  // sesn_01... 125
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "125",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .budget(BetaManagedAgentsBudgetLimit.builder()
          .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
          .maxListCost(BetaMonetaryAmount.builder()
              .amount("125")
              .currency(BetaCurrency.USD)
              .build())
          .build())
      .build());
  IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount());  // sesn_01... 125
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
      ],
  );
  echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "125", currency: "USD"}
    }
  )
  puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
  ```
</CodeGroup>

Consulta [Budget delle sessioni](https://platform.claude.com/docs/it/managed-agents/budgets) per scoprire come funziona l'applicazione del limite, cosa concorre al costo di listino e come si comportano i budget nelle sessioni multiagente.

## Autenticazione MCP tramite vault

Se il tuo agente usa strumenti MCP che richiedono autenticazione, passa `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) alla creazione della sessione per fare riferimento a un vault contenente credenziali OAuth memorizzate. Anthropic gestisce il rinnovo dei token per tuo conto. Consulta [Autenticarsi con i vault](https://platform.claude.com/docs/it/managed-agents/vaults) per scoprire come creare vault e registrare credenziali.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "vault_ids": ["'"$VAULT_ID"'"]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  vault_ids:
    - $VAULT_ID
  YAML
  ```

  ```python Python
  vault_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      vault_ids=[vault.id],
  )
  ```

  ```typescript TypeScript
  const vaultSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  });
  ```

  ```csharp C#
  var vaultSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      VaultIds = [vault.ID],
  });
  ```

  ```go Go
  vaultSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	VaultIDs:      []string{vault.ID},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var vaultSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addVaultId(vault.id())
      .build());
  ```

  ```php PHP
  $vaultSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      vaultIDs: [$vault->id],
  );
  ```

  ```ruby Ruby
  vault_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  )
  ```
</CodeGroup>

## Avviare la sessione

Creare una sessione senza `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) registra la sessione ma non avvia alcun lavoro; la sandbox dell'ambiente inizia il provisioning non appena la sessione viene creata, quindi la prima chiamata a uno strumento non deve attenderla. Per delegare un'attività, invia eventi alla sessione usando un [evento utente](https://platform.claude.com/docs/it/managed-agents/reference#event-types). Per fornire invece il primo evento nella richiesta di creazione, consulta [Inizializzare la sessione con eventi iniziali](https://platform.claude.com/docs/it/managed-agents/sessions#seed-the-session-with-initial-events). La sessione funziona come una macchina a stati che tiene traccia dei progressi, mentre gli eventi guidano l'esecuzione effettiva.

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
    -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 '{
      "events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send \
    --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
              .addTextContent("List the files in the working directory.")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )
  ```
</CodeGroup>

Consulta [Flusso di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming) per scoprire come eseguire lo streaming delle risposte dell'agente e gestire le conferme degli strumenti.

Consulta [Stati della sessione](https://platform.claude.com/docs/it/managed-agents/session-operations#session-statuses) per gli stati attraverso cui passa una sessione.

## Passaggi successivi

<CardGroup cols={3}>
  <Card title="Operazioni sulle sessioni" icon="settings" href="https://platform.claude.com/docs/it/managed-agents/session-operations">
    Recupera, elenca, aggiorna, archivia ed elimina le sessioni di Claude Managed Agents.
  </Card>

  <Card title="Flusso di eventi della sessione" icon="lightning" href="https://platform.claude.com/docs/it/managed-agents/events-and-streaming">
    Invia eventi, esegui lo streaming delle risposte e interrompi o reindirizza la tua sessione durante l'esecuzione.
  </Card>

  <Card title="Deployment pianificati" icon="arrows-clockwise" href="https://platform.claude.com/docs/it/managed-agents/scheduled-deployments">
    Crea e gestisci deployment con la Claude API: esegui un agente secondo una pianificazione cron ricorrente e ispeziona la cronologia delle sue esecuzioni.
  </Card>
</CardGroup>