Claude · Agents: das Agent SDK, managed Agents und Scheduling

Ein Agent ist einfach Claude in einer Schleife mit Tools, der läuft, bis eine Aufgabe tatsächlich erledigt ist. Diese eine Idee ist die ganze Lektion. Ein normaler APIAPIApplication Programming Interface: eine standardisierte Schnittstelle, über die Anwendungen kommunizieren und Daten austauschen, ohne die interne Funktionsweise der jeweils anderen zu kennen.Vollständige Definition ansehen →-Call gibt Claude einen Zug zum Antworten; ein Agent gibt Claude die Möglichkeit, ein Tool aufzurufen, das Ergebnis zu sehen, über den nächsten Schritt zu entscheiden, ein weiteres Tool aufzurufen und weiterzumachen, bis er die Arbeit für abgeschlossen hält oder Sie ihn stoppen.

Die Bausteine kennen Sie bereits (Tool Use, MCPMCPEin offener Standard, mit dem KI-Assistenten einheitlich und kontrolliert an die Werkzeuge und Daten des Unternehmens angebunden werden, statt jede Integration einzeln zu bauen.Vollständige Definition ansehen →, die Messages API). In dieser Lektion geht es darum, sie zu etwas zu verdrahten, das autonom läuft, und um das Produktionsthema, das in Tutorials niemand erwähnt: wie Sie einen Agenten nach Zeitplan laufen lassen, ohne ihn zu babysitten.

Wann ein Agent besser ist als ein einzelner Call

Greifen Sie zu einem einfachen Messages-API-Call, wenn die Aufgabe one-shot und in sich abgeschlossen ist: diesen Text zusammenfassen, dieses Ticket klassifizieren, diese E-Mail entwerfen. Ein Input, ein Output, fertig.

Greifen Sie zu einem Agenten, wenn die Aufgabe Discovery, Iteration oder Verzweigung erfordert, die Sie nicht im Voraus skripten kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →önnen. Das Erkennungsmerkmal: Sie können die genaue Abfolge der Schritte nicht vorab aufschreiben, weil die Schritte davon abhängen, was Claude unterwegs findet.

Konkrete Beispiele, in denen sich ein Agent auszahlt:

• „Untersuche, warum unsere Fehlerrate letzte Nacht hochgeschossen ist“ (Claude muss Logs abfragen, ein Muster bemerken, erneut abfragen, mit einem Deploy korrelieren).
• „Gleiche die gestrigen Stripe-Charges mit unserer Orders-Tabelle ab und markiere Abweichungen“ (variable Anzahl an Lookups, abhängig von den Daten).
• „Review diesen PR, führe die Tests aus und behebe alles, was fehlschlägt“ (die Fixes hängen davon ab, welche Tests fehlschlagen).

Wenn Sie feststellen, dass Sie einen riesigen if/else-Baum um Modellaufrufe herum schreiben, wollen Sie vermutlich einen Agenten. Wenn ein einzelner Prompt mit gutem Kontext die Aufgabe erledigt, überkonstruieren Sie es nicht.

Das Claude Agent SDK, einfach erklärt

Das Claude Agent SDK ist das offizielle Toolkit, um Agents auf derselben Harness zu bauen, die auch Claude Code antreibt. Es übernimmt die Schleife für Sie: es verwaltet die Konversation, stellt Claude die Tools bereit, führt die von Claude angeforderten Tool-Calls aus, spielt die Ergebnisse zurück und wiederholt das bis zur Fertigstellung.

Der entscheidende Denkwechsel: Mit der reinen Messages API schreiben Sie die Schleife selbst (Call, auf tool_use prüfen, Tool ausführen, Ergebnis anhängen, erneut aufrufen). Das Agent SDK besitzt diese Schleife, damit Sie sich auf die Tools des Agenten und das gewünschte Ergebnis konzentrieren.

Drei Dinge, die das SDK out of the box mitbringt:

• Die Agent-Schleife, inklusive Verwaltung des Kontexts, während die Konversation wächst.
• Tools, inklusive Built-ins wie Dateioperationen und Shell-Kommandos, plus alles, was Sie über MCP bereitstellen (Model Context Protocol, der offene Standard, um Claude mit externen Systemen und Daten zu verbinden).
• Permissions und Guardrails, damit Sie entscheiden, was der Agent anfassen darf.

Es gibt es in TypeScript und Python. Da es sich eine Grundlage mit Claude Code teilt, kann ein damit gebauter Agent Dateien lesen, Kommandos ausführen und Code editieren, mit derselben Kompetenz, die Sie aus Claude Code kennen, nur gerichtet auf *Ihre* Aufgabe statt auf eine interaktive Terminal-Session.

Managed Agents vs. Eigenbetrieb

Es gibt zwei Wege, einen Agenten zu betreiben, und der Unterschied ist für das Scheduling relevant.

Self-hosted: Sie betreiben das Agent SDK im eigenen Prozess, auf der eigenen Maschine, im eigenen Container oder in einer Serverless Function. Ihnen gehören die Runtime, die Secrets und der Zeitplan. Maximale Kontrolle, mehr Ops-Aufwand.

Managed Agents: Anthropic betreibt die Agent-Schleife auf der eigenen Infrastruktur. Sie definieren den Agenten (Tools, Instruktionen und Permissions) und Anthropic führt ihn aus, inklusive Orchestrierung, Retries und Skalierung. Sie geben die operative Last ab.

Die praktische Empfehlung: Prototypen self-hosted, weil der Feedback Loop schnell ist und Sie alles ausgeben können. Wechseln Sie zu Managed Agents, wenn Sie Zuverlässigkeit und Isolation brauchen und lieber keinen Server pflegen wollen. Speziell fürs Scheduling gilt: ein Managed Agent in Kombination mit einem cron-artigen Trigger entfernt fast alle beweglichen Teile.

Eine Anmerkung zu den Begriffen: Ein Agent ist hier eine konfigurierte Claude-plus-Tools-Schleife. Ein Connector (aus den Claude-Apps und dem Connector-Marketplace) ist eine paketierte Integration, die einen Dienst über MCP für Claude bereitstellt. Ein Skill ist eine wiederverwendbare, paketierte Fähigkeit. Agents können Connectors und Skills als ihre Tools *nutzen*.

Ein konkretes Beispiel: der Nightly-Report-Agent

Bauen wir den kanonischen Fall: einen Agenten, der jede Nacht läuft, die Zahlen von gestern zieht, einen kurzen Report schreibt und ihn in Slack postet.

Warum ein Agent und kein Skript? Weil „einen kurzen Report schreiben“ genau der unscharfe, urteilslastige Schritt ist, den ein Skript nicht leisten kann und für den ein einzelner API-Call die Daten nicht zuverlässig *sammeln* kann. Der Agent fragt die Datenbank ab (möglicherweise mehrfach, je nachdem, was er sieht), interpretiert die Zahlen, entscheidet, was hervorhebenswert ist, und formatiert die Nachricht.

Hier eine saubere Python-Skizze mit dem Agent SDK. Der Agent bekommt zwei Tools (ein Tool für Datenbankabfragen und eines fürs Posten in Slack) und eine Instruktion. Beachten Sie, wie wenig Orchestrierungscode nötig ist: Die Schleife steckt in query.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, tool, create_sdk_mcp_server

@tool("run_sql", "Run a read-only SQL query against the analytics DB", {"sql": str})
async def run_sql(args):
    rows = await analytics_db.fetch(args["sql"])
    return {"content": [{"type": "text", "text": str(rows)}]}

@tool("post_to_slack", "Post a message to the #metrics channel", {"text": str})
async def post_to_slack(args):
    await slack.post(channel="#metrics", text=args["text"])
    return {"content": [{"type": "text", "text": "posted"}]}

