Claude Code SDK: Ein Entwickler-Leitfaden zum Aufbau von Agenten

Das Claude Code SDK verwandelt Claude Code von einem interaktiven Coding-Assistenten in eine vollständig programmierbare Agenten-Laufzeitumgebung. Wer Claude Code bisher interaktiv genutzt hat, erschließt sich mit dem SDK grundlegend neue Möglichkeiten – automatisierte Pipelines, individuelle UIs, Multi-Agenten-Orchestrierung und CI/CD-Integration.

Was ist das Claude Code SDK?

Das Claude Code SDK ist eine programmatische Schnittstelle, die es ermöglicht:

• Claude Code nicht-interaktiv aus Skripten und Pipelines heraus auszuführen
• Zu steuern, welche Dateien, Verzeichnisse und Werkzeuge im Kontext sind
• Strukturierte Ausgaben für die Weiterverarbeitung zu parsen
• Claude Code mit anderen Tools in automatisierten Workflows zu verketten
• Individuelle UIs auf Basis von Claude Codes Reasoning zu erstellen

Verfügbar als Node.js-Paket:

npm install @anthropic-ai/claude-code

Oder per CLI im nicht-interaktiven Modus aufrufen:

claude -p "Dein Prompt hier" --output-format json

Grundlegende SDK-Konzepte

Nicht-interaktiver Modus

Der einfachste SDK-Anwendungsfall: Claude Code mit einem Prompt ausführen, Ausgabe erhalten, fertig.

# CLI nicht-interaktiv
claude -p "Untersuche src/auth.ts auf Sicherheitslücken" \
  --output-format json \
  --max-turns 5

// SDK
const { query } = require('@anthropic-ai/claude-code');

const result = await query({
  prompt: "Untersuche src/auth.ts auf Sicherheitslücken",
  options: {
    maxTurns: 5,
    outputFormat: 'json'
  }
});

Tool-Konfiguration

Steuere, auf welche Tools Claude Code in deinem SDK-Aufruf Zugriff hat:

const result = await query({
  prompt: "Erstelle eine Test-Suite für src/utils.ts",
  options: {
    allowedTools: ['Read', 'Write', 'Bash'],
    // Nicht benötigte Tools deaktivieren:
    // disallowedTools: ['WebSearch', 'mcp__custom_tool']
  }
});

Eigene System-Prompts

Überschreibe den Standard-System-Prompt von Claude Code für spezialisiertes Verhalten:

const result = await query({
  prompt: "Refaktoriere dieses Modul",
  options: {
    systemPrompt: `Du bist ein TypeScript-Experte, spezialisiert auf funktionale Programmiermuster.
    Verwende stets unveränderliche Datenstrukturen. Nutze Result-Typen für die Fehlerbehandlung.
    Verwende niemals any- oder unknown-Typen.`,
  }
});

Praktische SDK-Muster

1. Automatisiertes Code-Review in CI

// .github/workflows/code-review.js
const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

const diff = execSync('git diff main...HEAD').toString();

const review = await query({
  prompt: `Überprüfe diesen PR-Diff auf: Sicherheitsprobleme, Performance-Schwächen und fehlende Tests.
  Ausgabe als JSON mit den Schlüsseln: security[], performance[], testing[].
  
  Diff:
  ${diff}`,
  options: {
    outputFormat: 'json',
    allowedTools: ['Read'],  // Nur lesend in CI
    maxTurns: 3
  }
});

console.log(JSON.parse(review.result));

2. Automatisierte Dokumentationsgenerierung

const fs = require('fs');
const { query } = require('@anthropic-ai/claude-code');

async function generateDocs(srcPath) {
  const result = await query({
    prompt: `Erstelle umfassende JSDoc-Dokumentation für alle exportierten Funktionen in ${srcPath}.
    Füge Parameter-Beschreibungen, Rückgabetypen und Verwendungsbeispiele hinzu.
    Schreibe die aktualisierte Datei mit der hinzugefügten Dokumentation.`,
    options: {
      allowedTools: ['Read', 'Write'],
      cwd: process.cwd()
    }
  });
  return result;
}

3. Multi-Agenten-Pipeline mit externen Fähigkeiten

Hier entfaltet die AnyCap-Integration ihre volle Stärke. Eine Pipeline, in der Claude Code das Code-Reasoning übernimmt und AnyCap für Medien und Publishing zuständig ist:

const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

async function buildAndPublishDocs(repoPath) {
  // Schritt 1: Claude Code generiert Dokumentation
  const docsResult = await query({
    prompt: "Erstelle eine umfassende README für dieses Projekt mit Setup-Anleitung, API-Referenz und Beispielen",
    options: {
      cwd: repoPath,
      allowedTools: ['Read', 'Write', 'Bash']
    }
  });

  // Schritt 2: AnyCap generiert ein Hero-Diagramm
  execSync(`anycap image generate \
    --prompt "Technisches Architekturdiagramm für ein Entwickler-Tool, klarer minimalistischer Stil" \
    --model nano-banana-2 \
    -o ${repoPath}/docs/architecture.png`);

  // Schritt 3: AnyCap veröffentlicht als Webseite
  const pageResult = execSync(`anycap page deploy ${repoPath}/docs/`).toString();
  
  return { docs: docsResult, page: JSON.parse(pageResult) };
}

SDK-Authentifizierung

Das SDK verwendet dieselbe Authentifizierung wie Claude Code. API-Key setzen:

export ANTHROPIC_API_KEY=dein_key_hier

Oder für Team-Umgebungen eine umgebungsspezifische Konfiguration verwenden:

const { query } = require('@anthropic-ai/claude-code');

// SDK liest ANTHROPIC_API_KEY automatisch
// Oder explizit übergeben:
process.env.ANTHROPIC_API_KEY = await getSecretFromVault('anthropic-api-key');

Ausgabeformate

Das SDK unterstützt drei Ausgabeformate:

// JSON-Ausgabe enthält Metadaten
{
  "result": "Die Funktion hat eine potenzielle SQL-Injection-Schwachstelle...",
  "is_error": false,
  "session_id": "sess_xxxx",
  "cost_usd": 0.0043,
  "num_turns": 2
}

Rate-Limits und Kostenmanagement in SDK-Workflows

SDK-basierte Automatisierung kann Tokens schneller verbrauchen als die interaktive Nutzung. Eingebaute Schutzmaßnahmen:

const result = await query({
  prompt: "...",
  options: {
    maxTurns: 5,        // Reasoning-Iterationen begrenzen
    timeoutMs: 30000,   // Timeout für lang laufende Aufgaben
  }
});

// Kosten in der Produktion immer prüfen
if (result.cost_usd > 0.10) {
  logger.warn(`Sitzung mit hohen Kosten: $${result.cost_usd}`);
}

Für ressourcenintensive Aufgaben (Bildgenerierung, Videoerstellung, Websuche) empfiehlt es sich, diese an AnyCap auszulagern, anstatt sie von Claude Code im Kontext verarbeiten zu lassen. Das hält die SDK-Kosten planbar und verhindert, dass Claude Ratenlimits bei Nicht-Reasoning-Aufgaben erreicht.

Erste Schritte

# SDK installieren
npm install @anthropic-ai/claude-code

# AnyCap für Fähigkeitserweiterung installieren
curl -fsSL https://anycap.ai/install.sh | sh

# AnyCap-Skill zu Claude Code hinzufügen
npx -y skills add anycap-ai/anycap -y

→ AnyCap für Claude Code → Tools zu Claude Code hinzufügen – Leitfaden