Claude Agent SDK: So erstellen Sie Agenten (2026)

TL;DR

• Das Claude Agent SDK ist Anthropic's Bibliothek zum Erstellen von AI Agents in Ihrem eigenen Code — dieselbe Agent-Engine, die Claude Code antreibt, bereitgestellt als claude-agent-sdk für Python (3.10+) und @anthropic-ai/claude-agent-sdk für TypeScript.
• Es wurde Ende 2025 von `claude-code-sdk` umbenannt; wenn ein Tutorial ClaudeCodeOptions sagt, ist es veraltet — die Klasse heißt jetzt ClaudeAgentOptions.
• Sie erhalten die vollständige Agent-Schleife kostenlos: Datei-Tools, Bash, Websuche, benutzerdefinierte Tools über @tool, MCP-Server (so binden Sie Jira oder Shopify ein), Subagents, Hooks und Berechtigungen. Sie zahlen nur für Claude API Tokens.
• Es kommuniziert mit der Anthropic Messages API, sodass Sie es mit ANTHROPIC_BASE_URL auf ein Gateway ausrichten können — wir haben es gegen den /v1/messages-Endpoint von Velokey getestet, und es läuft mit einem Schlüssel und Credit Billing.

Alle bauen gerade Agents, und die meisten Leitfäden hören beim Zehn-Zeilen-Quickstart auf. Dieser hier behandelt, was danach passiert: wie man es ohne die häufige Node-Falle installiert, wie man echte Tools wie Jira und Shopify einbindet, was der Betrieb tatsächlich kostet und wie man es über ein Gateway routet. Los geht's.

Was ist das Claude Agent SDK?

Das Claude Agent SDK ist eine Bibliothek, die deiner eigenen Anwendung dieselbe autonome Agentenschleife gibt, die in Claude Code läuft — Dateien lesen und schreiben, Befehle ausführen, das Web durchsuchen und Tools aufrufen, ohne dass du die Tool-Call-Schleife von Hand schreiben musst. Anthropic liefert es für Python und TypeScript aus, und laut der offiziellen Dokumentation ist es der unterstützte Weg, um produktionsreife Agenten auf Claude zu bauen.

Der wichtige Kontext, den die meisten übersehen: Es hieß früher Claude Code SDK. Anthropic hat es Ende 2025 in Claude Agent SDK umbenannt, um zu signalisieren, dass es zum Erstellen *beliebiger* Agenten gedacht ist, nicht nur von Coding-Tools. Das Package, die Imports und eine zentrale Klasse haben sich alle geändert — claude-code-sdk wurde zu claude-agent-sdk, und ClaudeCodeOptions wurde zu ClaudeAgentOptions. Viele Blogposts und Stack Overflow-Antworten verweisen immer noch auf die alten Namen. Wenn dein Import also fehlschlägt, ist das normalerweise der Grund.

Unter der Haube verpackt das SDK die Claude Code CLI als Subprozess. Dein Python- oder TypeScript-Code spricht mit dem SDK; das SDK steuert die gebündelte CLI; die CLI spricht mit Claude. Diese Architektur ist aus zwei Gründen wichtig, auf die wir zurückkommen werden: Die CLI ist ein Node-Binary (du brauchst also Node installiert, selbst für das Python SDK), und die CLI betreibt aggressives Prompt-Caching für ihren System-Prompt (was deine Kostenrechnung verändert).

Wie installiere und verwende ich das Claude Agent SDK?

Installieren Sie das Claude Agent SDK von PyPI (oder npm), legen Sie Ihren API-Schlüssel fest und rufen Sie query() auf — ein funktionsfähiger Agent umfasst etwa zehn Zeilen. Python benötigt 3.10 oder neuer:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

Hier ist der minimale One-Shot-Agent. query() gibt einen asynchronen Iterator von Nachrichten zurück:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

Für alles Interaktive oder Mehrfachdialoge verwenden Sie ClaudeSDKClient und konfigurieren ihn mit ClaudeAgentOptions:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

Zwei Installationsfallen, über die viele stolpern und die nicht im zehnzeiligen Schnellstart enthalten sind:

Was können Sie mit dem Claude Agent SDK erstellen?

Sie können jeden Agenten erstellen, der Dateizugriff, Befehlsausführung oder Tool-Nutzung benötigt — vom Code-Reviewer über einen Triage-Agenten für den Kundensupport bis hin zu einem Operator für Datenpipelines. Das SDK stellt Ihnen fünf Bausteine bereit, und das gesamte Design dreht sich darum, zu steuern, was der Agent tun darf:

Benutzerdefinierte Tools sind der eleganteste Teil. Dekorieren Sie eine Funktion, und der Agent kann sie direkt aufrufen — kein separater Prozess, kein Netzwerk-Hop:

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

Hooks und Berechtigungen machen aus einer Demo etwas, das Sie unbeaufsichtigt laufen lassen würden. Ein PreToolUse-Hook kann einen Bash-Befehl blockieren, der einem gefährlichen Muster entspricht; permission_mode entscheidet, ob der Agent für eine Genehmigung pausiert oder Änderungen automatisch akzeptiert. In der Produktion beginnen die meisten Teams mit einer engen allowed_tools-Liste und erweitern sie, wenn sie dem Agenten mehr vertrauen — das Gegenteil des weit geöffneten Quickstarts.

