---
title: Inizia con Claude Managed Agents
url: https://platform.claude.com/docs/it/managed-agents/quickstart
description: Crea il tuo primo agente autonomo.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: Non idoneo per ZDR, ad eccezione di Managed Agents self-hosted. Le sessioni sono risorse con stato; le trascrizioni restano finché non le elimini.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): beta
---

Questa guida ti accompagna nella creazione di un agente, nella configurazione di un ambiente, nell’avvio di una sessione e nello streaming delle risposte dell’agente.

Lascia che Claude Code configuri il tuo agente per te

```text
/claude-api managed-agents-onboard
```

## Concetti fondamentali

| Concetto | Descrizione |
| ----- | ----- |
| **Agente** | Il modello, il prompt di sistema, gli strumenti, i server MCP e le skill |
| **Ambiente** | Configurazione del luogo in cui vengono eseguite le sessioni: una sandbox cloud gestita da Anthropic oppure una sandbox self-hosted sulla tua infrastruttura |
| **Sessione** | Un’istanza di agente in esecuzione all’interno di un ambiente, che svolge un compito specifico e genera output |
| **Eventi** | Messaggi scambiati tra la tua applicazione e l’agente (turni dell’utente, risultati degli strumenti, aggiornamenti di stato) |

## Prima di iniziare

<Steps continues>
  <Step title="Crea un account Claude Console">
    [Registrati](https://platform.claude.com/) per un account Claude Console, oppure accedi a quello che hai già.
  </Step>

  <Step title="Scegli come autenticarti">
    L’accesso tramite la CLI è consigliato per lo sviluppo locale.

    Follow the steps for one of the following options.
  </Step>
</Steps>

**CLI**

<Steps continued>
  <Step title="Installa la CLI" stepNumber={3}>
    <Tabs noDeepLinks>
      <Tab title="Homebrew (macOS)">
        ```bash
        brew install anthropics/tap/ant
        ```
      </Tab>

      <Tab title="curl (Linux/WSL)">
        Per gli ambienti Linux, scarica direttamente il binario della release.

        ```bash
        VERSION=2.12.1
        OS=$(uname -s | tr '[:upper:]' '[:lower:]')
        case $(uname -m) in
          x86_64) ARCH=amd64 ;;
          aarch64) ARCH=arm64 ;;
        esac
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
          | sudo tar -xz -C /usr/local/bin ant
        ```

        Puoi trovare tutte le release nella [pagina delle release su GitHub](https://github.com/anthropics/anthropic-cli/releases).
      </Tab>

      <Tab title="go install">
        Puoi anche installare la CLI dal codice sorgente con `go install`, che richiede Go 1.26.10 o successivo.

        ```bash
        go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latest
        ```

        `go install` posiziona il binario in `$(go env GOPATH)/bin`. Aggiungi quella directory al tuo `PATH` se non è già presente:

        ```bash
        export PATH="$PATH:$(go env GOPATH)/bin"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Accedi" stepNumber={4}>
    ```bash
    ant auth login
    ```

    Una volta completato l’accesso, gli SDK e la CLI rileveranno automaticamente le tue credenziali.
  </Step>
</Steps>

**Chiave API**

<Steps continued>
  <Step title="Crea una chiave API" stepNumber={3}>
    Crea una [chiave API](https://platform.claude.com/settings/keys) nella Claude Console.
  </Step>

  <Step title="Imposta la variabile d’ambiente" stepNumber={4}>
    Gli SDK e la CLI leggono la tua chiave da `ANTHROPIC_API_KEY`:

    ```bash
    export ANTHROPIC_API_KEY="your-api-key-here"
    ```
  </Step>
</Steps>

**Chiave API**

Per eseguire gli esempi della CLI, installa la CLI:

<Tabs noDeepLinks>
  <Tab title="Homebrew (macOS)">
    ```bash
    brew install anthropics/tap/ant
    ```
  </Tab>

  <Tab title="curl (Linux/WSL)">
    Per gli ambienti Linux, scarica direttamente il binario della release.

    ```bash
    VERSION=2.12.1
    OS=$(uname -s | tr '[:upper:]' '[:lower:]')
    case $(uname -m) in
      x86_64) ARCH=amd64 ;;
      aarch64) ARCH=arm64 ;;
    esac
    curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
      | sudo tar -xz -C /usr/local/bin ant
    ```

    Puoi trovare tutte le release nella [pagina delle release su GitHub](https://github.com/anthropics/anthropic-cli/releases).
  </Tab>

  <Tab title="go install">
    Puoi anche installare la CLI dal codice sorgente con `go install`, che richiede Go 1.26.10 o successivo.

    ```bash
    go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latest
    ```

    `go install` posiziona il binario in `$(go env GOPATH)/bin`. Aggiungi quella directory al tuo `PATH` se non è già presente:

    ```bash
    export PATH="$PATH:$(go env GOPATH)/bin"
    ```
  </Tab>
</Tabs>

## Installa l’SDK

<Tabs>
  <Tab title="Python">
    ```bash
    pip install anthropic
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash
    npm install @anthropic-ai/sdk
    ```
  </Tab>

  <Tab title="Java">
    <Tabs>
      <Tab title="Gradle">
        ```kotlin
        implementation("com.anthropic:anthropic-java:3.12.0")
        ```
      </Tab>

      <Tab title="Maven">
        ```xml
        <dependency>
            <groupId>com.anthropic</groupId>
            <artifactId>anthropic-java</artifactId>
            <version>3.12.0</version>
        </dependency>
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Go">
    ```bash
    go get github.com/anthropics/anthropic-sdk-go/v2
    ```
  </Tab>

  <Tab title="C#">
    ```bash
    dotnet add package Anthropic
    ```
  </Tab>

  <Tab title="Ruby">
    ```bash
    bundle add anthropic
    ```
  </Tab>

  <Tab title="PHP">
    ```bash
    composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7"
    ```
  </Tab>
