Agenti gestitiPrimi passi

Inizia con Claude Managed Agents

Crea il tuo primo agente autonomo.

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.

Preferisci una guida interattiva? Esegui /claude-api managed-agents-onboard nell'ultima versione di Claude Code per una configurazione guidata e domande e risposte interattive.

Concetti fondamentali

Concetto	Descrizione
Agent	Il modello, il prompt di sistema, gli strumenti, i server MCP e le skill
Environment	Configurazione che definisce dove vengono eseguite le sessioni: una sandbox cloud gestita da Anthropic, oppure una sandbox self-hosted sulla tua infrastruttura
Session	Un'istanza dell'agente in esecuzione all'interno di un environment, che esegue un'attività specifica e genera output
Events	Messaggi scambiati tra la tua applicazione e l'agente (turni dell'utente, risultati degli strumenti, aggiornamenti di stato)

Prerequisiti

Un account Console di Anthropic
Una chiave API

Installa la CLI

Verifica l'installazione:

ant --version

Installa l'SDK

Imposta la tua chiave API come variabile d'ambiente:

export ANTHROPIC_API_KEY="your-api-key-here"

Crea la tua prima sessione

Tutte le richieste all'API Managed Agents richiedono l'header beta managed-agents-2026-04-01. L'SDK imposta automaticamente l'header beta.

Crea un agente
Crea un agente che definisce il modello, il prompt di sistema e gli strumenti disponibili.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
Il tipo di strumento agent_toolset_20260401 abilita l'intero set di strumenti predefiniti per l'agente (bash, operazioni sui file, ricerca web e altro). Consulta Strumenti per l'elenco completo e le opzioni di configurazione per ciascuno strumento.
Salva l'agent.id restituito. Lo utilizzerai come riferimento in ogni sessione che crei.
Crea un ambiente
Un ambiente definisce la sandbox in cui viene eseguito il tuo agente.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
Salva l'environment.id restituito. Lo utilizzerai come riferimento in ogni sessione che crei.
Per eseguire la sandbox sulla tua infrastruttura invece che su una sandbox cloud, consulta Sandbox self-hosted.

Avvia una sessione

Crea una sessione che fa riferimento al tuo agente e al tuo ambiente.

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

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

Invia un messaggio e ricevi la risposta in streaming

Apri uno stream, invia un evento utente, quindi elabora gli eventi man mano che arrivano:

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:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

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:

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.

Cosa sta succedendo

Quando invii un evento utente, Claude Managed Agents:

Effettua il provisioning di una sandbox: La configurazione del tuo ambiente determina come viene costruita.
Esegue il ciclo dell'agente: Claude determina quali strumenti utilizzare in base al tuo messaggio.
Esegue gli strumenti: Le scritture di file, i comandi bash e le altre chiamate agli strumenti vengono eseguite all'interno della sandbox.
Trasmette eventi in streaming: Ricevi aggiornamenti in tempo reale mentre l'agente lavora.
Passa in stato idle: L'agente emette un evento session.status_idle quando non ha più nulla da fare.

Passaggi successivi

Definisci il tuo agente

Crea configurazioni di agenti riutilizzabili e versionate

Configura gli ambienti

Personalizza le impostazioni di rete e della sandbox

Strumenti dell'agente

Abilita strumenti specifici per il tuo agente

Stream di eventi della sessione

Gestisci gli eventi e guida l'agente durante l'esecuzione

Deployment pianificati

Esegui il tuo agente secondo una pianificazione cron ricorrente

Was this page helpful?

Concetti fondamentali

Concetto	Descrizione
Agent	Il modello, il prompt di sistema, gli strumenti, i server MCP e le skill
Environment	Configurazione che definisce dove vengono eseguite le sessioni: una sandbox cloud gestita da Anthropic, oppure una sandbox self-hosted sulla tua infrastruttura
Session	Un'istanza dell'agente in esecuzione all'interno di un environment, che esegue un'attività specifica e genera output
Events	Messaggi scambiati tra la tua applicazione e l'agente (turni dell'utente, risultati degli strumenti, aggiornamenti di stato)

Crea la tua prima sessione

Tutte le richieste all'API Managed Agents richiedono l'header beta managed-agents-2026-04-01. L'SDK imposta automaticamente l'header beta.

Crea un agente
Crea un agente che definisce il modello, il prompt di sistema e gli strumenti disponibili.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
Il tipo di strumento agent_toolset_20260401 abilita l'intero set di strumenti predefiniti per l'agente (bash, operazioni sui file, ricerca web e altro). Consulta Strumenti per l'elenco completo e le opzioni di configurazione per ciascuno strumento.
Salva l'agent.id restituito. Lo utilizzerai come riferimento in ogni sessione che crei.
Crea un ambiente
Un ambiente definisce la sandbox in cui viene eseguito il tuo agente.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
Salva l'environment.id restituito. Lo utilizzerai come riferimento in ogni sessione che crei.
Per eseguire la sandbox sulla tua infrastruttura invece che su una sandbox cloud, consulta Sandbox self-hosted.

Avvia una sessione

Crea una sessione che fa riferimento al tuo agente e al tuo ambiente.

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

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

Invia un messaggio e ricevi la risposta in streaming

Apri uno stream, invia un evento utente, quindi elabora gli eventi man mano che arrivano:

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:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

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:

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.

Cosa sta succedendo

Quando invii un evento utente, Claude Managed Agents:

Effettua il provisioning di una sandbox: La configurazione del tuo ambiente determina come viene costruita.

Esegue il ciclo dell'agente: Claude determina quali strumenti utilizzare in base al tuo messaggio.

Esegue gli strumenti: Le scritture di file, i comandi bash e le altre chiamate agli strumenti vengono eseguite all'interno della sandbox.

Trasmette eventi in streaming: Ricevi aggiornamenti in tempo reale mentre l'agente lavora.

Passa in stato idle: L'agente emette un evento session.status_idle quando non ha più nulla da fare.

Concetti fondamentali

Prerequisiti

Installa la CLI

Installa l'SDK

Crea la tua prima sessione

Cosa sta succedendo

Passaggi successivi

Concetti fondamentali

Prerequisiti

Installa la CLI

Installa l'SDK

Crea la tua prima sessione

Cosa sta succedendo

Passaggi successivi

Concetti fondamentali

Prerequisiti

Installa la CLI

Installa l'SDK

Crea la tua prima sessione

Cosa sta succedendo

Passaggi successivi

Concetti fondamentali

Prerequisiti

Installa la CLI

Installa l'SDK

Crea la tua prima sessione

Cosa sta succedendo

Passaggi successivi