Der sechste Baustein, und derjenige, zu dem man greift, sobald ein einzelner Agent langsam wird, sind Subagenten. Das SDK kann einen neuen Subagenten mit eigenem Kontext starten, um eine eingegrenzte Teilaufgabe zu bearbeiten, und anschließend das Ergebnis zurückgeben — Claude Code nutzt dies, um über Dateien hinweg aufzufächern. Es ist die integrierte Antwort auf „Kann es an mehreren Dingen parallel arbeiten?“ und „Wie verhindere ich, dass der Hauptkontext voll läuft?“: Delegieren Sie die laute Arbeit (zehn Dateien lesen, eine Testmatrix ausführen) an Subagenten, damit der Hauptagent fokussiert bleibt. Session-Forking ist der verwandte Trick, um eine laufende Unterhaltung zu verzweigen.

Wie integriere ich Jira oder Shopify mit dem Claude Agent SDK?

Du integrierst Jira, Shopify oder ein beliebiges externes System, indem du dessen MCP-Server zu mcp_servers in ClaudeAgentOptions hinzufügst — das SDK enthält keinen Jira-spezifischen Code, es spricht das offene Model Context Protocol, und sowohl Atlassian als auch Shopify liefern MCP-Server aus. Das ist die Antwort auf die am häufigsten gestellten Integrationsfragen („wie verbinde ich Jira/Shopify mit Claude Agent SDK“): Es gibt keinen speziellen Connector, du registrierst einen MCP-Server und erlaubst seine Tools.

Das Muster ist für beide gleich. Richte das SDK auf den MCP-Server aus (einen lokalen Befehl oder eine Remote-URL) und erlaube dann die Tools, die er bereitstellt:

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

Tausche den Server-Block gegen @shopify/mcp-server (mit deinem Shopify-Token) aus, und derselbe Agent kann Bestellungen lesen oder Produkte aktualisieren. Zwei Dinge müssen stimmen: Die Tool-Namen folgen der Konvention mcp__<server>__<tool>, daher müssen deine allowed_tools-Einträge exakt übereinstimmen, und jeder MCP-Server benötigt seine eigenen Zugangsdaten in env. Wenn der Agent sagt, dass ein Tool nicht verfügbar ist, liegt es fast immer an einer Namensabweichung oder einem fehlenden Token, nicht an einem SDK-Bug.

Wenn der Anbieter statt eines lokalen Befehls einen Remote-MCP-Server hostet, registriere ihn per URL statt über command/args — {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}} — und das SDK verbindet sich über das Netzwerk. Lokale (stdio) Server sind für die Entwicklung einfacher und behalten den Token auf deinem Rechner; Remote-Server (URL) ersparen dir jede Installation. In beiden Fällen sind die Regeln für allowed_tools und die Zugangsdaten pro Server gleich.

Wie führe ich das Claude Agent SDK über ein Gateway aus?

Setzen Sie ANTHROPIC_BASE_URL auf das Root Ihres Gateways, und das SDK sendet jede Anfrage dorthin statt an api.anthropic.com — keine Codeänderung nötig. Das SDK berücksichtigt die standardmäßigen Anthropic-Umgebungsvariablen, daher funktioniert jedes Backend, das die Anthropic Messages API (/v1/messages) bereitstellt: ein Unternehmens-Proxy, eine regionale Bridge oder ein vereinheitlichtes Gateway.

