Agents: das Agent SDK, managed Agents und Scheduling

# Agents: das Agent SDK, managed Agents und Scheduling

Ein Agent ist einfach Claude in einer Loop mit Tools, die läuft, bis eine Aufgabe tatsächlich erledigt ist. Diese eine Idee ist die ganze Lektion. Ein normaler APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Call gibt Claude einen Turn 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 so weiter, bis ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → die Arbeit für abgeschlossen hält oder Sie ihn stoppen.

Die Bausteine kennen Sie schon (Tool Use, MCP, die Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →). In dieser Lektion geht es darum, sie zu etwas zu verdrahten, das autonom läuft, und um das Produktionsthema, das in Tutorials nie vorkommt: wie man einen Agent nach Zeitplan laufen lässt, ohne ihn zu babysitten.

Wann ein Agent besser ist als ein einzelner Call

Greifen Sie zu einem einfachen Messages-APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-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 Agent, wenn die Aufgabe Discovery, Iteration oder Verzweigung erfordert, die Sie nicht vorab skripten kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen. Das Erkennungsmerkmal: Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen die exakte Schrittfolge nicht im Vorfeld aufschreiben, weil die Schritte davon abhängen, was Claude unterwegs findet.

Konkrete Beispiele, in denen sich ein Agent auszahlt:

