Claude Managed Agents bouwen met Claude Sonnet 5

Heb je ooit een Claude Code-achtige workflow vanuit een Python-script willen draaien, waarbij het model in een beheerde omgeving kan werken met toegang tot tools, bestanden, skills en instructies?

Claude Managed Agents zijn voor dit soort workflows gemaakt en helpen je agents te bouwen die meerstaps taken in een gecontroleerde omgeving kunnen uitvoeren.

In deze tutorial laat ik je zien hoe je Claude Sonnet 5 gebruikt, een recent model van Anthropic dat is ontworpen voor geavanceerd redeneren, coderen en data-analyse. Het stelt de agent in staat data te inspecteren, tools te gebruiken, code te schrijven en uit te voeren, en gestructureerde output te produceren.

Je maakt een Managed Agent, configureert de omgeving, uploadt een CSV-bestand en geeft de agent toegang tot tools en een XLSX-skill. 

De agent analyseert de data, genereert Python-, JSON- en Excel-bestanden, controleert de resultaten en stelt de voltooide output beschikbaar om te downloaden.

Als je helemaal nieuw bent met Claude, bekijk dan eerst de Claude Code 101-cursus.

Wat zijn Claude Managed Agents?

Claude Managed Agents is Anthropics beheerde framework om Claude als een autonome agent te draaien. 

In plaats van zelf een lus te schrijven om prompts te sturen, tool-calls uit te voeren, resultaten op te slaan en de runtime te beheren, definieer je de agent en laat je Anthropic die infrastructuur afhandelen. 

Het is bedoeld voor langere, meerstaps taken waarbij het model meerdere tools moet gebruiken voordat het klaar is.

Managed Agents zijn opgebouwd rond vier hoofdonderdelen:

• Agent: de herbruikbare configuratie met het model, de systeemprompt, tools, MCP-servers en skills.
• Omgeving: waar de agent draait, in Anthropics cloud-sandbox of in je eigen self-hosted sandbox.
• Sessie: een actieve instantie van de agent die een specifieke taak uitvoert.
• Events: de berichten, tool-calls, resultaten en statusupdates die tijdens de sessie worden uitgewisseld.

1. Vereisten voor je Claude Agent-werkruimte

Installeer voor deze tutorial Python 3.12 of hoger en Jupyter Notebook op je computer. We gebruiken een Jupyter Notebook om de Managed Agent stap voor stap te maken, draaien en inspecteren.

Je hebt ook een Anthropic Console-account nodig. 

Maak een nieuwe API-sleutel in de Console, voeg minstens $5 aan API-tegoed toe en bewaar de sleutel veilig. 

Managed Agents kunnen in één sessie meerdere model- en tool-calls doen en zijn daardoor mogelijk duurder dan een standaard API-request.

Sla de sleutel op als een ANTHROPIC_API_KEY-omgevingsvariabele in plaats van deze direct aan het notebook toe te voegen of te committen naar GitHub.

Voor macOS, Linux of WSL, voer dit uit in je terminal:

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

Voor Windows PowerShell, gebruik:

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

2. De Anthropic Python-SDK instellen

Installeer voordat je een Managed Agent maakt de officiële Anthropic Python-SDK en importeer de modules die voor dit notebook nodig zijn. 

De SDK biedt de Anthropic-client, die je gebruikt om agents, omgevingen, bestanden en sessies te maken. 

%pip install -q --upgrade anthropic

Laad vervolgens je Anthropic API-sleutel uit een omgevingsvariabele. 

De sleutel buiten het notebook houden is veiliger dan hem direct in de code zetten, zeker als je het project wilt delen of naar GitHub wilt pushen.

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

Managed Agents zijn momenteel toegankelijk via Anthropics bèt­a-API. De managed-agents-2026-04-01 bètaflag maakt deze functie mogelijk, hoewel de officiële SDK automatisch de vereiste bètaheader meestuurt voor Managed Agents-verzoeken. 

We houden de flag in het notebook omdat die later nodig is bij het lijsten en downloaden van sessiebestanden. 

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

client = Anthropic(api_key=api_key)

Maak tot slot een dictionary om de ID’s op te slaan van alle resources die tijdens de tutorial worden aangemaakt. 

Dit omvat de agent, omgeving, geüpload bestand en sessie. Door deze ID’s op te slaan, is opruimen aan het einde eenvoudiger, zelfs als een latere stap faalt.

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

De client is nu klaar. 

3. Maak de Managed Agent

