TypeScript

Voraussetzungen

Node.js 18+

Installation

Installieren Sie @anthropic-ai/claude-code von NPM:

npm install -g @anthropic-ai/claude-code

Um den TypeScript SDK-Quellcode anzuzeigen, besuchen Sie die @anthropic-ai/claude-code Seite auf NPM.

Grundlegende Verwendung

Die primäre Schnittstelle über das TypeScript SDK ist die query Funktion, die einen asynchronen Iterator zurückgibt, der Nachrichten streamt, sobald sie ankommen:

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

for await (const message of query({
  prompt: "Systemleistung analysieren",
  abortController: new AbortController(),
  options: {
    maxTurns: 5,
    systemPrompt: "Du bist ein Leistungsingenieur",
    allowedTools: ["Bash", "Read", "WebSearch"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Konfigurationsoptionen

Argument	Typ	Beschreibung	Standard
`abortController`	`AbortController`	Abort-Controller zum Abbrechen von Operationen	`new AbortController()`
`additionalDirectories`	`string[]`	Zusätzliche Verzeichnisse, die in die Sitzung einbezogen werden sollen	`undefined`
`allowedTools`	`string[]`	Liste der Tools, die Claude verwenden darf	Alle Tools standardmäßig aktiviert
`appendSystemPrompt`	`string`	Text, der an den Standard-System-Prompt angehängt wird	`undefined`
`canUseTool`	`CanUseTool`	Benutzerdefinierte Berechtigungsfunktion für Tool-Verwendung	`undefined`
`continue`	`boolean`	Die neueste Sitzung fortsetzen	`false`
`customSystemPrompt`	`string`	Den Standard-System-Prompt vollständig ersetzen	`undefined`
`cwd`	`string`	Aktuelles Arbeitsverzeichnis	`process.cwd()`
`disallowedTools`	`string[]`	Liste der Tools, die Claude nicht verwenden darf	`undefined`
`env`	`Dict<string>`	Umgebungsvariablen, die gesetzt werden sollen	`undefined`
`executable`	`'bun' \| 'deno' \| 'node'`	Welche JavaScript-Laufzeit verwendet werden soll	`node` beim Ausführen mit Node.js, `bun` beim Ausführen mit Bun
`executableArgs`	`string[]`	Argumente, die an die ausführbare Datei übergeben werden	`[]`
`fallbackModel`	`string`	Modell, das verwendet wird, wenn das primäre Modell fehlschlägt	`undefined`
`maxThinkingTokens`	`number`	Maximale Tokens für Claudes Denkprozess	`undefined`
`maxTurns`	`number`	Maximale Anzahl von Gesprächsrunden	`undefined`
`mcpServers`	`Record<string, McpServerConfig>`	MCP-Server-Konfigurationen	`undefined`
`model`	`string`	Zu verwendendes Claude-Modell	Verwendet Standard aus CLI-Konfiguration
`pathToClaudeCodeExecutable`	`string`	Pfad zur Claude Code ausführbaren Datei	Ausführbare Datei, die mit `@anthropic-ai/claude-code` geliefert wird
`permissionMode`	`PermissionMode`	Berechtigungsmodus für die Sitzung	`"default"` (Optionen: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`)
`permissionPromptToolName`	`string`	Name des MCP-Tools für Berechtigungsaufforderungen	`undefined`
`resume`	`string`	Sitzungs-ID zum Fortsetzen	`undefined`
`stderr`	`(data: string) => void`	Callback für stderr-Ausgabe	`undefined`
`strictMcpConfig`	`boolean`	Strenge MCP-Konfigurationsvalidierung durchsetzen	`undefined`

Mehrrunden-Gespräche

Für Mehrrunden-Gespräche haben Sie zwei Optionen.

Sie können Antworten generieren und sie fortsetzen, oder Sie können den Streaming-Eingabemodus verwenden, der einen async/generator für ein Array von Nachrichten akzeptiert. Derzeit ist der Streaming-Eingabemodus die einzige Möglichkeit, Bilder über Nachrichten anzuhängen.

Fortsetzen mit Sitzungsverwaltung

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

// Neueste Unterhaltung fortsetzen
for await (const message of query({
  prompt: "Jetzt refaktoriere das für bessere Leistung",
  options: { continue: true }
})) {
  if (message.type === "result") console.log(message.result);
}

// Spezifische Sitzung fortsetzen
for await (const message of query({
  prompt: "Die Tests aktualisieren",
  options: {
    resume: "550e8400-e29b-41d4-a716-446655440000",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Streaming-Eingabemodus

Der Streaming-Eingabemodus ermöglicht es Ihnen, Nachrichten als asynchrones Iterable anstatt als einzelnen String bereitzustellen. Dies ermöglicht Mehrrunden-Gespräche, Bildanhänge und dynamische Nachrichtengenerierung:

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

// Einen asynchronen Generator für Streaming-Nachrichten erstellen
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Beginne mit der Analyse dieser Codebasis"
    }
  };
  
  // Auf eine Bedingung oder Benutzereingabe warten
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Konzentriere dich jetzt auf das Authentifizierungsmodul"
    }
  };
}

// Streaming-Eingabe verwenden
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Bash"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Streaming-Eingabe mit Bildern

Der Streaming-Eingabemodus ist die einzige Möglichkeit, Bilder über Nachrichten anzuhängen:

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* messagesWithImage() {
  // Ein Bild mit Text senden
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Analysiere diesen Screenshot und schlage Verbesserungen vor"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("screenshot.png", "base64")
          }
        }
      ]
    }
  };
}

for await (const message of query({
  prompt: messagesWithImage()
})) {
  if (message.type === "result") console.log(message.result);
}

Benutzerdefinierte System-Prompts

System-Prompts definieren die Rolle, Expertise und das Verhalten Ihres Agenten:

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

// SRE-Incident-Response-Agent
for await (const message of query({
  prompt: "API ist ausgefallen, untersuchen",
  options: {
    systemPrompt: "Du bist ein SRE-Experte. Diagnostiziere Probleme systematisch und biete umsetzbare Lösungen.",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

// An Standard-System-Prompt anhängen
for await (const message of query({
  prompt: "Diese Funktion refaktorieren",
  options: {
    appendSystemPrompt: "Immer umfassende Fehlerbehandlung und Unit-Tests einschließen.",
    maxTurns: 2
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Benutzerdefinierte Tools über MCP

Das Model Context Protocol (MCP) ermöglicht es Ihnen, Ihren Agenten benutzerdefinierte Tools und Fähigkeiten zu geben:

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

// SRE-Agent mit Überwachungstools
for await (const message of query({
  prompt: "Den Ausfall des Zahlungsdienstes untersuchen",
  options: {
    mcpConfig: "sre-tools.json",
    allowedTools: ["mcp__datadog", "mcp__pagerduty", "mcp__kubernetes"],
    systemPrompt: "Du bist ein SRE. Verwende Überwachungsdaten zur Diagnose von Problemen.",
    maxTurns: 4
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Benutzerdefinierte Tools mit MCPs

Sie können benutzerdefinierte Tools mit MCPs implementieren, zum Beispiel hier ist, wie Sie ein benutzerdefiniertes Berechtigungsbehandlungstool erstellen können.

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simuliere eine Berechtigungsprüfung - genehmige, wenn die Eingabe "allow" enthält, andernfalls verweigere',
  {
    tool_name: z.string().describe("Der Name des Tools, das eine Berechtigung anfordert"),
    input: z.object({}).passthrough().describe("Die Eingabe für das Tool"),
    tool_use_id: z.string().optional().describe("Die eindeutige Tool-Verwendungsanfrage-ID"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Berechtigung verweigert durch Test approval_prompt Tool",
                }
          ),
        },
      ],
    };
  }
);

// Im SDK verwenden
import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Die Codebasis analysieren",
  options: {
    permissionPromptTool: "mcp__test-server__approval_prompt",
    mcpConfig: "my-config.json",
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Ausgabeformate

Textausgabe (Standard)

// Standard-Textausgabe
for await (const message of query({
  prompt: "Erkläre Datei src/components/Header.tsx"
})) {
  if (message.type === "result") {
    console.log(message.result);
    // Ausgabe: Dies ist eine React-Komponente, die...
  }
}

JSON-Ausgabe

// Alle Nachrichten für JSON-ähnlichen Zugriff sammeln
const messages = [];
for await (const message of query({
  prompt: "Wie funktioniert die Datenschicht?"
})) {
  messages.push(message);
}

// Auf Ergebnisnachricht mit Metadaten zugreifen
const result = messages.find(m => m.type === "result");
console.log({
  result: result.result,
  cost: result.total_cost_usd,
  duration: result.duration_ms
});

Eingabeformate

// Direkter Prompt
for await (const message of query({
  prompt: "Erkläre diesen Code"
})) {
  if (message.type === "result") console.log(message.result);
}

// Aus Variable
const userInput = "Erkläre diesen Code";
for await (const message of query({ prompt: userInput })) {
  if (message.type === "result") console.log(message.result);
}

Agent-Integrationsbeispiele

SRE-Incident-Response-Agent

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

// Automatisierter Incident-Response-Agent
async function investigateIncident(
  incidentDescription: string,
  severity = "medium"
) {
  const messages = [];

  for await (const message of query({
    prompt: `Incident: ${incidentDescription} (Schweregrad: ${severity})`,
    options: {
      systemPrompt: "Du bist ein SRE-Experte. Diagnostiziere das Problem, bewerte die Auswirkungen und biete sofortige Handlungsschritte.",
      maxTurns: 6,
      allowedTools: ["Bash", "Read", "WebSearch", "mcp__datadog"],
      mcpConfig: "monitoring-tools.json"
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Verwendung
const result = await investigateIncident("Payment API gibt 500-Fehler zurück", "high");
console.log(result.result);

Automatisierte Sicherheitsüberprüfung

import { query } from "@anthropic-ai/claude-code";
import { execSync } from "child_process";

async function auditPR(prNumber: number) {
  // PR-Diff abrufen
  const prDiff = execSync(`gh pr diff ${prNumber}`, { encoding: 'utf8' });

  const messages = [];
  for await (const message of query({
    prompt: prDiff,
    options: {
      systemPrompt: "Du bist ein Sicherheitsingenieur. Überprüfe diese PR auf Schwachstellen, unsichere Muster und Compliance-Probleme.",
      maxTurns: 3,
      allowedTools: ["Read", "Grep", "WebSearch"]
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Verwendung
const report = await auditPR(123);
console.log(JSON.stringify(report, null, 2));

Mehrrunden-Rechtsassistent

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

async function legalReview() {
  // Rechtsüberprüfungssitzung starten
  let sessionId: string;

  for await (const message of query({
    prompt: "Rechtsüberprüfungssitzung starten",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
  }

  // Mehrstufige Überprüfung mit derselben Sitzung
  const steps = [
    "contract.pdf auf Haftungsklauseln überprüfen",
    "Compliance mit DSGVO-Anforderungen prüfen",
    "Zusammenfassung der Risiken für Führungskräfte erstellen"
  ];

  for (const step of steps) {
    for await (const message of query({
      prompt: step,
      options: { resume: sessionId, maxTurns: 2 }
    })) {
      if (message.type === "result") {
        console.log(`Schritt: ${step}`);
        console.log(message.result);
      }
    }
  }
}

Nachrichtenschema

Nachrichten, die von der JSON-API zurückgegeben werden, sind streng typisiert nach folgendem Schema:

type SDKMessage =
  // Eine Assistentennachricht
  | {
      type: "assistant";
      uuid: string;
      session_id: string;
      message: Message; // aus Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Eine Benutzernachricht (Eingabe)
  | {
      type: "user";
      uuid?: string;
      session_id: string;
      message: MessageParam; // aus Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Eine Benutzernachricht (Ausgabe/Wiedergabe mit erforderlicher UUID)
  | {
      type: "user";
      uuid: string;
      session_id: string;
      message: MessageParam; // aus Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Wird als letzte Nachricht bei Erfolg ausgegeben
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Wird als letzte Nachricht bei Fehler oder maximalen Runden ausgegeben
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Wird als erste Nachricht zu Beginn einer Unterhaltung ausgegeben
  | {
      type: "system";
      subtype: "init";
      uuid: UUID;
      session_id: string;
      apiKeySource: "user" | "project" | "org" | "temporary";
      cwd: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
      slash_commands: string[];
      output_style: string;
    };

  type SDKPermissionDenial = {
    tool_name: string;
    tool_use_id: string;
    tool_input: Record<string, unknown>;
  }

Zusätzliche unterstützende Typen:

Message, MessageParam und Usage Typen sind im Anthropic TypeScript SDK verfügbar.

Erste Schritte

Mit Claude Code entwickeln

Claude Code SDK

Bereitstellung

Verwaltung

Konfiguration

Referenz

Ressourcen

Voraussetzungen

Installation

Grundlegende Verwendung

Konfigurationsoptionen

Mehrrunden-Gespräche

Fortsetzen mit Sitzungsverwaltung

Streaming-Eingabemodus

Streaming-Eingabe mit Bildern

Benutzerdefinierte System-Prompts

Benutzerdefinierte Tools über MCP

Benutzerdefinierte Tools mit MCPs

Ausgabeformate

Textausgabe (Standard)

JSON-Ausgabe

Eingabeformate

Agent-Integrationsbeispiele

SRE-Incident-Response-Agent

Automatisierte Sicherheitsüberprüfung

Mehrrunden-Rechtsassistent

Nachrichtenschema

Verwandte Ressourcen

Erste Schritte

Mit Claude Code entwickeln

Claude Code SDK

Bereitstellung

Verwaltung

Konfiguration

Referenz

Ressourcen

​Voraussetzungen

​Installation

​Grundlegende Verwendung

​Konfigurationsoptionen

​Mehrrunden-Gespräche

​Fortsetzen mit Sitzungsverwaltung

​Streaming-Eingabemodus

​Streaming-Eingabe mit Bildern

​Benutzerdefinierte System-Prompts

​Benutzerdefinierte Tools über MCP

​Benutzerdefinierte Tools mit MCPs

​Ausgabeformate

​Textausgabe (Standard)

​JSON-Ausgabe

​Eingabeformate

​Agent-Integrationsbeispiele

​SRE-Incident-Response-Agent

​Automatisierte Sicherheitsüberprüfung

​Mehrrunden-Rechtsassistent

​Nachrichtenschema

​Verwandte Ressourcen

Voraussetzungen

Installation

Grundlegende Verwendung

Konfigurationsoptionen

Mehrrunden-Gespräche

Fortsetzen mit Sitzungsverwaltung

Streaming-Eingabemodus

Streaming-Eingabe mit Bildern

Benutzerdefinierte System-Prompts

Benutzerdefinierte Tools über MCP

Benutzerdefinierte Tools mit MCPs

Ausgabeformate

Textausgabe (Standard)

JSON-Ausgabe

Eingabeformate

Agent-Integrationsbeispiele

SRE-Incident-Response-Agent

Automatisierte Sicherheitsüberprüfung

Mehrrunden-Rechtsassistent

Nachrichtenschema

Verwandte Ressourcen