tools = create_sdk_mcp_server(name="report-tools", tools=[run_sql, post_to_slack])

PROMPT = """Pull yesterday's signups, revenue, and active users from the
analytics DB. Compare each to the prior day. Write a 5-line report that
leads with anything unusual, then post it to Slack."""

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"report": tools},
        allowed_tools=["mcp__report__run_sql", "mcp__report__post_to_slack"],
        system_prompt="You are a careful analytics assistant. Query before you conclude.",
    )
    async for message in query(prompt=PROMPT, options=options):
        print(message)

asyncio.run(main())

Ein paar Dinge sind erwähnenswert:

• allowed_tools ist Ihr GuardrailGuardrailRegeln und Kontrollen, die ein KI-System in sicheren, rechtskonformen und markengerechten Grenzen halten und unerwünschte Ausgaben blockieren.Vollständige Definition ansehen →. Das SQLSQLSales Qualified Lead: ein Prospect, den das Sales-Team als bereit für direkte Ansprache und ein Angebot validiert hat, weil er klare Qualifizierungskriterien erfüllt.Vollständige Definition ansehen →-Tool ist per Konstruktion read-only; der Agent kann buchstäblich keine Tabelle droppen, weil Sie ihm diese Fähigkeit nie gegeben haben.
• Die Instruktion sagt „Query before you conclude.“ Das bringt den Agenten dazu, tatsächlich in die Daten zu schauen, statt Zahlen zu halluzinieren, die wichtigste Gewohnheit für einen Reporting-Agenten.
• Die Schleife ist unsichtbar. Claude entscheidet, wie viele run_sql-Calls nötig sind. Wenn die Signups seltsam aussehen, kann ererDas Verhältnis von Interaktionen (Likes, Kommentare, Shares) zur Reichweite eines Inhalts. Zeigt, wie stark die Zielgruppe reagiert, gemessen an der Zahl der Personen, die den Inhalt gesehen haben.Vollständige Definition ansehen → tiefer graben, bevor er den Report schreibt.

Scheduling: den Agenten im Takt laufen lassen

Ein Agent, den Sie von Hand auslösen, ist eine Demo. Ein Agent, der jede Nacht um 2 Uhr läuft, während Sie schlafen, ist ein Produkt. Scheduling ist der Unterschied.

Hier steckt keine Magie, und das ist eine gute Nachricht: Ein Agent-Run ist einfach ein Prozess, den Sie aufrufen können. Wählen Sie den Trigger-Mechanismus, der dazu passt, wo der Agent lebt.

Option 1: OS-cron (self-hosted). Wenn der Agent auf einem Server läuft, den Sie kontrollieren, reicht einfaches cron. Eine Zeile in Ihrer crontab:

0 2 * * * cd /opt/nightly-report && /usr/bin/python3 agent.py >> /var/log/report.log 2>&1

Das führt `agent.py` täglich um 02:00 aus und hängt die Ausgabe an ein Log an. Einfach, robust, und Sie können das Log lesen, wenn etwas komisch aussieht.

Option 2: Eine serverless Scheduled Function. Ein Cloud-Scheduler (eine geplante Lambda, ein Cloud-Run-Job, ein GitHub-Actions-schedule-Trigger) ruft den Agenten nach einer cron-Expression auf, ohne dass Sie einen Server am Leben halten. Sie zahlen nur, wenn er läuft. Das ist der Sweet Spot für die meisten Nightly Jobs.

Hier die GitHub-Actions-Variante, die ehrlich gesagt die einfachste ist, wenn Ihr Code ohnehin in einem Repo liegt:

