Claude Agent SDK (ehemals Claude Code SDK): Python- und TypeScript-Leitfaden

Claude Agent SDK (ehemals Claude Code SDK): Python- und TypeScript-Leitfaden

Das Claude Code SDK, das in Anthropics Agent-SDK-Release in Claude Agent SDK umbenannt wurde, ist eine Python- und TypeScript-Bibliothek zum Ausführen autonomer Coding-Agents in Ihrer Anwendung. Es übernimmt Dateilesevorgänge, Befehle, Codebearbeitungen, Tool-Aufrufe und mehrstufige Iterationen – ohne eine manuell erstellte Tool-Schleife. Mit dem Anthropic-kompatiblen Endpunkt von Novita AI kann dasselbe SDK auch unterstützte Open-Weight-Modelle ausführen und bietet Teams einen Weg zu Modellauswahl und Kostenkontrolle über das Standard-Anthropic-Backend hinaus. Zum Vergleich von Abo und API siehe Claude-API-Preis vs. Abo-Pläne.

Dieser Leitfaden behandelt alles, was Entwickler für den Einstieg benötigen: Installation, die zentrale query()-API, integrierte Tools, Hooks, Sessions, Subagents, MCP-Integration und die Verwendung der LLM-API von Novita AI als Modell-Backend.

