Come creare Claude Managed Agents con Claude Sonnet 5

Hai mai desiderato eseguire un workflow in stile Claude Code da uno script Python, in cui il modello possa lavorare in un ambiente gestito con accesso a strumenti, file, skill e istruzioni?

I Claude Managed Agents sono pensati proprio per questo tipo di workflow, e ti aiutano a creare agenti in grado di svolgere attività multi-step in un ambiente controllato.

In questo tutorial ti mostrerò come usare Claude Sonnet 5, un modello recente di Anthropic pensato per task avanzati di ragionamento, coding e analisi dei dati. È ciò che consente all’agente di ispezionare i dati, usare strumenti, scrivere ed eseguire codice e produrre output strutturati.

Creerai un Managed Agent, configurerai il suo ambiente, caricherai un file CSV e darai all’agente accesso a strumenti e a una skill per XLSX. 

L’agente analizzerà i dati, genererà file Python, JSON ed Excel, verificherà i risultati e renderà disponibili gli output finali per il download.

Se sei completamente nuovo a Claude, ti consiglio di dare prima un’occhiata al corso Claude Code 101.

Cosa sono i Claude Managed Agents?

I Claude Managed Agents sono il framework gestito di Anthropic per eseguire Claude come agente autonomo. 

Invece di scrivere tu stesso un loop per inviare prompt, eseguire chiamate agli strumenti, salvare i risultati e gestire il runtime, definisci l’agente e lasci che Anthropic gestisca quell’infrastruttura. 

È pensato per task più lunghi e multi-step in cui il modello potrebbe dover usare diversi strumenti prima di completare il lavoro.

I Managed Agents si basano su quattro parti principali:

• Agent: la configurazione riutilizzabile che contiene il modello, il system prompt, gli strumenti, i server MCP e le skill.
• Environment: dove l’agente viene eseguito, nel cloud sandbox di Anthropic o in un tuo sandbox self-hosted.
• Session: un’istanza in esecuzione dell’agente che svolge un task specifico.
• Events: i messaggi, le chiamate agli strumenti, i risultati e gli aggiornamenti di stato scambiati durante l’esecuzione della sessione.

1. Prerequisiti per il tuo workspace dell’agente Claude

Per seguire questo tutorial, installa Python 3.12 o successivo e Jupyter Notebook sul tuo computer. Useremo un Jupyter Notebook per creare, eseguire e ispezionare il Managed Agent passo dopo passo.

Ti servirà anche un account dell’Anthropic Console. 

Crea una nuova API key nella Console, aggiungi almeno 5 $ di crediti API e conserva la chiave in modo sicuro. 

I Managed Agents possono effettuare diverse chiamate a modello e strumenti in un’unica sessione, quindi potrebbero costare più di una richiesta API standard.

Archivia la chiave come variabile d’ambiente ANTHROPIC_API_KEY invece di aggiungerla direttamente al notebook o farne il commit su GitHub.

Su macOS, Linux o WSL, esegui questo nel terminale:

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

Per Windows PowerShell, usa:

$env:ANTHROPIC_API_KEY="your-api-key-here"

2. Configura l’SDK Python di Anthropic

Prima di creare un Managed Agent, installa l’SDK Python ufficiale di Anthropic e importa i moduli necessari per questo notebook. 

L’SDK fornisce il client Anthropic, che userai per creare agenti, ambienti, file e sessioni. 

%pip install -q --upgrade anthropic

Poi carica la tua API key di Anthropic da una variabile d’ambiente. 

Tenere la chiave fuori dal notebook è più sicuro che inserirla direttamente nel codice, soprattutto se prevedi di condividere il progetto o pubblicarlo su GitHub.

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

I Managed Agents sono attualmente accessibili tramite l’API beta di Anthropic. Il flag beta managed-agents-2026-04-01 abilita questa funzione, anche se l’SDK ufficiale invia automaticamente l’header beta richiesto per le richieste dei Managed Agents. 

Manteniamo il flag nel notebook perché servirà in seguito per elencare e scaricare i file della sessione. 

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

Infine, crea un dizionario per archiviare gli ID di ogni risorsa creata durante il tutorial. 

Questo include l’agente, l’ambiente, il file caricato e la sessione. Salvare questi ID semplifica la pulizia finale, anche se un passaggio successivo dovesse fallire.

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