• „Untersuche, warum unsere Error Rate letzte Nacht in die Höhe geschossen ist“ (Claude muss Logs abfragen, ein Muster bemerken, erneut abfragen, mit einem Deploy korrelieren).
• „Reconcile die Stripe-Charges von gestern gegen unsere Orders-Tabelle und markiere Abweichungen“ (variable Anzahl von 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 einen riesigen if/else-Baum um Modell-Calls herum schreiben, wollen Sie wahrscheinlich einen Agent. Wenn ein einzelner Prompt mit gutem Kontext die Arbeit erledigt, bauen Sie es nicht zu kompliziert.

Das Claude Agent SDK in klaren Worten

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

Der entscheidende Denkwechsel: Mit der rohen Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → schreiben Sie die Loop selbst (Call, auf tool_use prüfen, Tool ausführen, Ergebnis anhängen, erneut aufrufen). Das Agent SDK besitzt diese Loop, damit Sie sich darauf konzentrieren, welche Tools der Agent hat und was getan werden soll.

Drei Dinge, die das SDK von Haus aus mitbringt:

• Die Agent-Loop, inklusive Kontextverwaltung, 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 sowohl in TypeScript als auch in Python. Da es dieselbe Grundlage wie Claude Code nutzt, kann ein damit gebauter Agent Dateien lesen, Kommandos ausführen und Code bearbeiten, mit derselben Kompetenz, die Sie von Claude Code kennen, aber ausgerichtet auf *Ihre* Aufgabe statt auf eine interaktive Terminal-Session.

Managed Agents vs. selbst betreiben

Es gibt zwei Wege, einen Agent zu betreiben, und der Unterschied ist fürs Scheduling relevant.

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

Managed Agents: Anthropic lässt die Agent-Loop auf eigener Infrastruktur laufen. Sie definieren den Agent (Tools, Instructions, Permissions) und Anthropic führt ihn aus, inklusive Orchestrierung, Retries und Skalierung. Die operative Last geben Sie ab.

Die praktische Empfehlung: Prototypen self-hosted, weil die Feedback-Loop schnell ist und Sie alles ausgeben kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen. Wechseln Sie zu Managed Agents, wenn Sie Zuverlässigkeit und Isolation brauchen und keinen Server pflegen wollen. Speziell fürs Scheduling entfernt ein Managed Agent mit einem cron-artigen Trigger fast alle bewegten Teile.

> Eine Anmerkung zu den Begriffen: Ein Agent ist hier eine konfigurierte Loop aus Claude plus Tools. Ein Connector (aus den Claude-Apps und dem Connector-Marketplace) ist eine verpackte Integration, die einen Service über MCP für Claude verfügbar macht. Ein Skill ist eine wiederverwendbare, verpackte Fähigkeit. Agents kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Connectors und Skills als ihre Tools *nutzen*.

Ein konkretes Beispiel: der nightly report Agent

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

Warum ein Agent und kein Script? Weil „schreibe einen kurzen Report“ genau der unscharfe, urteilslastige Schritt ist, den ein Script nicht leisten kann und für den ein einzelner APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Call die Daten nicht zuverlässig *sammeln* kann. Der Agent fragt die Datenbank ab (je nach Befund möglicherweise mehrfach), interpretiert die Zahlen, entscheidet, was hervorzuheben ist, und formatiert die Nachricht.

Hier eine schlanke Python-Skizze mit dem Agent SDK. Der Agent bekommt zwei Tools (ein Tool für Datenbankabfragen und eines zum Posten in Slack) und eine Instruction. Beachten Sie, wie wenig Orchestrierungscode es gibt: Die Loop lebt 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, die auffallen sollten:

• allowed_tools ist Ihr Guardrail. Das SQLSQLSales Qualified Lead: a prospect the sales team has validated as ready for direct outreach and a proposal, having passed clear qualification criteria.Vollständige Definition ansehen →-Tool ist von Konstruktion her read-only; der Agent kann buchstäblich keine Tabelle löschen, weil Sie ihm diese Fähigkeit nie gegeben haben.
• Die Instruction sagt „Query before you conclude.“ Das schiebt den Agent dazu, tatsächlich in die Daten zu schauen statt Zahlen zu halluzinieren, und das ist die wichtigste Gewohnheit für einen Reporting-Agent.
• Die Loop ist unsichtbar. Claude entscheidet, wie viele run_sql-Calls nötig sind. Sehen die Signups seltsam aus, kann ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → tiefer graben, bevor ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → den Report schreibt.

Scheduling: den Agent in einem Takt laufen lassen

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

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

Option 1: OS cron (self-hosted). Läuft der Agent auf einem Server, den Sie kontrollieren, ist einfaches cron völlig in Ordnung. 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 kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen das Log lesen, wenn etwas seltsam aussieht.

Option 2: Eine serverless Scheduled Function. Ein Cloud-Scheduler (eine scheduled Lambda, ein Cloud Run Job, ein GitHub Actions schedule-Trigger) ruft den Agent nach einer cron-Expression auf, ohne dass Sie einen Server am Leben halten. Sie zahlen nur, wenn ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → läuft. Das ist der Sweet Spot für die meisten Nightly Jobs.

Hier die GitHub-Actions-Variante, die ehrlich gesagt am einfachsten ist, wenn Ihr Code schon in einem Repo liegt:

name: nightly-report
on:
  schedule:
    - cron: "0 2 * * *"
  workflow_dispatch: {}   # lässt Sie den Job auch manuell 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 workflow_dispatch-Zeile ist eine kleine, aber wichtige Gewohnheit: Sie gibt Ihnen einen manuellen „run now“-Button, damit Sie testen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, ohne bis 2 Uhr zu warten. Speichern Sie Ihren Key als Repository Secret, nie in der Datei.

Option 3: Managed Agents mit Schedule. Wenn Sie den Agent auf der Managed Infrastructure von Anthropic betreiben, hängen Sie einen Schedule an die Agent-Definition, statt eigenes cron zu verdrahten. Agent-Loop, Retries und Ausführungsumgebung werden für Sie übernommen; Sie liefern Takt und Trigger. Schauen Sie für die exakte Konfiguration in die aktuellen Agent SDK Docs, denn die Managed-Oberfläche entwickelt sich 2025 und 2026 schnell weiter.

Was sich ändert, sobald es unbeaufsichtigt läuft

Ein geplanter Agent ist autonom, und das bringt drei Themen mit, die ein einmaliger Call nie hatte. Planen Sie sie von Tag eins ein.

Idempotenz und Teilfehler. Wenn der Agent in Slack postet und der Run danach 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 Agent selbst Erfolg oder Fehlschlag an einer Stelle signalisieren, die Sie 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 Loop kann in pathologischen Fällen weit 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 günstigste Versicherung ist, die Sie haben. Der nightly Agent bekommt eine read-only Datenbankrolle und einen einzigen Slack-Channel. Nicht mehr. Ein unbeaufsichtigter Agent sollte niemals Permissions halten, die ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → für seine eine Aufgabe nicht zwingend braucht.

Key Takeaways

• Nutzen Sie einen Agent, wenn die Schritte davon abhängen, was Claude entdeckt. Wenn Sie die exakte Sequenz skripten kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, ist ein einzelner Messages-APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Call einfacher und günstiger. Wenn nicht, hat die Loop ihren Platz verdient.
• Lassen Sie das Agent SDK die Loop besitzen. Ihre Aufgabe ist es, Tools zu definieren (oft über MCP), eine klare Instruction 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 scheduled serverless Job oder GitHub Actions schedule für die meisten Fälle, oder ein Schedule direkt am Managed Agent.
• Planen Sie den 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 gewähren, damit der Agent nur seine eine Aufgabe anfassen kann.
• Bauen Sie immer einen manuellen Trigger ein (workflow_dispatch, einen „run now“-Pfad), damit Sie den Agent testen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, ohne auf den Schedule zu warten.