Claude Managed Agents mit Claude Sonnet 5 erstellen: So geht’s

Wolltest du schon einmal einen Claude-Code-ähnlichen Workflow direkt aus einem Python-Skript starten, bei dem das Modell in einer verwalteten Umgebung mit Zugriff auf Tools, Dateien, Skills und Anweisungen arbeitet?

Genau dafür sind Claude Managed Agents gedacht: Sie helfen dir, Agenten zu bauen, die mehrstufige Aufgaben in einer kontrollierten Umgebung zuverlässig ausführen.

In diesem Tutorial zeige ich dir, wie du Claude Sonnet 5 nutzt, ein aktuelles Modell von Anthropic für anspruchsvolle Aufgaben in den Bereichen Reasoning, Coding und Datenanalyse. Es treibt die Fähigkeit des Agenten an, Daten zu prüfen, Tools zu verwenden, Code zu schreiben und auszuführen sowie strukturierte Ergebnisse zu erzeugen.

Du erstellst einen Managed Agent, richtest seine Umgebung ein, lädst eine CSV-Datei hoch und gibst dem Agenten Zugriff auf Tools und eine XLSX-Skill. 

Der Agent analysiert die Daten, generiert Python-, JSON- und Excel-Dateien, prüft die Ergebnisse und stellt die fertigen Outputs zum Herunterladen bereit.

Wenn du ganz neu bei Claude bist, empfehle ich dir zuerst den Kurs Claude Code 101.

Was sind Claude Managed Agents?

Claude Managed Agents ist Anthropics verwaltetes Framework, um Claude als autonomen Agenten auszuführen. 

Anstatt selbst eine Schleife zu schreiben, die Prompts sendet, Tool-Aufrufe ausführt, Ergebnisse speichert und die Laufzeit verwaltet, definierst du den Agenten und überlässt Anthropic diese Infrastruktur. 

Es ist für längere, mehrstufige Aufgaben gedacht, bei denen das Modell mehrere Tools nutzen muss, bevor die Arbeit abgeschlossen ist.

Managed Agents bestehen aus vier Hauptkomponenten:

• Agent: die wiederverwendbare Konfiguration mit Modell, Systemprompt, Tools, MCP-Servern und Skills.
• Umgebung: der Ausführungsort des Agenten, entweder in Anthropics Cloud-Sandbox oder in deiner eigenen Self-Hosted-Sandbox.
• Session: eine laufende Instanz des Agenten für eine konkrete Aufgabe.
• Events: Nachrichten, Tool-Aufrufe, Ergebnisse und Statusupdates, die während der Session ausgetauscht werden.

1. Voraussetzungen für deinen Claude-Agenten‑Workspace

Installiere für dieses Tutorial Python 3.12 oder neuer und Jupyter Notebook auf deinem Rechner. Wir verwenden ein Jupyter Notebook, um den Managed Agent Schritt für Schritt zu erstellen, auszuführen und zu prüfen.

Außerdem brauchst du ein Konto in der Anthropic Console. 

Erstelle in der Console einen neuen API-Schlüssel, lade mindestens 5 US‑$ an API‑Guthaben auf und bewahre den Schlüssel sicher auf. 

Managed Agents können in einer einzigen Session mehrere Modell- und Tool-Aufrufe tätigen und sind daher teurer als eine Standard-API-Anfrage.

Speichere den Schlüssel als ANTHROPIC_API_KEY Umgebungsvariable, statt ihn direkt ins Notebook zu schreiben oder zu GitHub zu committen.

Unter macOS, Linux oder WSL führst du Folgendes im Terminal aus:

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

Unter Windows PowerShell verwendest du:

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

2. Anthropic Python SDK einrichten

Bevor wir einen Managed Agent erstellen, installieren wir das offizielle Anthropic Python SDK und importieren die für dieses Notebook benötigten Module. 

Das SDK stellt den Anthropic Client bereit, mit dem du Agenten, Umgebungen, Dateien und Sessions erstellst. 

%pip install -q --upgrade anthropic

Als Nächstes lädst du deinen Anthropic API-Schlüssel aus einer Umgebungsvariable. 

Es ist sicherer, den Schlüssel außerhalb des Notebooks zu halten, besonders wenn du das Projekt teilen oder nach GitHub pushen möchtest.

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 werden derzeit über Anthropics Beta-API genutzt. Das managed-agents-2026-04-01 Beta-Flag aktiviert diese Funktion, wobei das offizielle SDK die erforderlichen Beta-Header für Anfragen an Managed Agents automatisch setzt. 

Wir behalten das Flag im Notebook, weil es später beim Auflisten und Herunterladen von Session-Dateien benötigt wird. 

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

client = Anthropic(api_key=api_key)

Zum Schluss erstellen wir ein Dictionary, das die IDs aller im Tutorial angelegten Ressourcen speichert. 

Dazu zählen Agent, Umgebung, hochgeladene Datei und Session. Das Speichern der IDs erleichtert das Aufräumen am Ende, selbst wenn später ein Schritt fehlschlägt.

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

Der Client ist jetzt startklar. 