Een Managed Agent is de herbruikbare configuratie voor je workflow. 

Bij het aanmaken kies je het Claude-model, schrijf je de systeemprompt die de rol en instructies bepaalt en koppel je de tools en skills die het kan gebruiken. 

Je kunt vervolgens dezelfde agent in meerdere sessies hergebruiken in plaats van de configuratie telkens opnieuw te maken. 

We noemen onze agent Sonnet 5 Data Analyst en gebruiken claude-sonnet-5. 

De systeemprompt zegt dat het zich moet gedragen als een zorgvuldige data-analist: bekijk bestanden die zijn gemount in /workspace, gebruik code-uitvoering voor analyse, houd resultaten beknopt en sla definitieve bestanden op 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"}],
)

De agent_toolset_20260401 geeft de agent toegang tot Anthropics ingebouwde tools in een sessie, terwijl de xlsx-skill taakspecifieke begeleiding biedt voor het maken en analyseren van Excel-werkboeken. 

Anthropic levert ook kant-en-klare skills voor PowerPoint-, Word- en PDF-workflows.

Sla ten slotte de agent-ID op. 

Je gebruikt die later bij het aanmaken van een sessie en hiermee kan de opruimsectie de agent archiveren zodra de tutorial is afgerond.

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

Je zou een output moeten zien zoals:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Configureer de Anthropic Cloud-sandbox

Vervolgens maken we de omgeving waarin de Managed Agent tijdens een sessie draait. 

Een omgeving fungeert als een veilige sandbox en geeft de agent een aparte werkruimte om gemounte bestanden te lezen, code te schrijven en commando’s uit te voeren.

We gebruiken Anthropics cloudomgeving met beperkte netwerktoegang. De agent gebruikt deze sandbox later om het geüploade CSV-bestand met Python te analyseren.

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}")

Na het uitvoeren van de cel, zie je een omgeving-ID zoals:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Data uploaden met de Anthropic Files API

Vervolgens uploaden we de dataset die de agent gaat analyseren. 

Managed Agents gebruiken Anthropics Files API om lokale bestanden te uploaden, die vervolgens in de sessieomgeving kunnen worden gemount.

Voor deze gids gebruiken we de voorbeeld-dataset met 12 rijen, genaamd sales_data.csv. 

Voor we uploaden, controleren we of het bestand bestaat en of het het verwachte aantal datarijen bevat.

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}"

Daarna uploaden we het bestand en slaan we de ID op voor later opruimen.

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

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

Na het uitvoeren van de cel, zie je een output zoals:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Initialiseer een Agent Execution-sessie

Nu maken we een sessie. 

Een sessie verbindt de agent, de omgeving en de resources die nodig zijn voor een specifieke taak. Hier mounten we het geüploade CSV-bestand op /workspace/sales_data.csv, zodat de agent er vanuit de sandbox bij kan.

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}")

Je zou een sessie-ID moeten zien zoals:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Stream de reactie van de agent

Nu sturen we de taak naar de sessie en streamen we de activiteit van de agent terwijl die werkt. 

Een sessie maken bereidt alleen de agent en sandbox voor; de agent begint pas te werken nadat deze een user.message-event ontvangt. 

De eventstream laat ons in realtime de berichten, tool-calls en uiteindelijke sessiestatus van de agent zien. 

De prompt vraagt de agent het gemounte CSV-bestand te analyseren, een Python-script te schrijven en uit te voeren, een JSON-samenvatting te maken en een Excel-rapport op te bouwen. 

We maken ook drie variabelen om de tekst van de agent te verzamelen, de gebruikte tools bij te houden en te bevestigen of de sessie succesvol is afgerond.

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)

Tijdens het draaien zie je tools-events zoals read, bash, write en edit. 

Deze laten zien dat de agent de beschikbare instructies en bestanden bekijkt, het analysescript schrijft, het in de sandbox draait en problemen corrigeert die het vindt.

Een sessie wordt idle wanneer de agent niets meer te doen heeft. In dit voorbeeld geeft session.status_idle aan dat de taak voltooid is, dus stoppen we met luisteren naar de stream. 

Anthropic beheert de uitvoering van de ingebouwde tools binnen de sandbox; je hoeft toolresultaten alleen zelf af te handelen bij gebruik van custom tools. 

8. Haal gegenereerde bestanden en eventgeschiedenis op

Zodra de sessie is voltooid, kunnen we de opgeslagen eventgeschiedenis bekijken en de door de agent gemaakte bestanden downloaden. 

