Claude Agent SDK: Claude Code sicher in Apps einbetten

Wenn Claude Code nicht nur im Terminal helfen soll, sondern in internen Tools, CI, PR-Vorprüfungen, Content-QA oder Support-Konsolen laufen soll, ist heute Claude Agent SDK der richtige Einstieg.

Viele alte Beispiele nennen noch @anthropic-ai/claude-code, claude-code-sdk oder “Claude Code SDK”. Im Juni 2026 verweist die offizielle Dokumentation für TypeScript auf @anthropic-ai/claude-agent-sdk und für Python auf claude-agent-sdk. Prüfen Sie vor dem Kopieren alter Snippets die offizielle Agent SDK overview und den Migration Guide.

Dieser Artikel baut keinen Chatbot. Es geht um einen Agenten, der Dateien lesen, im Repository suchen, MCP-Tools aufrufen, kleine Änderungen mit engen Rechten ausführen, einen bestimmten Test starten und ein prüfbares Ergebnis zurückgeben kann.

Was das Agent SDK leistet

Claude Agent SDK bringt die Agentenschleife von Claude Code in eigene TypeScript- oder Python-Programme. Eine Agentenschleife bedeutet: Claude wählt eine Aktion, ruft ein Tool auf, liest das Ergebnis und entscheidet dann über den nächsten Schritt. Das ist deutlich mehr als eine einzelne Chat-API-Anfrage.

Thema	Aktuelle Empfehlung
TypeScript-Paket	@anthropic-ai/claude-agent-sdk
Python-Paket	claude-agent-sdk
CLI vs SDK	CLI für Menschen, SDK für Apps und Automatisierung
Client SDK vs Agent SDK	Client SDK: Tool-Schleife selbst bauen; Agent SDK: Claude-Code-Schleife nutzen
Hauptrisiko	Breitere Rechte machen Agenten nützlicher und Fehler gefährlicher

Das TypeScript SDK enthält normalerweise ein natives Claude-Code-Binary als optionale Abhängigkeit. Die CLI muss daher nicht immer separat installiert werden. Wenn ein Package Manager optional dependencies überspringt, kann das Binary fehlen. Dann die Installationspolitik korrigieren oder pathToClaudeCodeExecutable auf ein installiertes claude zeigen lassen.

Kopierbares Setup

Wir nutzen TypeScript mit tsx, damit die Beispiele ohne Build-Pipeline laufen.

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

package.json sollte so aussehen:

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

Der API-Key gehört in die Umgebung, nicht ins Repository, nicht in Screenshots und nicht in CI-Logs.

export ANTHROPIC_API_KEY="sk-ant-..."

Unter Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Erstellen Sie zuerst src/read-only-audit.ts. Dieser Agent ist bewusst nur lesend unterwegs.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "Prüfe dieses Repository im reinen Lesemodus.",
  "Finde TODO-Kommentare, alte Abhängigkeiten und schwach getestete Bereiche.",
  "Gib eine priorisierte Liste mit konkreten Dateireferenzen zurück.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Ausführen:

npm run audit

Der Lesemodus ist kein Formalismus. Er zeigt, ob der Agent brauchbare Signale liefert, bevor Edit, Write oder Bash erlaubt werden.

Praktische Einsatzfälle

Claude Agent SDK lohnt sich, wenn eine Aufgabe Beobachtung, Tool-Nutzung und Entscheidung braucht. In Masa’s Entwicklungs- und Content-Workflows sind diese vier Fälle realistisch:

Einsatzfall	Tools	Ergebnis	Grenze
PR-Vorprüfung	Read, Glob, Grep	Risiken, fehlende Tests, Review-Fokus	Kommentar erst nach menschlicher Prüfung
Kleine Codekorrektur	Read, Edit, Bash(npm test)	Minimaler Diff und Testergebnis	Push, Deploy, Löschen verbieten
Incident-Triage	MCP-Runbook, Logsuche	Hypothesen und nächste Checks	Produktionstools nur lesend
Mehrsprachige Artikel-QA	Read, Grep	Mojibake, fehlende CTA, alte Links	Sprachqualität menschlich prüfen

