Claude Agent SDK Entwicklerleitfaden
Das Claude Code SDK wurde offiziell zum Claude Agent SDK umbenannt – seine Fähigkeiten umfassen nun den Aufbau von KI-Agenten über Coding-Aufgaben hinaus. Dieser Leitfaden behandelt Python/TypeScript-Quickstarts, Kernkonzepte, den Vergleich mit Managed Agents und die Anbindung über QCode.
Aktualisiert 2026-10-20
Was ist das Claude Agent SDK
Offizielle Umbenennung
Dem offiziellen Migrationsleitfaden zufolge wurde die Dokumentation mit der Umbenennung neu gegliedert und auch die Installations-Paketnamen haben sich geändert; beide Namen beziehen sich auf dasselbe SDK (geprüft am 2026-10-20).
Warum die Umbenennung
Der offizielle Grund ist der Scope: Die Bibliothek dient dem Aufbau von KI-Agenten über reine Coding-Aufgaben hinaus (geprüft am 2026-10-20).
Einheitliche Toolschnittstelle
Bietet dieselben Tools, denselben Agent-Loop und dieselbe Kontextverwaltung wie Claude Code – als Bibliothek in Ihre eigene Python- oder TypeScript-Anwendung einbettbar und in einem eigenen Prozess ausführbar.
Produktionsreif
Eingebaute Tools zum Lesen, Schreiben und Bearbeiten von Dateien, zum Ausführen von Befehlen und zur Websuche – dazu Sitzungsverwaltung, Berechtigungen, Hooks, Subagents und MCP-Anbindung.
Mehrsprachige Unterstützung
Offiziell in zwei Paketen gepflegt: claude-agent-sdk für Python und @anthropic-ai/claude-agent-sdk für TypeScript; beide werden fortlaufend aktualisiert.
Kernkonzepte
Tools
Vom Agenten aufrufbare Funktionen, die mit Decoratoren deklariert werden und automatisch ein JSON Schema erzeugen, damit Claude sie versteht und aufruft.
Agent Loop
Claude denkt → wählt ein Tool → führt es aus → beobachtet das Ergebnis → denkt weiter, bis die Aufgabe abgeschlossen ist.
Speicher / Kontext
Einheitliche Verwaltung von Kurzzeitspeicher innerhalb der Sitzung (Verlauf) und Langzeitspeicher über Sitzungen hinweg (Persistenz in Dateien/Datenbank).
Berechtigungen
Feingranulare Berechtigungskontrolle: Zugriffsscope für Dateisystem, Netzwerk, Code-Ausführung und externe APIs lassen sich unabhängig konfigurieren.
Python-Quickstart
Ihr erster Claude Agent in drei Schritten – für QCode geben Sie lediglich den QCode-Schlüssel und den Anthropic-Endpunkt an.
Schritt 1: SDK installieren
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdkSchritt 2: Agent erstellen
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
system_prompt="You are an expert Python developer",
permission_mode="acceptEdits",
)
async for message in query(
prompt="Create a Python web server", options=options
):
print(message)
asyncio.run(main())Schritt 3: Eigene Tools definieren
import asyncio
from typing import Any
from claude_agent_sdk import (
ClaudeAgentOptions, create_sdk_mcp_server, query, tool
)
@tool("get_weather", "Get current weather for a city", {"city": str})
async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
return {
"content": [
{"type": "text",
"text": f"Weather in {args['city']}: 22 C, sunny"}
]
}
weather_server = create_sdk_mcp_server(
name="weather",
version="1.0.0",
tools=[get_weather],
)
options = ClaudeAgentOptions(
mcp_servers={"weather": weather_server},
allowed_tools=["mcp__weather__get_weather"],
)
async def main():
async for message in query(
prompt="What's the weather in Beijing and Shanghai?",
options=options,
):
print(message)
asyncio.run(main())TypeScript-Quickstart
Entwicklung von Claude-Agenten in Node.js / Bun mit vollständiger Typunterstützung.
Schritt 1: SDK installieren
npm install @anthropic-ai/claude-agent-sdkSchritt 2: Agent erstellen
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Create a Python web server",
options: { systemPrompt: "You are an expert Python developer" },
})) {
console.log(message);
}Schritt 3: Vollständiges Beispiel
import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
const getTemperature = tool(
"get_temperature",
"Get the current temperature at a location",
{
latitude: z.number().describe("Latitude coordinate"),
longitude: z.number().describe("Longitude coordinate")
},
async (args) => {
return {
content: [{ type: "text", text: `Temperature at ${args.latitude}` }]
};
}
);
const weatherServer = createSdkMcpServer({
name: "weather",
version: "1.0.0",
tools: [getTemperature]
});
for await (const message of query({
prompt: "What's the temperature in Beijing?",
options: {
mcpServers: { weather: weatherServer },
allowedTools: ["mcp__weather__get_temperature"]
}
})) {
console.log(message);
}Agent SDK vs. Managed Agents
| Aspekt |
Agent SDK
|
Managed Agents
|
|---|---|---|
| Laufzeitumgebung | Self-Hosted (lokal / eigener Server) | Anthropic hostet den Agent-Loop; Sessions können in einer verwalteten Cloud-Sandbox oder in einer Sandbox Ihrer eigenen Infrastruktur laufen. |
| Skalierung | Manuelle Instanzverwaltung | Automatische elastische Skalierung |
| Anwendungsfall | Prototyping, stark individualisierte Szenarien | Produktiver Einsatz von Agenten im Unternehmensumfeld |
Nutzung über QCode.cc
Richten Sie ANTHROPIC_BASE_URL auf den Endpunkt https://api.qcode.cc/api und rufen Sie das Agent SDK mit Ihrem QCode-Schlüssel auf; welche Modelle aufrufbar sind, zeigt /models. Bei Managed Agents hostet Anthropic den Agent-Loop, und Sessions laufen in einer verwalteten Cloud-Sandbox oder in einer Sandbox Ihrer eigenen Infrastruktur (offizielle Dokumentation, abgerufen am 2026-10-20); diesen Pfad haben wir nicht verifiziert und übernehmen dafür keine Zusicherung.
# Python SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_API_KEY=your-qcode-api-key
# TypeScript SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_API_KEY=your-qcode-api-key
# Point the endpoint at your own gateway: the SDK reads it from env
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
env={
"ANTHROPIC_BASE_URL": "https://api.qcode.cc/api",
},
)Claude-Modelle Fable 5 / Opus 4.8 / Sonnet 4.6 sind über QCode aufrufbar; Ob Haiku 4.5 und weitere Modelle aufrufbar sind, zeigt /models (geprüft am 2026-10-20).
Vollständige Unterstützung für Tool-Aufrufe (Function Calling)
Unterstützung für Streaming-Ausgabe
Gleiches Format wie die offizielle Messages API – das Agent SDK benötigt lediglich ANTHROPIC_BASE_URL
Beginnen Sie noch heute mit dem Aufbau von KI-Agenten
Registrieren Sie sich bei QCode.cc für stabilen Claude-API-Zugriff aus China – mit Unterstützung aller Agent-SDK-Funktionen.