De eventgeschiedenis geeft een volledig overzicht van de sessie, inclusief modelverzoeken, tool-calls, toolresultaten en statuswijzigingen.

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)")

Vervolgens lijsten we de bestanden op die aan de sessie zijn gekoppeld en downloaden we de bestanden die als downloadbaar zijn gemarkeerd. De bestanden worden lokaal opgeslagen in een map 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}")

Tot slot controleren we of alle verwachte outputs succesvol zijn gedownload:

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)}"
)

Het gegenereerde Pythonscript, de JSON-samenvatting en het Excel-rapport staan nu in de lokale map outputs.

9. Analyseer de Python-, JSON- en Excel-outputs

Nadat de agent de taak heeft voltooid, worden de gegenereerde bestanden gedownload naar de lokale map outputs/. 

Deze bestanden laten zien dat de agent meer deed dan alleen tekst teruggeven: hij schreef en voerde code uit, maakte gestructureerde data en produceerde een spreadsheetrapport dat je los kunt beoordelen.

De screenshots hieronder tonen de drie gegenereerde artefacten.

Dit bestand bevat de analysecode die de agent heeft geschreven en uitgevoerd, waardoor de workflow reproduceerbaar en eenvoudig te inspecteren is.

Dit bestand slaat de resultaten op in een gestructureerd formaat dat kan worden gebruikt door dashboards, API’s of andere programma’s.

Dit Excel-bestand toont de maandelijkse berekeningen visueel, met omzet, kosten, winst, marges, totalen en een grafiek.

Voor de 12 rijen in sales_data.csv zijn de geverifieerde resultaten:

• Totale omzet: $32.900
• Totale kosten: $14.750
• Totale winst: $18.150
• Gemiddelde maandelijkse winst: $1.512,50
• Beste maand: december ($2.550 winst)
• Slechtste maand: januari ($400 winst)

Het werkboek is formulegestuurd in plaats van alleen op hardcoded waarden te vertrouwen. 

Tijdens de run las de agent de gekoppelde XLSX-skillinstructies, maakte het werkboek, herberekende het met LibreOffice, controleerde de formules en loste een probleem met een circulaire verwijzing op voordat de taak werd afgerond.

10. Ruim Managed Agent API-resources op

Managed Agent-resources blijven beschikbaar totdat je ze verwijdert, dus het is belangrijk om ze op te ruimen zodra de taak klaar is. 

Actieve resources, vooral draaiende sessies en omgevingen, kunnen kosten blijven veroorzaken als je ze laat draaien.

Een sessie moet idle zijn voordat deze kan worden verwijderd. 

In deze laatste stap verwijderen we de sessie, het geüploade bestand en de omgeving en archiveren we de agent. 

Elke opruimactie is verpakt in een helperfunctie zodat één mislukte verwijdering de overige resources niet tegenhoudt om toch te worden verwijderd.

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.")

Je ziet een output zoals:

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

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

Het complete project, inclusief het notebook, het voorbeeld-CSV-bestand en installatie-instructies, is beschikbaar op GitHub. 

Je kunt de repository clonen en het notebook opnieuw draaien om de resultaten uit deze gids te reproduceren.

Tot slot

Ik vond Claude Managed Agents eenvoudig op te zetten en mee te werken. 

Je maakt een agent, geeft ’m de tools, skills en sandbox die hij nodig heeft en draait hem vervolgens via een sessie. 

Vanaf daar kan hij een complete workflow afhandelen, zoals code schrijven, bestanden maken, zijn eigen output controleren en de eindresultaten teruggeven.

Ik probeerde eerst een Modal Sandbox te gebruiken omdat ik een flexibelere externe omgeving wilde. 

Maar de setup werd te complex voor de scope van deze gids, dus koos ik ervoor om dit project te richten op Anthropics beheerde cloud-sandbox.

Het grootste nadeel voor mij waren de kosten. Ik heb dit voorbeeld twee keer gedraaid met een kleine CSV met slechts 12 rijen en dat kostte ongeveer $0,25. 

Het dashboard toonde de kosten onder het model, maar ik kon geen gedetailleerde uitsplitsing vinden. Voor een eenvoudige reken- en spreadsheettaak voelt dat prijzig vergeleken met goedkopere open-sourceopties.

Al met al laat dit project de volledige Managed Agent-workflow zien: een agent maken, een CSV-bestand uploaden, Python draaien in een beheerde sandbox, JSON- en Excel-rapporten genereren, de output verifiëren, de bestanden downloaden en de resources achteraf opruimen.