Claude Agent SDK: Einstieg
Agenten mit dem Claude Agent SDK in Python und TypeScript bauen: offizielle Paketnamen, der query()-Einstieg, ClaudeSDKClient und der Betrieb über QCode (2026).
Brauchen Sie einen API-Key? Registrieren →Endpunkte & Base-URLs →
Auf dieser Seite
Zuletzt überprüft: 2026-10-20 · 📄 Gemäß offizieller Dokumentation (Claude Agent SDK Overview, Python- und TypeScript-Referenz, geprüft am 2026-10-20)
Das Claude Agent SDK ist das offizielle Paket von Anthropic, mit dem Sie Claude Code als Bibliothek verwenden: Für Python installieren Sie claude-agent-sdk, für TypeScript @anthropic-ai/claude-agent-sdk, und rufen query() auf. Es ist eine Bibliothek, die die Claude-Code-Binärdatei ausführt und bringt Tools, Berechtigungen, Sitzungen und Hooks mit, sodass Sie Claude-Code-Funktionen in Ihre eigene Anwendung einbetten können (geprüft am 2026-10-20).
Was ist das Claude Agent SDK?¶
Claude Agent SDK stellt die Bausteine bereit, mit denen Sie Anwendungen erstellen können, die Folgendes tun:
- Natürlichsprachliche Anweisungen verstehen und komplexe Aufgaben ausführen
- Tools verwenden (Suche, Codeausführung, Dateioperationen usw.)
- Gesprächskontext für mehrere Interaktionsrunden beibehalten
- Mit externen Diensten verbinden (über MCP-Server)
Agent SDK installieren¶
Python¶
pip install claude-agent-sdk
TypeScript¶
npm install @anthropic-ai/claude-agent-sdk
Die SDK-Version folgt der gebündelten Claude-Code-Version: Im offiziellen Beispiel bündelt SDK v0.3.191 Claude Code v2.1.191 (geprüft am 2026-10-20).
Erste Schritte mit query()¶
Python¶
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions()
async for message in query(prompt="Create a Python web server", options=options):
print(message)
asyncio.run(main())
TypeScript¶
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Create a Python web server",
options: {}
})) {
console.log(message);
}
query() erstellt standardmäßig eine neue Sitzung; für mehrere Austausche in derselben Sitzung verwenden Sie ClaudeSDKClient in Python (geprüft am 2026-10-20).
QCode konfigurieren¶
In Python werden die Variablen aus ClaudeAgentOptions(env={...}) über die geerbte Prozessumgebung gelegt:
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
env={
"ANTHROPIC_BASE_URL": "https://api.qcode.cc/api",
"ANTHROPIC_AUTH_TOKEN": "cr_your_api_key",
}
)
In TypeScript ersetzt options.env die process.env, daher müssen Sie ...process.env einfügen, um geerbte Variablen wie PATH zu behalten:
const options = { env: { ...process.env, ANTHROPIC_BASE_URL: "https://api.qcode.cc/api", ANTHROPIC_AUTH_TOKEN: "cr_..." } };
Verwenden Sie die Authentifizierung per API-Schlüssel: Laut offizieller Dokumentation dürfen Drittentwickler in SDK-basierten Produkten keine claude.ai-Anmeldung anbieten (geprüft am 2026-10-20). QCode rechnet pro Token ab, die Preise je Modell stehen auf qcode.cc/models.
Agent SDK, Claude Code CLI und Client SDK¶
| Punkt | Agent SDK | Claude Code CLI | Client SDK |
|---|---|---|---|
| Typ | Python-/TypeScript-Bibliothek | Terminal-Oberfläche | anthropic / @anthropic-ai/sdk |
| Ausführung | Bibliothek, die die Claude-Code-Binärdatei ausführt | Interaktive Nutzung im Terminal | Ruft die Messages API direkt auf |
| Mitgeliefert | Tools, Berechtigungen, Sitzungen und Hooks | Tools, Berechtigungen, Sitzungen und Hooks | Tool-Aufrufe implementieren Sie selbst |
| Einsatz | Claude Code in die eigene Anwendung einbetten | Tägliche interaktive Entwicklung | Nur direkte Aufrufe der Messages API |
Client SDK: die Messages API direkt aufrufen¶
Die folgenden Beispiele verwenden das Client SDK (anthropic / @anthropic-ai/sdk), nicht das Agent SDK; es passt, wenn Sie die Messages API nur direkt aufrufen möchten.
Client SDK installieren¶
Python SDK¶
pip install anthropic
TypeScript SDK¶
npm install @anthropic-ai/sdk
Einfacher Nachrichtenaufruf¶
from anthropic import Anthropic
# Via QCode.cc API
client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key="cr_your_api_key"
)
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Explain what a RESTful API is"}
]
)
print(message.content[0].text)
Streaming-Antwort¶
with client.messages.stream(
model="claude-opus-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Write a Python quicksort function"}
]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
Tool Use¶
Tool Use ist die Kernfunktion von Agenten und ermöglicht es dem Modell, externe Tools aufzurufen.
Tools definieren¶
from anthropic import Anthropic
client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key="cr_your_api_key"
)
# Define search tool
tools = [
{
"name": "search_web",
"description": "Search the web for information",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search keywords"
}
},
"required": ["query"]
}
},
{
"name": "calculate",
"description": "Perform mathematical calculations",
"input_schema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Mathematical expression, e.g., '2 + 3 * 4'"
}
},
"required": ["expression"]
}
}
]
# Send message with tools
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Calculate (15 + 25) * 2 and search for what this means"}
],
tools=tools
)
# Process tool calls
for content in message.content:
if content.type == "text":
print(content.text)
elif content.type == "tool_use":
print(f"Calling tool: {content.name}")
print(f"Parameters: {content.input}")
# Simulate executing the tool
if content.name == "calculate":
result = eval(content.input["expression"])
tool_result = str(result)
elif content.name == "search_web":
tool_result = f"Results for '{content.input['query']}'..."
# Send the result back to the model
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Calculate (15 + 25) * 2 and search for what this means"},
message,
{
"role": "user",
"content": None,
"type": "tool_result",
"tool_use_id": content.id,
"content": tool_result
}
],
tools=tools
)
Streaming-Tool-Aufrufe¶
with client.messages.stream(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Create a file named hello.py that prints 'Hello, World!'"}
],
tools=[
{
"name": "write_file",
"description": "Write content to a file",
"input_schema": {
"type": "object",
"properties": {
"filename": {"type": "string"},
"content": {"type": "string"}
},
"required": ["filename", "content"]
}
}
]
) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
elif event.delta.type == "tool_use_delta":
print(f"\n[Tool Call] {event.delta.name}")
Prompt Caching¶
Prompt Caching kann die Kosten bei langen Konversationen erheblich senken:
# System prompt (will be cached)
system_prompt = """You are a professional code review assistant.
Your responsibilities:
1. Check code security
2. Identify performance issues
3. Verify code standards
4. Provide improvement suggestions
"""
# Use cache_control to mark cacheable content
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
system=[
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "Review @src/auth/login.ts"}
]
)
Beispiel: Agent-Erstellung¶
from anthropic import Anthropic
from typing import List
class CodeReviewAgent:
def __init__(self, api_key: str):
self.client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key=api_key
)
self.system_prompt = """You are a professional code review assistant.
Focus on: security, performance, readability, best practices.
Output for each review: issue list, severity, fix suggestions."""
def review(self, code_snippet: str) -> str:
message = self.client.messages.create(
model="claude-opus-5",
max_tokens=4096,
system=self.system_prompt,
messages=[
{"role": "user", "content": f"Review this code:\n\n{code_snippet}"}
]
)
return message.content[0].text
# Usage
agent = CodeReviewAgent("cr_your_api_key")
result = agent.review("SELECT * FROM users WHERE id = " + user_id)
QCode-Konfiguration für das Client SDK¶
import os
# Method 1: Environment variable
os.environ["ANTHROPIC_BASE_URL"] = "https://api.qcode.cc/api"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "cr_your_key"
client = Anthropic() # Auto-reads environment variables
# Method 2: Asia node (recommended for mainland China)
client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key="cr_your_key"
)
Nächste Schritte¶
- API-Referenz – Vollständige Dokumentation der API-Parameter
- Modellauswahl-Handbuch – Das richtige Modell wählen
- MCP-Server – Externe Dienste verbinden, um Funktionen zu erweitern
Mit QCode starten
Ein API-Key für Claude Code, Codex und mehr – Abrechnung pro Token, Preise je Modell auf qcode.cc/models