Die wichtigsten Punkte

  • Das Claude Code SDK heißt jetzt Claude Agent SDK (claude-agent-sdk für Python, @anthropic-ai/claude-agent-sdk für TypeScript).
  • Eine einzige query()-Funktion ersetzt die manuelle Tool-Ausführungsschleife, die Sie mit dem Anthropic Client SDK benötigen würden.
  • Integrierte Tools decken Dateilesen, Bearbeitung, Bash-Ausführung, Websuche und mehr ab – ohne Implementierungsaufwand.
  • Sessions ermöglichen Agents, Arbeiten über mehrere Aufrufe hinweg mit vollständigem Kontext wiederaufzunehmen.
  • Mit Hooks können Sie Tool-Aufrufe an bestimmten Lebenszykluspunkten validieren, protokollieren oder blockieren.
  • Der Anthropic-kompatible Endpunkt von Novita AI (https://api.novita.ai/anthropic) ermöglicht die Nutzung hochwertiger Open-Weight-Modelle mit demselben SDK-Code.

Was ist das Claude Code SDK?

Das Claude Code SDK ist eine programmatische Schnittstelle zu den Agent-Fähigkeiten von Claude Code. Es stellt dieselben Tools, Reasoning-Loop und Kontextverwaltung bereit, die auch die Claude Code CLI interaktiv nutzt – jedoch als Bibliothek, die Sie importieren und aus Ihrem eigenen Code aufrufen. Für projektbezogene Regeln und Umfang siehe Claude-Code-Regeln und CLAUDE.md.

Anthropic hat es ab der 4.6-Generation in Claude Agent SDK umbenannt, aber der ursprüngliche Suchbegriff „claude code sdk“ beschreibt weiterhin treffend, was es ist: die SDK-Schicht, die auf Claude Code aufsetzt und es Ihnen ermöglicht, Agent-Aufgaben in Software zu automatisieren.

Wofür es gut ist:

  • Automatisierte Code-Reviews, Refactoring oder Testgenerierung in CI/CD
  • Agents, die Dateien lesen und ändern, Skripte ausführen oder in Ihrem Namen im Web suchen
  • Multi-Agent-Pipelines, in denen ein Koordinator Teilaufgaben an spezialisierte Worker delegiert
  • Jeder Workflow, bei dem Claude autonome, mehrstufige Aktionen ausführen soll, statt nur auf einen Prompt zu antworten

Wofür es nicht gedacht ist: Wenn Sie direkte Kontrolle über jede Nachricht, strukturierte Ausgaben aus einem einzelnen Aufruf oder Streaming-Antworten für eine Chat-Oberfläche benötigen, ist das Anthropic Client SDK besser geeignet.

Claude Code SDK vs. Anthropic Client SDK: Wann verwendet man was?

Beide SDKs basieren auf Claude, lösen aber unterschiedliche Probleme.

Claude Agent SDK Anthropic Client SDK
Tool-Ausführung Wird von Claude autonom übernommen Sie implementieren die Tool-Schleife
Schnittstelle query() gibt einen asynchronen Iterator zurück client.messages.create() gibt ein Antwortobjekt zurück
Integrierte Tools Read, Write, Edit, Bash, Grep, Glob, WebSearch und mehr Keine – Sie definieren und führen alle Tools selbst aus
Sessions Integriert – mit einer Session-ID fortsetzbar Manuell – Chatverlauf selbst verwalten
Am besten geeignet für Agentic-Pipelines, CI/CD, Dateioperationen Chat-Apps, strukturierte Ausgaben, feingranulare Kontrolle

Wenn Sie möchten, dass Claude selbst herausfindet, welche Dateien gelesen und bearbeitet werden sollen: Agent SDK. Wenn Sie möchten, dass Claude auf einen bestimmten Prompt antwortet und einen Wert zurückgibt, den Sie weiterverarbeiten: Client SDK.

Claude Agent SDK installieren

Python (erfordert Python 3.10+):

pip install claude-agent-sdk

TypeScript / Node.js:

npm install @anthropic-ai/claude-agent-sdk

Das TypeScript-Paket bündelt eine native Claude-Code-Binärdatei für Ihre Plattform als optionale Abhängigkeit. Sie müssen Claude Code nicht separat installieren.

Um Ihre Python-Version vor der Installation zu überprüfen:

python3 --version  # macOS/Linux
py --version       # Windows

Wenn pip den Fehler No matching distribution found for claude-agent-sdk meldet, ist Ihre Python-Interpreter-Version älter als 3.10.

Schritt 1: Authentifizierung konfigurieren

Setzen Sie Ihren Anthropic-API-Schlüssel als Umgebungsvariable:

export ANTHROPIC_API_KEY=your-api-key

Das SDK unterstützt auch Amazon Bedrock, Google Vertex AI und Azure AI Foundry für Teams, die über Cloud-Anbieter routen:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# plus standard AWS credentials

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT and gcloud credentials

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# plus Azure credentials

Schritt 2: Ihre erste Agent-Abfrage ausführen

Die gesamte SDK-Oberfläche ist um eine einzige Funktion herum aufgebaut: query(). Sie akzeptiert einen Prompt und Optionen und gibt einen asynchronen Iterator von Nachrichtenereignissen zurück.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List all Python files in this directory",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List all Python files in this directory",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

Der Iterator liefert verschiedene Nachrichtentypen. Die beiden nützlichsten:

  • ResultMessage (oder Nachrichten mit einem result-Feld) – die endgültige Antwort des Agents
  • SystemMessage mit subtype === "init" – enthält die session_id für die spätere Fortsetzung

Schritt 3: Berechtigungen mit allowedTools steuern

Das SDK enthält vorimplementierte Tools. Sie legen fest, welche der Agent verwenden darf; Claude übernimmt die Ausführung.

Tool Funktion
Read Liest jede Datei im Arbeitsverzeichnis
Write Erstellt neue Dateien
Edit Nimmt gezielte Änderungen an vorhandenen Dateien vor
Bash Führt Shell-Befehle, Skripte und Git-Operationen aus
Glob Findet Dateien anhand von Mustern (**/*.ts, src/**/*.py)
Grep Durchsucht Dateiinhalte mit regulären Ausdrücken
WebSearch Durchsucht das Web nach aktuellen Informationen
WebFetch Ruft Webseiteninhalte ab und parst sie
Monitor Überwacht ein Hintergrundskript und reagiert auf Ausgabezeilen
AskUserQuestion Stellt dem Benutzer mitten in der Aufgabe klärende Fragen
Agent Ruft einen definierten Subagenten auf

Die Kombination aus Bash + Read + Edit reicht für die meisten automatisierten Code-Aufgaben aus. Fügen Sie WebSearch oder WebFetch hinzu, wenn der Agent externe Daten benötigt.

allowed_tools (Python) / allowedTools (TypeScript) genehmigt bestimmte Tools ohne Rückfrage vorab. Die Einschränkung des Tool-Sets begrenzt auch, was der Agent unbeabsichtigt tun kann – eine nützliche Schutzmaßnahme für automatisierte Pipelines.

Code-Review-Agent mit Nur-Lesen-Zugriff:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Review this codebase for security issues and code smell",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Vollständiger Edit-Agent (genehmigt Dateischreibvorgänge vorab):

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" genehmigt Dateibearbeitungen automatisch ohne interaktive Rückfrage – erforderlich für den Betrieb in CI.

Schritt 4: Hooks zur Lebenszyklussteuerung verwenden

Mit Hooks können Sie an definierten Punkten der Agent-Ausführung eigenen Code ausführen. Sie können Aktionen protokollieren, Eingaben validieren, gefährliche Operationen blockieren oder externen Zustand aktualisieren.

Verfügbare Hook-Ereignisse: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest

Dieses Beispiel schreibt jedes Mal ein Audit-Log, wenn der Agent eine Datei bearbeitet oder erstellt:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactor auth.py to use dataclasses",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())
import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactor auth.ts to use interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Ein PreToolUse-Hook, der { block: true } zurückgibt, verhindert den Tool-Aufruf vollständig – nützlich, um in automatisierten Kontexten Richtlinien wie „niemals Dateien löschen“ durchzusetzen.

Schritt 5: Arbeit mit Sessions fortsetzen

Sessions bewahren den vollständigen Kontext des Agents – welche Dateien er gelesen hat, was er herausgefunden hat, den Gesprächsverlauf – über mehrere query()-Aufrufe hinweg. So können Sie eine lange Aufgabe in Schritte aufteilen oder unterbrochene Arbeit fortsetzen.

Um eine Session fortzusetzen, erfassen Sie die session_id aus dem SystemMessage-Init-Ereignis und übergeben sie an resume:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # First query: read and analyze the codebase
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Second query: continue with full context from the first
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

Der zweite Prompt verwendet „those dependencies“ – eine Referenz, die nur Sinn ergibt, weil die Session den Kontext des ersten Aufrufs enthält. Ohne resume hätte Claude keine Ahnung, worauf Sie sich beziehen.

Schritt 6: Aufgaben mit Subagents delegieren

Subagents sind spezialisierte Agents, die Ihr Haupt-Agent über das Agent-Tool aufrufen kann. Der Haupt-Agent koordiniert; Subagents erledigen fokussierte Arbeit. Die Ergebnisse fließen zurück in den Hauptkontext.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Fügen Sie "Agent" zu allowed_tools hinzu, um Subagent-Aufrufe vorab zu genehmigen. Nachrichten von einem Subagent enthalten ein parent_tool_use_id-Feld, damit Sie nachvollziehen können, welche Ausgabe von welchem Subagent stammt.

Schritt 7: Externe Systeme über MCP anbinden

Das Model Context Protocol (MCP) ermöglicht es, dem Agent externe Fähigkeiten hinzuzufügen – Datenbanken, Browser, interne APIs – ohne eigene Tools zu schreiben. Der Agent behandelt MCP-Tools wie integrierte Tools.

Dieses Beispiel fügt Browser-Automatisierung über den Playwright-MCP-Server hinzu:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open https://example.com and describe the page structure",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Die mcp_servers-Option akzeptiert jeden Server, der der MCP-Spezifikation folgt. Das Community-MCP-Registry unter github.com/modelcontextprotocol/servers listet Hunderte von Integrationen, darunter Postgres, Puppeteer, Slack, GitHub und Dateisystemvarianten.

Novita AI als Modell-Backend verwenden

Das Claude Agent SDK verwendet standardmäßig die API von Anthropic, aber Sie können es auf den Anthropic-kompatiblen Endpunkt von Novita AI ausrichten, um kostengünstige Open-Weight-Modelle zu nutzen – ohne Codeänderungen.

Der Endpunkt von Novita AI spiegelt das Anthropic-API-Format:

https://api.novita.ai/anthropic

Setzen Sie diese beiden Umgebungsvariablen, bevor Sie Ihren Agent ausführen:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"

Ihre vorhandenen query()-Aufrufe funktionieren ohne Änderungen. Das SDK liest ANTHROPIC_BASE_URL automatisch.

Novita AI hostet eine Reihe von Modellen – darunter Kimi K2.5, GLM 5.2, MiniMax M2.1 und Qwen 3.5 – die über diesen Endpunkt zugänglich sind. Für Teams, die Agent-Pipelines mit Tausenden von Aufgaben betreiben, kann der Kostenunterschied pro Token erheblich sein. Siehe Novita AI LLM API für den aktuellen Modellkatalog und die Preise.

Wenn Sie Ihren Agent in isolierter Sandbox-Infrastruktur bereitstellen müssen – nützlich für agentische Codeausführung, bei der der Agent Ihr Host-Dateisystem nicht berühren soll – bietet Novita Agent Sandbox eine E2B-kompatible Ausführungsumgebung, die speziell für Agents entwickelt wurde, die auf dem Claude Agent SDK basieren.

Claude Code SDK in CI/CD-Pipelines

Die permission_mode="acceptEdits"- und allowed_tools-Einschränkungen des SDK machen es praktikabel, Agents unbeaufsichtigt in CI auszuführen. Ein typisches GitHub-Actions-Muster:

- name: Run automated code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Wobei review_agent.py etwa Folgendes enthält:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Für Agents, die Änderungen ins Repository zurückschreiben (automatisiertes Refactoring, Dokumentationsgenerierung), kombinieren Sie dies mit einem PostToolUse-Hook, der Änderungen validiert, bevor sie in Git landen.

Fehlerbehebung

No matching distribution found for claude-agent-sdk Ihre Python-Version ist älter als 3.10. Führen Sie python3 --version aus und aktualisieren Sie bei Bedarf.

ANTHROPIC_API_KEY is not set Das SDK benötigt die Umgebungsvariable. Exportieren Sie sie vor dem Ausführen in Ihrer Shell oder .env-Datei.

TypeScript-Agent wird vor Abschluss beendet Stellen Sie sicher, dass Sie die vollständige Iterator-Schleife mit await abwarten. Das SDK muss alle Nachrichtenereignisse verarbeiten, bevor Ihr Prozess beendet wird.

Agent verwendet unerwartete Tools Verwenden Sie allowed_tools, um das Tool-Set explizit einzuschränken. Wenn Sie es nicht angeben, hat der Agent Zugriff auf alle integrierten Tools.

Subagent-Nachrichten erscheinen nicht in der Ausgabe Filtern Sie nach Nachrichten, bei denen parent_tool_use_id gesetzt ist, um Subagent-Ausgaben getrennt vom Haupt-Agent zu identifizieren.

Session wird nicht korrekt fortgesetzt Erfassen Sie session_id aus der SystemMessage mit subtype === "init" am Anfang der ersten Abfrage, nicht aus einer Ergebnisnachricht.

Häufig gestellte Fragen (FAQ)

Was ist der Unterschied zwischen dem Claude Code SDK und dem Anthropic SDK?

Das Claude Agent SDK (ehemals Claude Code SDK) bietet Ihnen einen autonomen Agent, der die Tool-Ausführung automatisch übernimmt. Das Anthropic Client SDK bietet direkten API-Zugriff, bei dem Sie die Tool-Schleife selbst implementieren. Verwenden Sie das Agent SDK für agentische Pipelines; verwenden Sie das Client SDK für direkte Modellaufrufe mit präziser Kontrolle.

Welche Python-Version wird für das claude-agent-sdk benötigt?

Python 3.10 oder höher. Das Paket lässt sich nicht auf Python 3.9 oder älter installieren.

Muss ich die Claude Code CLI installieren, um das TypeScript-SDK zu verwenden?

Nein. Das Paket @anthropic-ai/claude-agent-sdk enthält eine eigene native Claude-Code-Binärdatei als optionale Abhängigkeit.

Kann das Claude Agent SDK andere Modelle als Anthropics Claude verwenden?

Indem Sie ANTHROPIC_BASE_URL auf einen Anthropic-kompatiblen Endpunkt wie https://api.novita.ai/anthropic setzen, können Sie jedes Modell verwenden, das dieser Anbieter hostet – einschließlich Open-Weight-Modellen von Kimi, GLM, MiniMax oder Qwen.

Wie unterscheidet sich das Agent SDK von Claude Managed Agents?

Managed Agents ist eine gehostete REST-API, bei der Anthropic den Agent in ihrer Infrastruktur ausführt. Das Agent SDK ist eine Bibliothek, die die Agent-Schleife in Ihrem eigenen Prozess auf Ihrem eigenen Dateisystem ausführt. Das Agent SDK ist besser für lokale Entwicklung und Agents geeignet, die auf Ihre privaten Dateien oder Dienste zugreifen müssen.

Unterstützt das Claude Agent SDK Streaming-Ausgaben?

Die query()-Funktion gibt einen asynchronen Iterator zurück, der Nachrichten liefert, während der Agent arbeitet. Das ergibt ein streaming-ähnliches Verhalten – Sie sehen Zwischenergebnisse, bevor die endgültige Antwort eintrifft.

Kann ich das Agent SDK mit Amazon Bedrock oder Vertex AI verwenden?

Ja. Setzen Sie CLAUDE_CODE_USE_BEDROCK=1 plus AWS-Anmeldedaten für Bedrock oder CLAUDE_CODE_USE_VERTEX=1 plus Google-Cloud-Anmeldedaten für Vertex AI.

Welche Dokumentation zu „anthropic claude agent sdk“ sollte ich zuerst lesen?

Die offizielle Dokumentation finden Sie unter code.claude.com/docs/en/agent-sdk/overview. Beginnen Sie mit dem Schnellstart, und lesen Sie dann die Leitfäden zu Sessions und Hooks, sobald Ihr Agent funktioniert.

Empfohlene Artikel


Quellen geprüft am 3. Juli 2026: Dokumentation zum Claude Agent SDK, Novita AI LLM API