3. Den Managed Agent erstellen

Ein Managed Agent ist die wiederverwendbare Konfiguration für deinen Workflow. 

Bei der Erstellung wählst du das Claude-Modell, schreibst den Systemprompt mit Rolle und Anweisungen und hängst die Tools und Skills an, die er nutzen darf. 

Diesen Agenten kannst du dann in mehreren Sessions wiederverwenden, statt die Konfiguration jedes Mal neu aufzusetzen. 

Wir nennen unseren Agenten Sonnet 5 Data Analyst und verwenden claude-sonnet-5. 

Der Systemprompt weist ihn an, sich wie eine sorgfältige Datenanalystin zu verhalten: Dateien im Verzeichnis /workspace zu prüfen, für Analysen die Codeausführung zu nutzen, Ergebnisse prägnant und numerisch zu halten und finale Dateien in /mnt/session/outputs zu speichern.

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

Das agent_toolset_20260401 gibt dem Agenten Zugriff auf Anthropics integrierte Tools innerhalb einer Session, während die xlsx Skill aufgabenspezifische Hilfestellung für das Erstellen und Analysieren von Excel-Arbeitsmappen liefert. 

Anthropic stellt außerdem vorgefertigte Skills für PowerPoint-, Word- und PDF-Workflows bereit.

Zum Schluss speicherst du die Agent-ID. 

Du brauchst sie später zum Erstellen einer Session; außerdem ermöglicht sie, den Agenten im Aufräumteil am Ende zu archivieren.

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

Die Ausgabe sollte in etwa so aussehen:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Die Anthropic Cloud‑Sandbox konfigurieren

Als Nächstes erstellen wir die Umgebung, in der der Managed Agent während einer Session läuft. 

Eine Umgebung fungiert als sichere Sandbox und bietet dem Agenten einen separaten Workspace, um eingehängte Dateien zu lesen, Code zu schreiben und Befehle auszuführen.

Wir verwenden Anthropics Cloud-Umgebung mit eingeschränktem Netzwerkzugang. Der Agent nutzt diese Sandbox später, um die hochgeladene CSV-Datei mit Python zu analysieren.

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

Nach dem Ausführen solltest du eine Environment-ID ähnlich dieser sehen:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Daten mit der Anthropic Files API hochladen

Nun laden wir den Datensatz hoch, den der Agent analysieren soll. 

Managed Agents verwenden Anthropics Files API, um lokale Dateien hochzuladen, die anschließend in der Session-Umgebung eingehängt werden können.

Für dieses Beispiel nutzen wir den 12‑zeiligen Beispieldatensatz sales_data.csv. 

Vor dem Upload prüfen wir, ob die Datei existiert, und bestätigen, dass sie die erwartete Anzahl an Datenzeilen enthält.

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

Dann laden wir die Datei hoch und speichern ihre ID fürs spätere Aufräumen.

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

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

Die Ausgabe sollte in etwa so aussehen:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Eine Agenten-Session initialisieren

Jetzt erstellen wir eine Session. 

Eine Session verbindet Agent, Umgebung und die Ressourcen, die er für eine konkrete Aufgabe braucht. Hier hängen wir die hochgeladene CSV-Datei unter /workspace/sales_data.csv ein, damit der Agent in der Sandbox darauf zugreifen kann.

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

Du solltest eine Session-ID ähnlich dieser sehen:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Die Antwort des Agenten streamen

Jetzt senden wir die Aufgabe an die Session und streamen die Aktivitäten des Agenten in Echtzeit. 

Das Erstellen einer Session bereitet Agent und Sandbox nur vor; der Agent startet erst, nachdem er ein user.message Event erhalten hat. 

Der Event-Stream zeigt uns Nachrichten, Tool-Aufrufe und den finalen Session-Status in Echtzeit. 

Der Prompt weist den Agenten an, die eingehängte CSV zu analysieren, ein Python-Skript zu schreiben und auszuführen, eine JSON-Zusammenfassung zu erstellen und einen Excel-Bericht zu bauen. 

Wir legen außerdem drei Variablen an, um den Text des Agenten zu sammeln, die verwendeten Tools aufzuzeichnen und zu bestätigen, ob die Session erfolgreich beendet wurde.

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)

Während der Ausführung siehst du Events wie read, bash, write und edit. 

Daran erkennst du, dass der Agent Anweisungen und Dateien prüft, das Analyseskript schreibt, es in der Sandbox ausführt und gefundene Probleme korrigiert.

Eine Session wird „idle“, wenn der Agent keine weiteren Aufgaben hat. In diesem Beispiel zeigt session.status_idle den Abschluss an – wir beenden daher das Streaming. 

Anthropic übernimmt die Ausführung seiner integrierten Tools in der Sandbox; nur bei Custom-Tools musst du Tool-Ergebnisse selbst verarbeiten. 

8. Generierte Dateien und Event-Historie abrufen

Nach Abschluss der Session können wir die gespeicherte Event-Historie einsehen und die vom Agenten erzeugten Dateien herunterladen. 

