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.
Claude Code
Lascia che Claude Code configuri il tuo agente per te
/claude-api managed-agents-onboardConcetti 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
Crea un account Claude Console
Registrati per un account Claude Console, oppure accedi a quello che hai già.
Scegli come autenticarti
L’accesso tramite la CLI è consigliato per lo sviluppo locale.
CLIChiave API
Installa la CLI
brew install anthropics/tap/antPer gli ambienti Linux, scarica direttamente il binario della release.
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 antPuoi trovare tutte le release nella pagina delle release su GitHub.
Puoi anche installare la CLI dal codice sorgente con
go install, che richiede Go 1.26.10 o successivo.go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latestgo installposiziona il binario in$(go env GOPATH)/bin. Aggiungi quella directory al tuoPATHse non è già presente:export PATH="$PATH:$(go env GOPATH)/bin"Accedi
ant auth loginUna volta completato l’accesso, gli SDK e la CLI rileveranno automaticamente le tue credenziali.
Crea una chiave API
Crea una chiave API nella Claude Console.
Imposta la variabile d’ambiente
Gli SDK e la CLI leggono la tua chiave da
ANTHROPIC_API_KEY:export ANTHROPIC_API_KEY="your-api-key-here"
Per eseguire gli esempi della CLI, installa la CLI:
brew install anthropics/tap/antPer gli ambienti Linux, scarica direttamente il binario della release.
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 antPuoi trovare tutte le release nella pagina delle release su GitHub.
Puoi anche installare la CLI dal codice sorgente con go install, che richiede Go 1.26.10 o successivo.
go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latestgo install posiziona il binario in $(go env GOPATH)/bin. Aggiungi quella directory al tuo PATH se non è già presente:
export PATH="$PATH:$(go env GOPATH)/bin"Installa l’SDK
pip install anthropicCrea la tua prima sessione
Crea un agente
Crea un agente che definisca il modello, il “system prompt” (prompt di sistema) e gli strumenti disponibili.
CLIant apply coding-assistant.mdcoding-assistant.md--- 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.ant applystampa l’ID dell’agente e lo registra inclaude-lock.json. Lo utilizzerai in ogni sessione che crei.Il tipo di strumento
agent_toolset_20260401abilita 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. Consulta Strumenti per l’elenco completo e le opzioni di configurazione per ciascuno strumento.Crea un ambiente
Un ambiente definisce la “sandbox” (ambiente isolato) in cui viene eseguito il tuo agente. Questo utilizza una rete
limitedcon i gestori di pacchetti consentiti, così il codice eseguito nella sandbox può raggiungere i registri di pacchetti e gli host di codice pubblici. Con la retelimited, l’elencoallowed_hostssi 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.CLIant apply environment.yamlenvironment.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: trueant applyregistra anche l’ID dell’ambiente inclaude-lock.json. Per creare l’agente e l’ambiente con un solo comando, passa entrambi i file:ant apply coding-assistant.md environment.yaml.Avvia una sessione
Crea una sessione che faccia riferimento al tuo agente e al tuo ambiente.
Pythonsession = 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:
Pythonwith 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.") breakL’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:
- Predispone 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: scritture di file, comandi bash e altre chiamate agli strumenti vengono eseguiti all’interno della sandbox.
- Trasmette gli eventi in streaming: ricevi aggiornamenti in tempo reale mentre l’agente lavora.
- Entra in stato di inattività: l’agente emette un evento
session.status_idlequando 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.
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.
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.
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.
Prossimi passi
Crea configurazioni di agenti riutilizzabili e con versioni
Personalizza le impostazioni di rete e della sandbox
Abilita strumenti specifici per il tuo agente
Gestisci gli eventi e guida l’agente durante l’esecuzione
Esegui il tuo agente secondo una pianificazione cron ricorrente
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
Questa pagina ti è stata utile?