Il client è ora pronto. 

3. Crea il Managed Agent

Un Managed Agent è la configurazione riutilizzabile per il tuo workflow. 

Quando lo crei, scegli il modello di Claude, scrivi il system prompt che ne definisce il ruolo e le istruzioni, e alleghi gli strumenti e le skill che può usare. 

Poi puoi riutilizzare lo stesso agente in più sessioni, invece di ricreare la configurazione ogni volta. 

Chiameremo il nostro agente Sonnet 5 Data Analyst e useremo claude-sonnet-5. 

Il system prompt gli dice di comportarsi come un’analista dei dati scrupolosa: ispezionare i file montati in /workspace, usare l’esecuzione di codice per l’analisi, mantenere i risultati concisi e salvare i file finali in /mnt/session/outputs.

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

L’agent_toolset_20260401 dà all’agente accesso agli strumenti integrati di Anthropic in una sessione, mentre la skill xlsx fornisce indicazioni specifiche per creare e analizzare workbook Excel. 

Anthropic offre anche skill predefinite per workflow con PowerPoint, Word e PDF.

Infine, salva l’ID dell’agente. 

Lo userai quando creerai una sessione più avanti, e consentirà anche alla sezione di pulizia di archiviare l’agente una volta completato il tutorial.

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

Dovresti vedere un output simile a:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Configura l’Anthropic Cloud Sandbox

Ora creeremo l’ambiente in cui il Managed Agent verrà eseguito durante una sessione. 

Un ambiente funge da sandbox sicura, dando all’agente uno spazio di lavoro separato per leggere i file montati, scrivere codice ed eseguire comandi.

Useremo l’ambiente cloud di Anthropic con rete limitata. L’agente userà questo sandbox più avanti per analizzare con Python il file CSV caricato.

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

Dopo aver eseguito la cella, dovresti vedere un ID ambiente simile a:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Carica i dati con l’Anthropic Files API

Ora caricheremo il dataset che l’agente analizzerà. 

I Managed Agents usano l’Anthropic Files API per caricare file locali, che possono poi essere montati all’interno dell’ambiente di sessione.

Per questa guida usiamo l’esempio di dataset da 12 righe chiamato sales_data.csv. 

Prima di caricarlo, verifichiamo che il file esista e confermiamo che contenga il numero previsto di righe di dati.

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

Quindi carichiamo il file e ne archiviamo l’ID per la pulizia finale.

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

Dopo aver eseguito la cella, dovresti vedere un output simile a:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Inizializza una sessione di esecuzione dell’agente

Ora creeremo una sessione. 

Una sessione collega l’agente, l’ambiente e le risorse necessarie per un task specifico. Qui montiamo il file CSV caricato in /workspace/sales_data.csv, così che l’agente possa accedervi dal sandbox.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

Dovresti vedere un ID di sessione simile a:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Effettua lo streaming della risposta dell’agente

Ora invieremo il task alla sessione ed effettueremo lo streaming dell’attività dell’agente mentre lavora. 

Creare una sessione prepara solo l’agente e il sandbox; l’agente inizia a lavorare dopo che riceve un evento user.message. 

Lo stream di eventi ci consente di vedere in tempo reale i messaggi dell’agente, le chiamate agli strumenti e lo stato finale della sessione. 

Il prompt dice all’agente di analizzare il file CSV montato, scrivere ed eseguire uno script Python, creare un riepilogo JSON e costruire un report Excel. 

Creiamo anche tre variabili per raccogliere il testo dell’agente, registrare gli strumenti usati e confermare se la sessione termina correttamente.

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

Durante l’esecuzione, dovresti vedere eventi di strumenti come read, bash, write ed edit. 

Questi mostrano che l’agente sta ispezionando le istruzioni e i file disponibili, scrivendo lo script di analisi, eseguendolo nel sandbox e correggendo gli eventuali problemi riscontrati.

Una sessione diventa idle quando l’agente non ha altro lavoro da fare. In questo esempio, session.status_idle indica che il task è completo, quindi smettiamo di ascoltare lo stream. 

Anthropic gestisce l’esecuzione dei suoi strumenti integrati all’interno del sandbox; devi occuparti dei risultati degli strumenti solo quando usi tool personalizzati. 

8. Recupera i file generati e la cronologia degli eventi