Die Event-Historie liefert einen vollständigen Verlauf der Session, inklusive Modellanfragen, Tool-Aufrufen, Tool-Ergebnissen und Statuswechseln.

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

Als Nächstes listen wir die zur Session gehörenden Dateien auf und laden alle herunter, die als downloadbar markiert sind. Die Dateien werden lokal im Ordner outputs gespeichert.

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

Zum Schluss prüfen wir, ob alle erwarteten Outputs erfolgreich heruntergeladen wurden:

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

Das generierte Python-Skript, die JSON-Zusammenfassung und der Excel-Bericht liegen nun lokal im Ordner outputs.

9. Python-, JSON- und Excel-Outputs analysieren

Nachdem der Agent die Aufgabe abgeschlossen hat, werden die generierten Dateien in das lokale Verzeichnis outputs/ heruntergeladen. 

Diese Dateien zeigen, dass der Agent mehr getan hat als nur Text zurückzugeben: Er hat Code geschrieben und ausgeführt, strukturierte Daten erzeugt und einen Spreadsheet-Bericht erstellt, der unabhängig überprüft werden kann.

Die folgenden Screenshots zeigen die drei erzeugten Artefakte.

Diese Datei enthält den Analysecode, den der Agent geschrieben und ausgeführt hat – dadurch ist der Workflow reproduzierbar und leicht zu prüfen.

Diese Datei speichert die Ergebnisse in einem strukturierten Format, das von Dashboards, APIs oder anderen Programmen genutzt werden kann.

Diese Excel-Datei stellt die monatlichen Berechnungen visuell dar – mit Umsatz, Kosten, Gewinn, Margen, Summen und einem Diagramm.

Für die 12 Zeilen in sales_data.csv sind die verifizierten Ergebnisse:

• Gesamtumsatz: 32.900 US‑$
• Gesamtkosten: 14.750 US‑$
• Gesamtgewinn: 18.150 US‑$
• Durchschnittlicher Monatsgewinn: 1.512,50 US‑$
• Bester Monat: Dezember (2.550 US‑$ Gewinn)
• Schlechtester Monat: Januar (400 US‑$ Gewinn)

Die Arbeitsmappe ist formelbasiert und verlässt sich nicht nur auf hart codierte Werte. 

Während der Ausführung hat der Agent die Anweisungen der XLSX‑Skill gelesen, die Arbeitsmappe erstellt, sie mit LibreOffice neu berechnet, die Formeln geprüft und vor Abschluss eine zirkuläre Referenz behoben.

10. Managed-Agent-API-Ressourcen aufräumen

Ressourcen von Managed Agents bleiben erhalten, bis du sie entfernst. Daher ist es wichtig, sie nach Abschluss aufzuräumen. 

Aktive Ressourcen – insbesondere laufende Sessions und Umgebungen – können weiter Kosten verursachen, wenn sie nicht beendet werden.

Eine Session muss „idle“ sein, bevor sie gelöscht werden kann. 

Im letzten Schritt löschen wir die Session, die hochgeladene Datei und die Umgebung und archivieren anschließend den Agenten. 

Jede Aufräumaktion ist in eine Hilfsfunktion gekapselt, damit ein fehlgeschlagenes Löschen die übrigen Schritte nicht blockiert.

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

Die Ausgabe sollte in etwa so aussehen:

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

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

Das vollständige Projekt inklusive Notebook, Beispiel-CSV und Setup-Anleitung ist auf GitHub verfügbar. 

Du kannst das Repository klonen und das Notebook erneut ausführen, um die Ergebnisse dieses Guides nachzustellen.

Abschließende Gedanken

Ich fand Claude Managed Agents leicht einzurichten und zu nutzen. 

Du erstellst einen Agenten, gibst ihm die Tools, Skills und die Sandbox, die er braucht, und führst ihn dann in einer Session aus. 

Von dort aus kann er ganze Workflows übernehmen – Code schreiben, Dateien erzeugen, seine Outputs prüfen und die finalen Ergebnisse zurückgeben.

Zunächst wollte ich eine Modal Sandbox nutzen, weil ich eine flexiblere externe Umgebung bevorzugte. 

Die Einrichtung wurde jedoch zu komplex für den Umfang dieses Guides, daher habe ich das Projekt auf Anthropics verwaltete Cloud-Sandbox fokussiert.

Der Hauptnachteil für mich waren die Kosten. Ich habe dieses Beispiel zweimal mit einer kleinen CSV-Datei mit nur 12 Zeilen ausgeführt und es kostete rund 0,25 US‑$. 

Im Dashboard erschien die Belastung unter dem Modell, aber ich fand keine detaillierte Aufschlüsselung. Für eine einfache Rechen- und Spreadsheet-Aufgabe wirkt das teuer im Vergleich zu günstigeren Open-Source-Optionen.

Insgesamt zeigt dieses Projekt den kompletten Managed-Agent-Workflow: Agent erstellen, CSV-Datei hochladen, Python in einer verwalteten Sandbox ausführen, JSON- und Excel-Berichte generieren, Outputs verifizieren, die Dateien herunterladen und anschließend die Ressourcen aufräumen.