Wir haben dies mit [Velokey](https://api.velokey.ai) getestet, das einen Anthropic-kompatiblen /v1/messages-Endpunkt bereitstellt. Eine Live-Anfrage daran gab eine standardmäßige Messages-Antwort zurück (stop_reason: end_turn, Anthropic-förmige Nutzung), was genau dem entspricht, was das SDK erwartet:

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

Warum sollte man einen Agent überhaupt über ein Gateway leiten? Ein Schlüssel statt eines separaten Anthropic-Kontos, einer separaten Stufe und einer separaten Einrichtung für 30-Tage-Aufbewahrung; kreditbasierte Abrechnung, die Sie begrenzen können; und derselbe Schlüssel erreicht [Claude Opus 4.8](/model/claude-opus-4-8), [Claude Sonnet 5](/model/claude-sonnet-5) und andere Modelle, die Sie möglicherweise anderswo verwenden. Wenn Ihr Proxy ein Bearer-Token statt des x-api-key-Headers erwartet, setzen Sie ANTHROPIC_AUTH_TOKEN anstelle von ANTHROPIC_API_KEY. Es ist dieselbe Drop-in-Idee wie das Verweisen eines OpenAI-kompatiblen Tools auf ein Gateway — siehe unseren Qwen CLI-Leitfaden für das OpenAI-Format-Äquivalent.

Wie viel kostet das Claude Agent SDK?

Das SDK selbst ist kostenlos und Open Source — du zahlst für die Claude API-Tokens, die der Agent verbraucht, und Agenten verbrauchen sehr viele davon. Jede Runde sendet die wachsende Unterhaltung erneut, jedes Tool-Ergebnis kommt zurück in den Kontext, und eine einzelne Aufgabe wie "fix this bug" kann zehn-plus Runden laufen. Das ist die Kostenüberraschung: Der Code umfasst zehn Zeilen, aber die Token-Rechnung skaliert damit, wie viel der Agent erkundet.

Drei Hebel halten das im Rahmen, und den größten davon baut das SDK für dich ein:

Diese letzte Zeile ist real, nicht theoretisch: In unserer Testanfrage meldete die Antwort Zehntausende von cache_read_input_tokens, was bedeutet, dass der große System-Prompt aus dem Cache geliefert wurde, zu ungefähr einem Zehntel des Eingabepreises, statt in jeder Runde erneut berechnet zu werden. Das ist der Hauptgrund, warum Agentenkosten nicht so brutal sind, wie die Rundenzahl vermuten lässt. Für die vollständige Token-Rechnung pro Modell siehe unseren Claude API pricing guide; wenn du einen funktionierenden Einzelaufruf an ein Claude-Modell möchtest, bevor du einen Agenten verdrahtest, behandelt how to call Claude with an API key die Grundlagen.

Häufig gestellte Fragen

Was ist das Claude Agent SDK?

Es ist Anthropic's offizielle Bibliothek zum Erstellen von AI-Agenten in Python oder TypeScript und verwendet dieselbe autonome Agentenschleife, die Claude Code antreibt. Sie übernimmt die Tool-Call-Schleife, Dateioperationen, Befehlsausführung und MCP-Integrationen für dich, sodass du das Ziel und die Tools schreibst, nicht die Orchestrierung. Du zahlst nur für Claude API-Tokens.

Ist das Claude Agent SDK dasselbe wie das Claude Code SDK?

Ja — es ist die umbenannte Version. Anthropic hat claude-code-sdk Ende 2025 in claude-agent-sdk umbenannt, und aus ClaudeCodeOptions wurde ClaudeAgentOptions. Die Funktionalität wurde übernommen; nur die Paket- und Klassennamen haben sich geändert. Wenn ein Tutorial die alten Namen importiert, stammt es aus der Zeit vor der Umbenennung und die Importe schlagen mit dem aktuellen Paket fehl.

Wie installiere ich das Claude Agent SDK?

Führe pip install claude-agent-sdk (Python 3.10+) oder npm install @anthropic-ai/claude-agent-sdk für TypeScript aus und setze dann ANTHROPIC_API_KEY. Da das SDK die gebündelte Claude Code CLI als Subprozess steuert, musst du außerdem Node.js installiert haben, selbst für das Python-Paket — ein fehlendes Node ist der häufigste Installationsfehler.

Wie verbinde ich Jira oder Shopify mit einem Claude Agent SDK-Agenten?

Füge den MCP-Server des Anbieters zu mcp_servers in ClaudeAgentOptions hinzu und erlaube seine Tools. Sowohl Atlassian (Jira) als auch Shopify veröffentlichen MCP-Server, daher musst du keinen eigenen Connector schreiben — du registrierst den Server mit seinem API-Token und listest seine Tools (benannt mcp__<server>__<tool>) in allowed_tools auf.

Funktioniert das Claude Agent SDK mit einem Gateway oder Proxy?

Ja. Es berücksichtigt die Umgebungsvariable ANTHROPIC_BASE_URL, sodass es ohne Codeänderung an jedes Backend weiterleitet, das die Anthropic Messages API (/v1/messages) bereitstellt. Wir haben eine Live-Anfrage gegen Velokey's Anthropic-kompatiblen Endpunkt verifiziert. Verwende ANTHROPIC_API_KEY für x-api-key-Proxys oder ANTHROPIC_AUTH_TOKEN für Bearer-Token-Proxys.

Welche Modelle verwendet das Claude Agent SDK?

Es verwendet Claude-Modelle über den Endpunkt, auf den du es ausrichtest — standardmäßig Anthropic's neuesten, und du kannst über die Option model ein bestimmtes Modell festlegen (zum Beispiel claude-sonnet-5 oder claude-opus-4-8). Über ein Gateway kannst du jedes Claude-Modell auswählen, das dieses Gateway bereitstellt, was praktisch ist, um bei routinemäßigen Agentenläufen ein günstigeres Modell zu verwenden.

Ist das Claude Agent SDK kostenlos?

Das SDK ist kostenlos und open-source, aber das Ausführen eines Agenten kostet Claude API-Tokens, und Multi-Turn-Agentenschleifen verbrauchen sie schnell. Kontrolliere die Ausgaben, indem du für Routinearbeiten ein günstigeres Modell wählst, max_turns festlegst und den Tool-Zugriff begrenzt — und verlasse dich auf das integrierte Prompt-Caching, das den wiederholten System-Prompt zu ungefähr einem Zehntel des Eingabepreises bereitstellt.