Als Ergänzung passen der Permissions Guide, der MCP Server Guide und die Claude Code Produktivitätstipps.

Runbook-Tool mit MCP

MCP steht für Model Context Protocol. Es ist ein Standard, um Tools und Datenquellen für Agenten bereitzustellen. Der offizielle MCP guide zeigt die Verbindung von MCP-Servern im Agent SDK. Für kleine Fälle kann ein MCP-Server auch im selben Prozess definiert werden.

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const runbooks: Record<string, string> = {
  billing: "Fehlzahlungen, Stripe-Webhooks und letzten Deploy prüfen.",
  search: "Indexzeit, Algolia task status und API-Limits prüfen.",
  content: "CMS-Sync, Locale-Slugs und Hero-Bild prüfen.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "Gibt ein schreibgeschütztes Betriebs-Runbook für einen Service zurück",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "Kein Runbook gefunden.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "Schlage erste Checks für einen Publishing-Incident vor.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Wichtig ist der Name in allowedTools: MCP-Tools werden als mcp__serverName__toolName erlaubt. Nur lookup_runbook reicht nicht.

Schreiben erlauben, ohne alles freizugeben

Wenn die Leseprüfung nützlich ist, kann ein Agent kleine Änderungen erzeugen. Grenzen bleiben Pflicht. Lesen Sie vor einem schreibenden Agenten den offiziellen permissions guide.

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = [
  "Behebe genau einen kleinen TypeScript-Fehler unter src.",
  "Führe danach npm test aus und berichte Diff-Zusammenfassung und Ergebnis.",
  "Kein großer Refactor und keine neuen Abhängigkeiten.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

Dieses Muster erstellt einen prüfbaren Diff mit Testnachweis. Es ist kein Freifahrtschein für Push, Deploy, Release oder Kundendaten.

Fehlerbilder und Fallen

Erste Falle: alte Namen. Beispiele mit @anthropic-ai/claude-code oder ClaudeCodeOptions können vor der Migration liegen.

Zweite Falle: freies Bash. Das kann Tests, Git, Deploy, Paketinstallationen oder Löschbefehle einschließen. Beginnen Sie mit Bash(npm test).

Dritte Falle: kein explizites cwd. Lokal, CI und Worker starten oft in verschiedenen Verzeichnissen. Produktion braucht ein klares Zielverzeichnis.

Vierte Falle: Agent SDK wie ein Chat SDK behandeln. Ein Agent liest viele Dateien und nutzt mehrere Tool-Turns. Prüfen Sie den offiziellen cost tracking guide, loggen Sie Usage und setzen Sie Grenzen.

Fünfte Falle: unklare MCP-Tools. Name, Beschreibung, Schema und Annotationen müssen sagen, wann das Tool genutzt wird und ob es nur liest.

Checkliste, CTA und Praxistest

• API-Keys und Tokens erscheinen nicht in Logs.
• Der erste Lauf nutzt nur Read, Glob, Grep.
• Schreibende Agenten haben cwd, Toolgrenzen und maxTurns.
• MCP trennt Lesetools von destruktiven Aktionen.
• Testbefehle sind konkret, nicht freie Shell.
• Ein Mensch prüft Diff und Tests vor dem Merge.

Claude Agent SDK ist nicht die Antwort auf “wie viel kann ich automatisieren?”, sondern auf “welche Automatisierung bleibt prüfbar?”. Das gilt auch für monetarisierte Inhalte: CTA, Produktlinks, Analytics Events und Beratungsformulare können in einem Lauf betroffen sein.

Für den Start hilft das kostenlose Cheatsheet. Wiederverwendbare Prompts und Setup-Material finden Sie unter Produkte. Für Team-Rollout, Permissions, MCP, CI-Gates und sichere Automation nutzen Sie Claude Code Training und Beratung.

Für diese Aktualisierung habe ich offizielle Seiten zu overview, TypeScript reference, MCP, permissions, migration und cost tracking geprüft. Der wichtigste praktische Schritt ist das erste Beispiel im Lesemodus: npm run audit erlaubt Beobachtung, bevor MCP, Editieren und Tests hinzukommen.