Inizia con Claude Managed Agents

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.

Concetti fondamentali

Prerequisiti

• Un account Claude Console
• Una chiave API

Installa la CLI

brew install anthropics/tap/ant

VERSION=1.39.0
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

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

export PATH="$PATH:$(go env GOPATH)/bin"

Verifica l'installazione:

ant --version

Installa l'SDK

pip install anthropic

Imposta la tua chiave API come variabile d'ambiente:

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

Crea la tua prima sessione

1. 1

   Crea un agente

   Crea un agente che definisce il modello, il "system prompt" (prompt di sistema) e gli strumenti disponibili.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   ant apply coding-assistant.md

   coding-assistant.md

   

   ---
   name: Coding Assistant
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful coding assistant. Write clean, well-documented code.

   ant apply stampa l'ID dell'agente e lo registra in claude-lock.json. Lo userai come riferimento in ogni sessione che crei.

   Il tipo di strumento agent_toolset_20260401 abilita l'intero set di strumenti predefiniti per agenti (bash, operazioni sui file, ricerca web e altro). Consulta Strumenti per l'elenco completo e le opzioni di configurazione di ciascuno strumento.

2. 2

   Crea un ambiente

   Un ambiente definisce la "sandbox" (ambiente isolato) in cui viene eseguito il tuo agente. Questo usa il networking limited con i gestori di pacchetti consentiti, così il codice in esecuzione nella sandbox può raggiungere i registri di pacchetti e gli host di codice pubblici. La ricerca web e il recupero web vengono eseguiti al di fuori della sandbox, e questa guida rapida non ne ha bisogno. Con il networking limited, l'elenco allowed_hosts si applica anche a loro. In questo ambiente non restituiscono pagine né risultati di ricerca, perché non elenca alcun host. Per il tuo agente, elenca in allowed_hosts gli host di cui ha bisogno.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   ant apply environment.yaml

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

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

3. 3

   Avvia una sessione

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   session = client.beta.sessions.create(
       agent=agent.id,
       environment_id=environment.id,
       title="Quickstart session",
   )
   
   print(f"Session ID: {session.id}")

4. 4

   Invia un messaggio e trasmetti la risposta in streaming

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   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

   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 succede

Quando invii un evento utente, Claude Managed Agents:

1. Effettua il provisioning di una sandbox: la configurazione del tuo ambiente determina come viene costruita.
2. Esegue il ciclo dell'agente: Claude determina quali strumenti usare in base al tuo messaggio.
3. Esegue gli strumenti: scritture di file, comandi bash e altre chiamate a strumenti vengono eseguite all'interno della sandbox.
4. Trasmette eventi in streaming: ricevi aggiornamenti in tempo reale mentre l'agente lavora.
5. Diventa inattivo: l'agente emette un evento session.status_idle quando non ha più nulla da fare.

Costruisci un'app completa

Ciascuno di questi quickstart abbina Claude Managed Agents a un popolare framework di chat per realizzare un'applicazione completa ed eseguibile. In ognuno, il framework renderizza 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 renderizza.

Prossimi passi