</Tabs>

## Crea la tua prima sessione

<Steps>
  <Step title="Crea un agente">
    Crea un agente che definisca il modello, il “system prompt” (prompt di sistema) e gli strumenti disponibili.

    <CodeGroup defaultLanguage="CLI">
      **Accesso tramite CLI**

      <CodeGroupItem>
        ```bash cURL
        curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
          -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
          -H "anthropic-version: 2026-10-21" \
          -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 assistant. Write clean, well-documented code.",
            "tools": [
              {
                "type": "agent_toolset_20260401",
                "configs": [
                  {"name": "web_search", "enabled": false},
                  {"name": "web_fetch", "enabled": false}
                ]
              }
            ]
          }'
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      **Chiave API**

      <CodeGroupItem>
        ```bash cURL
        curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
          -H "x-api-key: $ANTHROPIC_API_KEY" \
          -H "anthropic-version: 2026-10-21" \
          -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 assistant. Write clean, well-documented code.",
            "tools": [
              {
                "type": "agent_toolset_20260401",
                "configs": [
                  {"name": "web_search", "enabled": false},
                  {"name": "web_fetch", "enabled": false}
                ]
              }
            ]
          }'
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```bash CLI
        ant apply coding-assistant.md
        ```

        <File filename="coding-assistant.md">
          ```markdown
          ---
          name: Coding Assistant
          model: claude-opus-5-5
          tools:
            - type: agent_toolset_20260401
              configs:
                - name: web_search
                  enabled: false
                - name: web_fetch
                  enabled: false
          ---

          You are a helpful coding assistant. Write clean, well-documented code.
          ```
        </File>

        [`ant apply`](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/apply) stampa l’ID dell’agente e lo registra in `claude-lock.json`. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```python Python
        from anthropic import Anthropic

        client = Anthropic()

        agent = client.beta.agents.create(
            name="Coding Assistant",
            model="claude-opus-5-5",
            system="You are a helpful coding assistant. Write clean, well-documented code.",
            tools=[
                {
                    "type": "agent_toolset_20260401",
                    "configs": [
                        {"name": "web_search", "enabled": False},
                        {"name": "web_fetch", "enabled": False},
                    ],
                },
            ],
        )

        print(f"Agent ID: {agent.id}, version: {agent.version}")
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```typescript TypeScript
        import Anthropic from "@anthropic-ai/sdk";

        const client = new Anthropic();

        const agent = await client.beta.agents.create({
          name: "Coding Assistant",
          model: "claude-opus-5-5",
          system: "You are a helpful coding assistant. Write clean, well-documented code.",
          tools: [
            {
              type: "agent_toolset_20260401",
              configs: [
                { name: "web_search", enabled: false },
                { name: "web_fetch", enabled: false }
              ]
            }
          ]
        });

        console.log(`Agent ID: ${agent.id}, version: ${agent.version}`);
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```csharp C#
        using Anthropic;
        using Anthropic.Models.Beta.Agents;
        using Anthropic.Models.Beta.Environments;
        using Anthropic.Models.Beta.Sessions;
        using Anthropic.Models.Beta.Sessions.Events;

        var client = new AnthropicClient();

        var agent = await client.Beta.Agents.Create(new()
        {
            Name = "Coding Assistant",
            Model = BetaManagedAgentsModel.ClaudeOpus5_5,
            System = "You are a helpful coding assistant. Write clean, well-documented code.",
            Tools =
            [
                new BetaManagedAgentsAgentToolset20260401Params
                {
                    Configs =
                    [
                        new BetaManagedAgentsWebSearchToolConfigParams { Enabled = false },
                        new BetaManagedAgentsWebFetchToolConfigParams { Enabled = false },
                    ],
                },
            ],
        });

        Console.WriteLine($"Agent ID: {agent.ID}, version: {agent.Version}");
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```go Go
        package main

        import (
        	"context"
        	"fmt"

        	"github.com/anthropics/anthropic-sdk-go/v2"
        )

        func main() {
        	client := anthropic.NewClient()
        	ctx := context.Background()

        	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 assistant. Write clean, well-documented code."),
        		Tools: []anthropic.BetaAgentNewParamsToolUnion{{
        			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
        				Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{
        					{OfWebSearch: &anthropic.BetaManagedAgentsWebSearchToolConfigParams{
        						Enabled: anthropic.Bool(false),
        					}},
        					{OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
        						Enabled: anthropic.Bool(false),
        					}},
        				},
        			},
        		}},
        	})
        	if err != nil {
        		panic(err)
        	}

        	fmt.Printf("Agent ID: %s, version: %d\n", agent.ID, agent.Version)
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```java Java
        import com.anthropic.client.okhttp.AnthropicOkHttpClient;
        import com.anthropic.models.beta.agents.AgentCreateParams;
        import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params;
        import com.anthropic.models.beta.agents.BetaManagedAgentsModel;
        import com.anthropic.models.beta.agents.BetaManagedAgentsWebFetchToolConfigParams;
        import com.anthropic.models.beta.agents.BetaManagedAgentsWebSearchToolConfigParams;
        import com.anthropic.models.beta.environments.BetaCloudConfigParams;
        import com.anthropic.models.beta.environments.BetaLimitedNetworkParams;
        import com.anthropic.models.beta.environments.EnvironmentCreateParams;
        import com.anthropic.models.beta.sessions.SessionCreateParams;
        import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams;
        import com.anthropic.models.beta.sessions.events.EventSendParams;

        void main() {
            var client = AnthropicOkHttpClient.fromEnv();

            var agent = client.beta().agents().create(AgentCreateParams.builder()
                .name("Coding Assistant")
                .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
                .system("You are a helpful coding assistant. Write clean, well-documented code.")
                .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
                    .addConfig(BetaManagedAgentsWebSearchToolConfigParams.builder()
                        .enabled(false)
                        .build())
                    .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder()
                        .enabled(false)
                        .build())
                    .build())
                .build());

            IO.println("Agent ID: " + agent.id() + ", version: " + agent.version());
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```php PHP
        use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
        use Anthropic\Beta\Agents\BetaManagedAgentsModel;
        use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams;
        use Anthropic\Beta\Agents\BetaManagedAgentsWebSearchToolConfigParams;
        use Anthropic\Client;

        $client = new Client();

        $agent = $client->beta->agents->create(
            name: 'Coding Assistant',
            model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
            system: 'You are a helpful coding assistant. Write clean, well-documented code.',
            tools: [
                BetaManagedAgentsAgentToolset20260401Params::with(
                    configs: [
                        BetaManagedAgentsWebSearchToolConfigParams::with(enabled: false),
                        BetaManagedAgentsWebFetchToolConfigParams::with(enabled: false),
                    ],
                ),
            ],
        );

        echo "Agent ID: {$agent->id}, version: {$agent->version}\n";
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>

      <CodeGroupItem>
        ```ruby Ruby
        require "anthropic"

        client = Anthropic::Client.new

        agent = client.beta.agents.create(
          name: "Coding Assistant",
          model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
          system_: "You are a helpful coding assistant. Write clean, well-documented code.",
          tools: [
            {
              type: "agent_toolset_20260401",
              configs: [
                {name: "web_search", enabled: false},
                {name: "web_fetch", enabled: false}
              ]
            }
          ]
        )

        puts "Agent ID: #{agent.id}, version: #{agent.version}"
        ```

        Salva l’`agent.id` restituito. Lo utilizzerai in ogni sessione che crei.
      </CodeGroupItem>
    </CodeGroup>

    Il tipo di strumento `agent_toolset_20260401` abilita gli strumenti predefiniti per agenti (bash, operazioni sui file, ricerca web e altro). Questo esempio disabilita la ricerca web e il recupero web perché il compito di questa guida, scrivere un breve script Python, non fa uso del web. Fornisci a un agente [solo gli strumenti di cui ha bisogno](https://platform.claude.com/docs/it/managed-agents/secure-deployment#give-the-agent-the-smallest-tool-set). Consulta [Strumenti](https://platform.claude.com/docs/it/managed-agents/tools) per l’elenco completo e le opzioni di configurazione per ciascuno strumento.
  </Step>

  <Step title="Crea un ambiente">
    Un ambiente definisce la “sandbox” (ambiente isolato) in cui viene eseguito il tuo agente. Questo utilizza una [rete](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited` con i gestori di pacchetti consentiti, così il codice eseguito nella sandbox può raggiungere i [registri di pacchetti e gli host di codice](https://platform.claude.com/docs/it/managed-agents/environments#package-manager-hosts) pubblici. Con la rete `limited`, l’[elenco `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)](https://platform.claude.com/docs/it/managed-agents/environments#networking) si applica anche alla ricerca web e al recupero web, sebbene vengano eseguiti al di fuori della sandbox. Se non è elencato alcun host, come in questo ambiente, non restituiscono pagine né risultati di ricerca. Se un tuo agente usa questi strumenti, aggiungi a quell’elenco gli host di cui ha bisogno.

    <CodeGroup defaultLanguage="CLI">
      **Accesso tramite CLI**

      <CodeGroupItem>
        ```bash cURL
        curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
          -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
          -H "anthropic-version: 2026-10-21" \
          -H "anthropic-beta: managed-agents-2026-04-01" \
          -H "content-type: application/json" \
          -d '{
            "name": "quickstart-env",
            "config": {
              "type": "cloud",
              "networking": {"type": "limited", "allow_package_managers": true}
            }
          }'
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      **Chiave API**

      <CodeGroupItem>
        ```bash cURL
        curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
          -H "x-api-key: $ANTHROPIC_API_KEY" \
          -H "anthropic-version: 2026-10-21" \
          -H "anthropic-beta: managed-agents-2026-04-01" \
          -H "content-type: application/json" \
          -d '{
            "name": "quickstart-env",
            "config": {
              "type": "cloud",
              "networking": {"type": "limited", "allow_package_managers": true}
            }
          }'
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```bash CLI
        ant apply environment.yaml
        ```

        <File filename="environment.yaml">
          ```yaml
          # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
          name: quickstart-env
          config:
            type: cloud
            networking:
              type: limited
              allow_package_managers: true
          ```
        </File>

        [`ant apply`](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/apply) registra anche l’ID dell’ambiente in `claude-lock.json`. Per creare l’agente e l’ambiente con un solo comando, passa entrambi i file: `ant apply coding-assistant.md environment.yaml`.
      </CodeGroupItem>

      <CodeGroupItem>
        ```python Python
        environment = client.beta.environments.create(
            name="quickstart-env",
            config={
                "type": "cloud",
                "networking": {"type": "limited", "allow_package_managers": True},
            },
        )

        print(f"Environment ID: {environment.id}")
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```typescript TypeScript
        const environment = await client.beta.environments.create({
          name: "quickstart-env",
          config: {
            type: "cloud",
            networking: { type: "limited", allow_package_managers: true }
          }
        });

        console.log(`Environment ID: ${environment.id}`);
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```csharp C#
        var environment = await client.Beta.Environments.Create(new()
        {
            Name = "quickstart-env",
            Config = new BetaCloudConfigParams
            {
                Networking = new BetaLimitedNetworkParams { AllowPackageManagers = true },
            },
        });

        Console.WriteLine($"Environment ID: {environment.ID}");
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```go Go
        environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
        	Name: "quickstart-env",
        	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
        		OfCloud: &anthropic.BetaCloudConfigParams{
        			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
        				OfLimited: &anthropic.BetaLimitedNetworkParams{
        					AllowPackageManagers: anthropic.Bool(true),
        				},
        			},
        		},
        	},
        })
        if err != nil {
        	panic(err)
        }

        fmt.Printf("Environment ID: %s\n", environment.ID)
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```java Java
        var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
            .name("quickstart-env")
            .config(BetaCloudConfigParams.builder()
                .networking(BetaLimitedNetworkParams.builder()
                    .allowPackageManagers(true)
                    .build())
                .build())
            .build());

        IO.println("Environment ID: " + environment.id());
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```php PHP
        $environment = $client->beta->environments->create(
            name: 'quickstart-env',
            config: [
                'type' => 'cloud',
                'networking' => ['type' => 'limited', 'allow_package_managers' => true],
            ],
        );

        echo "Environment ID: {$environment->id}\n";
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>

      <CodeGroupItem>
        ```ruby Ruby
        environment = client.beta.environments.create(
          name: "quickstart-env",
          config: {type: "cloud", networking: {type: "limited", allow_package_managers: true}}
        )

        puts "Environment ID: #{environment.id}"
        ```

        Salva anche l’`environment.id` restituito.
      </CodeGroupItem>
    </CodeGroup>

    <Tip>
      Questa guida rapida utilizza un ambiente cloud. Per decidere se eseguire invece gli strumenti sulla tua infrastruttura con una 

      [sandbox self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes)

      , consulta 

      [Scegliere un ambiente per l’agente](https://platform.claude.com/docs/it/managed-agents/choosing-an-environment)

      .
    </Tip>
  </Step>

  <Step title="Avvia una sessione">
    Crea una sessione che faccia riferimento al tuo agente e al tuo ambiente.

    <CodeGroup>
      **Accesso tramite CLI**

      ```bash cURL
      curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
        -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
        -H "anthropic-version: 2026-10-21" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "agent": "'"$AGENT_ID"'",
          "environment_id": "'"$ENVIRONMENT_ID"'",
          "title": "Quickstart session"
        }'
      ```

      **Chiave API**

      ```bash cURL
      curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -H "anthropic-beta: managed-agents-2026-04-01" \
        -H "content-type: application/json" \
        -d '{
          "agent": "'"$AGENT_ID"'",
          "environment_id": "'"$ENVIRONMENT_ID"'",
          "title": "Quickstart session"
        }'
      ```

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

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

      print(f"Session ID: {session.id}")
      ```

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

      console.log(`Session ID: ${session.id}`);
      ```

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

      Console.WriteLine($"Session ID: {session.ID}");
      ```

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

      fmt.Printf("Session ID: %s\n", session.ID)
      ```

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

      IO.println("Session ID: " + session.id());
      ```

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

      echo "Session ID: {$session->id}\n";
      ```

      ```ruby Ruby
      session = client.beta.sessions.create(
        agent: agent.id,
        environment_id: environment.id,
        title: "Quickstart session"
      )

      puts "Session ID: #{session.id}"
      ```
    </CodeGroup>
  </Step>

  <Step title="Invia un messaggio e ricevi la risposta in streaming">
    Apri uno stream, invia un evento utente, quindi elabora gli eventi man mano che arrivano:

    <CodeGroup exclude="shell">
      <CodeGroupItem language="cURL">
        Questo flusso di lavoro richiede più logica di un singolo comando shell. Usa l’[Anthropic SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) per eseguirlo.
      </CodeGroupItem>

      <CodeGroupItem language="CLI">
        Questo flusso di lavoro richiede più logica di un singolo comando shell. Usa l’[Anthropic SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview) per eseguirlo.
      </CodeGroupItem>

      ```python Python
      with client.beta.sessions.events.stream(session.id) as stream:
          # Invia il messaggio dell'utente dopo l'apertura dello stream
          client.beta.sessions.events.send(
              session.id,
              events=[
                  {
                      "type": "user.message",
                      "content": [
                          {
                              "type": "text",
                              "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                          },
                      ],
                  },
              ],
          )

          # Elabora gli eventi di streaming
          for event in stream:
              match event.type:
                  case "agent.message":
                      for block in event.content:
                          if block.type == "text":
                              print(block.text, end="")
                  case "agent.tool_use":
                      print(f"\n[Using tool: {event.name}]")
                  case "session.status_idle":
                      print("\n\nAgent finished.")
                      break
      ```

      ```typescript TypeScript
      const stream = await client.beta.sessions.events.stream(session.id);

      // Invia il messaggio dell'utente dopo l'apertura dello stream
      await client.beta.sessions.events.send(session.id, {
        events: [
          {
            type: "user.message",
            content: [
              {
                type: "text",
                text: "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
              }
            ]
          }
        ]
      });

      // Elabora gli eventi di streaming
      loop: for await (const event of stream) {
        switch (event.type) {
          case "agent.message":
            for (const block of event.content) {
              if (block.type === "text") {
                process.stdout.write(block.text);
              }
            }
            break;
          case "agent.tool_use":
            console.log(`\n[Using tool: ${event.name}]`);
            break;
          case "session.status_idle":
            console.log("\n\nAgent finished.");
            break loop;
        }
      }
      ```

      ```csharp C#
      var stream = client.Beta.Sessions.Events.StreamStreaming(session.ID);

      // Invia il messaggio dell'utente dopo l'apertura dello stream
      await client.Beta.Sessions.Events.Send(session.ID, new()
      {
          Events =
          [
              new BetaManagedAgentsUserMessageEventParams
              {
                  Content =
                  [
                      new BetaManagedAgentsTextBlock
                      {
                          Text = "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                      },
                  ],
              },
          ],
      });

      // Elabora gli eventi in streaming
      await foreach (var streamEvent in stream)
      {
          if (streamEvent.Value is BetaManagedAgentsAgentMessageEvent message)
          {
              foreach (var block in message.Content)
              {
                  if (block.Value is BetaManagedAgentsTextBlock textBlock)
                  {
                      Console.Write(textBlock.Text);
                  }
              }
          }
          else if (streamEvent.Value is BetaManagedAgentsAgentToolUseEvent toolUse)
          {
              Console.WriteLine($"\n[Using tool: {toolUse.Name}]");
          }
          else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent)
          {
              Console.WriteLine("\n\nAgent finished.");
              break;
          }
      }
      ```

      ```go Go
      	stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{})
      	defer stream.Close()

      	// Invia il messaggio dell'utente dopo l'apertura dello stream
      	_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
      		Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
      			OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
      				Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
      					OfText: &anthropic.BetaManagedAgentsTextBlockParam{
      						Text: "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
      					},
      				}},
      			},
      		}},
      	})
      	if err != nil {
      		panic(err)
      	}

      	// Elabora gli eventi in streaming
      loop:
      	for stream.Next() {
      		switch event := stream.Current().AsAny().(type) {
      		case anthropic.BetaManagedAgentsAgentMessageEvent:
      			for _, block := range event.Content {
      				if block.Type == "text" {
      					fmt.Print(block.Text)
      				}
      			}
      		case anthropic.BetaManagedAgentsAgentToolUseEvent:
      			fmt.Printf("\n[Using tool: %s]\n", event.Name)
      		case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
      			fmt.Print("\n\nAgent finished.\n")
      			break loop
      		}
      	}
      	if err := stream.Err(); err != nil {
      		panic(err)
      	}
      ```

      ```java Java
      try (var stream = client.beta().sessions().events().streamStreaming(session.id())) {
          // Invia il messaggio dell'utente dopo l'apertura dello stream
          client.beta().sessions().events().send(session.id(), EventSendParams.builder()
              .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
                  .addTextContent("Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt")
                  .build())
              .build());

          // Elabora gli eventi di streaming
          loop:
          for (var event : stream) {
              switch (event.type().value()) {
                  case AGENT_MESSAGE -> event.asAgentMessage().content().forEach(block -> block.text().ifPresent(textBlock -> IO.print(textBlock.text())));
                  case AGENT_TOOL_USE -> IO.println("\n[Using tool: " + event.asAgentToolUse().name() + "]");
                  case SESSION_STATUS_IDLE -> {
                      IO.println("\n\nAgent finished.");
                      break loop;
                  }
              }
          }
      }
      ```

      ```php PHP
      $stream = $client->beta->sessions->events->streamStream($session->id);

      // Invia il messaggio dell'utente dopo l'apertura dello stream
      $client->beta->sessions->events->send(
          $session->id,
          events: [
              [
                  'type' => 'user.message',
                  'content' => [
                      ['type' => 'text', 'text' => 'Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt'],
                  ],
              ],
          ],
      );

      // Elabora gli eventi di streaming
      foreach ($stream as $event) {
          match (true) {
              $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsAgentMessageEvent => array_walk(
                  $event->content,
                  static fn ($block) => $block instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock ? print($block->text) : null,
              ),
              $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsAgentToolUseEvent => print("\n[Using tool: {$event->name}]\n"),
              $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent => print("\n\nAgent finished.\n"),
              default => null,
          };
          if ($event->type === 'session.status_idle') {
              break;
          }
      }
      ```

      ```ruby Ruby
      stream = client.beta.sessions.events.stream_events(session.id)

      # Invia il messaggio dell'utente dopo l'apertura dello stream
      client.beta.sessions.events.send_(
        session.id,
        events: [{
          type: "user.message",
          content: [{type: "text", text: "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"}]
        }]
      )

      # Elabora gli eventi di streaming
      stream.each do |event|
        case event
        when Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent
          event.content.each { print it.text if it.is_a?(Anthropic::Beta::Sessions::BetaManagedAgentsTextBlock) }
        when Anthropic::Beta::Sessions::BetaManagedAgentsAgentToolUseEvent
          puts "\n[Using tool: #{event.name}]"
        when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
          puts "\n\nAgent finished."
          break
        else
          # ignora gli altri tipi di evento
        end
      end
      ```
    </CodeGroup>

    L’agente scrive uno script Python, lo esegue nella sandbox e verifica che il file di output sia stato creato. Il tuo output sarà simile a questo:

    ```text wrap
    I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
    [Using tool: write]
    [Using tool: bash]
    The script ran successfully. Let me verify the output file.
    [Using tool: bash]
    fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

    Agent finished.
    ```
  </Step>
</Steps>

## Cosa succede

Quando invii un evento utente, Claude Managed Agents:

1. **Predispone una sandbox:** la configurazione del tuo ambiente determina come viene costruita.
2. **Esegue il ciclo dell’agente:** Claude determina quali strumenti utilizzare in base al tuo messaggio.
3. **Esegue gli strumenti:** scritture di file, comandi bash e altre chiamate agli strumenti vengono eseguiti all’interno della sandbox.
4. **Trasmette gli eventi in streaming:** ricevi aggiornamenti in tempo reale mentre l’agente lavora.
5. **Entra in stato di inattività:** l’agente emette un evento `session.status_idle` quando non ha più nulla da fare.

## Crea un’app completa

Ciascuna di queste guide rapide abbina Claude Managed Agents a un popolare framework di chat per creare un’applicazione completa ed eseguibile. In ognuna, il framework visualizza l’interfaccia di chat mentre una sessione gestita esegue il ciclo dell’agente lato server: la sessione conserva la trascrizione, esegue gli strumenti in una sandbox e trasmette in streaming gli eventi che il front end visualizza.

<CardGroup cols={3}>
  <Card title="Chat SDK" icon="github-logo" href="https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/chat-sdk">
    Un analista di ricerca in una chat nel browser creata con Chat SDK di Vercel. Ogni conversazione è una sessione persistente che trasmette in streaming la propria risposta mentre un feed in tempo reale mostra le chiamate agli strumenti. Sostituendo l’adattatore di Chat SDK, lo stesso handler si sposta su Slack, Teams, Discord o WhatsApp.
  </Card>

  <Card title="assistant-ui" icon="github-logo" href="https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/assistant-ui">
    Un analista di fogli di calcolo in una chat creata con le primitive di assistant-ui. Le sessioni costituiscono l’elenco dei thread, un reducer trasforma il registro degli eventi della sessione in messaggi e schede degli strumenti, e ogni comando bash mostra un controllo Consenti/Nega in linea prima di essere eseguito.
  </Card>

  <Card title="CopilotKit (AG-UI)" icon="github-logo" href="https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/copilot-kit-ag-ui">
    Un assistente per la finanza personale in una chat CopilotKit. L’adattatore AG-UI per Claude Managed Agents associa ogni thread di chat a una sessione gestita e trasmette in streaming le risposte token per token, mentre gli strumenti personalizzati visualizzano grafici interattivi in linea nella conversazione.
  </Card>
</CardGroup>

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Definisci il tuo agente" icon="brain" href="https://platform.claude.com/docs/it/managed-agents/agent-setup">
    Crea configurazioni di agenti riutilizzabili e con versioni
  </Card>

  <Card title="Configura gli ambienti" icon="settings" href="https://platform.claude.com/docs/it/managed-agents/environments">
    Personalizza le impostazioni di rete e della sandbox
  </Card>

  <Card title="Strumenti dell’agente" icon="tool" href="https://platform.claude.com/docs/it/managed-agents/tools">
    Abilita strumenti specifici per il tuo agente
  </Card>

  <Card title="Stream di eventi della sessione" icon="lightning" href="https://platform.claude.com/docs/it/managed-agents/events-and-streaming">
    Gestisci gli eventi e guida l’agente durante l’esecuzione
  </Card>

  <Card title="Deployment pianificati" icon="arrows-clockwise" href="https://platform.claude.com/docs/it/managed-agents/scheduled-deployments">
    Esegui il tuo agente secondo una pianificazione cron ricorrente
  </Card>

  <Card title="Guida rapida per wiki della conoscenza" icon="github-logo" href="https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/knowledge-wiki">
    Distilla una volta un corpus di documenti in un wiki della conoscenza, quindi rispondi a domande ricorrenti a partire da esso a una frazione del costo
  </Card>
</CardGroup>