name: nightly-report
on:
  schedule:
    - cron: "0 2 * * *"
  workflow_dispatch: {}   # erlaubt auch manuelles Auslösen
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install claude-agent-sdk
      - run: python agent.py
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Die Zeile workflow_dispatch ist eine kleine, aber wichtige Gewohnheit: Sie gibt Ihnen einen manuellen „run now“-Button, damit Sie testen können, ohne bis 2 Uhr zu warten. Speichern Sie Ihren Key als Repository Secret, niemals in der Datei.

Option 3: Managed Agents mit Zeitplan. Wenn Sie den Agenten auf Anthropics Managed Infrastructure betreiben, hängen Sie einen Zeitplan an die Agent-Definition, statt eigenes cron zu verdrahten. Agent-Schleife, Retries und Ausführungsumgebung werden für Sie übernommen; Sie liefern Takt und Trigger. Prüfen Sie die aktuellen Agent SDK Docs für die genaue Konfiguration, da sich die Managed-Oberfläche 2025 und 2026 schnell weiterentwickelt.

Was sich ändert, sobald der Agent unbeaufsichtigt läuft

Ein geplanter Agent ist autonom, und das wirft drei Fragen auf, die ein einzelner Call nie hatte. Planen Sie das ab Tag eins ein.

Idempotenz und Teilfehler. Wenn der Agent in Slack postet, der Run danach aber abstürzt, postet der Run von morgen dann doppelt? Bei einem Report ist das harmlos, aber bei allem, was Daten schreibt, machen Sie Tool-Aktionen retry-sicher oder prüfen Sie vorher, ob die Arbeit schon erledigt wurde.

Observability. Sie schauen nicht zu. Loggen Sie jeden Tool-Call und das Endergebnis, und lassen Sie den Agenten selbst Erfolg oder Misserfolg dort signalisieren, wo Sie es sehen (ein Slack-Thread, eine Status-Zeile). Wenn der Nightly Report ausbleibt, sollte diese Abwesenheit laut sein.

Kosten und Runaway Loops. Ein Agent in einer Schleife kann in pathologischen Fällen deutlich mehr Tool-Calls machen als erwartet. Setzen Sie ein Turn- oder Budget-Limit, damit ein verwirrter Agent stoppt, statt eine Stunde zu laufen. Das Agent SDK erlaubt dieses Cap; nutzen Sie es.

Least Privilege. Das ist eine Wiederholung wert, weil es die billigste Versicherung ist, die Sie haben. Der Nightly Agent bekommt eine read-only Datenbankrolle und einen einzigen Slack-Channel. Nicht mehr. Ein unbeaufsichtigter Agent sollte nie Rechte halten, die er für seinen einen Job nicht zwingend braucht.

Key Takeaways

• Nutzen Sie einen Agenten, wenn die Schritte davon abhängen, was Claude entdeckt. Wenn Sie die exakte Abfolge skripten können, ist ein einzelner Messages-API-Call einfacher und günstiger. Wenn nicht, verdient sich die Schleife ihren Platz.
• Lassen Sie das Agent SDK die Schleife besitzen. Ihr Job ist, Tools zu definieren (oft über MCP), eine klare Instruktion zu schreiben und Permissions zu setzen. Prototypen self-hosted, dann zu Managed Agents wechseln, wenn Anthropic die Runtime übernehmen soll.
• Scheduling ist nur ein Trigger auf einem normalen Prozess. OS-cron für einen eigenen Server, ein geplanter Serverless Job oder GitHub Actions schedule für die meisten Fälle, oder ein Zeitplan direkt am Managed Agent.
• Planen Sie unbeaufsichtigten Betrieb explizit ein: Schreibaktionen idempotent machen, jeden Tool-Call loggen, damit Fehler laut sind, Turns cappen, um Runaway Loops zu verhindern, und Least Privilege vergeben, damit der Agent nur seinen einen Job anfassen kann.
• Bauen Sie immer einen manuellen Trigger ein (workflow_dispatch, ein „run now“-Pfad), damit Sie den Agenten testen können, ohne auf den Zeitplan zu warten.