Una volta completata la sessione, possiamo ispezionare la cronologia degli eventi salvata e scaricare i file creati dall’agente. 

La cronologia degli eventi fornisce un registro completo della sessione, incluse le richieste al modello, le chiamate agli strumenti, i risultati degli strumenti e i cambiamenti di stato.

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

Successivamente, elenchiamo i file collegati alla sessione e scarichiamo quelli contrassegnati come scaricabili. I file vengono salvati localmente in una cartella outputs.

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

Infine, verifichiamo che tutti gli output previsti siano stati scaricati correttamente:

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

Lo script Python generato, il riepilogo JSON e il report Excel sono ora disponibili nella cartella locale outputs.

9. Analizza gli output Python, JSON ed Excel

Dopo che l’agente ha completato il task, i file generati vengono scaricati nella directory locale outputs/. 

Questi file mostrano che l’agente ha fatto più che restituire una risposta testuale: ha scritto ed eseguito codice, creato dati strutturati e prodotto un report in foglio di calcolo che può essere revisionato in autonomia.

Gli screenshot qui sotto mostrano i tre artefatti generati.

Questo file contiene il codice di analisi che l’agente ha scritto ed eseguito, rendendo il workflow riproducibile e facile da ispezionare.

Questo file archivia i risultati in un formato strutturato che può essere usato da dashboard, API o altri programmi.

Questo file Excel presenta visivamente i calcoli mensili, con ricavi, costi, profitto, margini, totali e un grafico.

Per le 12 righe in sales_data.csv, i risultati verificati sono:

• Ricavi totali: 32.900 $
• Costi totali: 14.750 $
• Profitto totale: 18.150 $
• Profitto medio mensile: 1.512,50 $
• Mese migliore: dicembre (2.550 $ di profitto)
• Mese peggiore: gennaio (400 $ di profitto)

Il workbook è basato su formule, invece di affidarsi solo a valori hardcoded. 

Durante l’esecuzione, l’agente ha letto le istruzioni della skill XLSX allegata, ha creato il workbook, lo ha ricalcolato con LibreOffice, ha controllato le formule e ha corretto un problema di riferimento circolare prima di completare il task.

10. Pulisci le risorse dell’API Managed Agent

Le risorse dei Managed Agent restano disponibili finché non le rimuovi, quindi è importante pulirle una volta completato il task. 

Le risorse attive, specialmente sessioni e ambienti in esecuzione, possono continuare a generare costi se lasciate attive.

Una sessione deve essere idle prima di poter essere eliminata. 

In questo ultimo passaggio, eliminiamo la sessione, il file caricato e l’ambiente, quindi archiviamo l’agente. 

Ogni azione di pulizia è racchiusa in una funzione helper, così che un’eliminazione non riuscita non impedisca di rimuovere le altre risorse.

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

Dovresti vedere un output simile a:

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

Il progetto completo, incluso il notebook, il file CSV di esempio e le istruzioni di setup, è disponibile su GitHub. 

Puoi clonare il repository e rieseguire il notebook per ricreare i risultati di questa guida.

Considerazioni finali

Ho trovato i Claude Managed Agents facili da configurare e utilizzare. 

Crei un agente, gli fornisci gli strumenti, le skill e il sandbox di cui ha bisogno, poi lo esegui tramite una sessione. 

Da lì, può gestire un workflow completo, come scrivere codice, creare file, verificare i propri output e restituire i risultati finali.

Inizialmente ho provato a usare un Modal Sandbox perché volevo un ambiente esterno più flessibile. 

Tuttavia, la configurazione è diventata troppo complessa per la portata di questa guida, quindi ho deciso di mantenere questo progetto focalizzato sul cloud sandbox gestito di Anthropic.

Lo svantaggio principale per me è stato il costo. Ho eseguito questo esempio due volte usando un piccolo file CSV di sole 12 righe, e il costo è stato di circa 0,25 $. 

La dashboard ha mostrato l’addebito sotto il modello, ma non sono riuscito a trovare un dettaglio preciso. Per un task semplice di calcolo e foglio di calcolo, sembra costoso rispetto a opzioni open-source più economiche.

In generale, questo progetto mostra l’intero workflow di un Managed Agent: creare un agente, caricare un file CSV, eseguire Python in un sandbox gestito, generare report JSON ed Excel, verificare gli output, scaricare i file e pulire le risorse al termine.