Agent SDK Referenz - TypeScript

​

Installation

npm install @anthropic-ai/claude-agent-sdk

​

In eine einzelne ausführbare Datei kompilieren

import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type: "file" };
import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract";
import { query } from "@anthropic-ai/claude-agent-sdk";

const cliPath = extractFromBunfs(binPath);

for await (const message of query({
  prompt: "Hello",
  options: { pathToClaudeCodeExecutable: cliPath },
})) {
  console.log(message);
}

• Zum Cross-Kompilieren installieren Sie das nicht übereinstimmende Plattformpaket, beispielsweise npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• Unter Windows ist der Binär-Unterpfad claude.exe, beispielsweise @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

​

Importieren Sie den /core-Eintrag, wenn Sie das Agent SDK bündeln

​

Funktionen

​

query()

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

​

Parameter

​

Rückgabewert

​

startup()

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

​

Parameter

​

Rückgabewert

​

Beispiel

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

// Startup-Kosten im Voraus zahlen
const warm = await startup({ options: { maxTurns: 3 } });

// Später, wenn ein Prompt bereit ist, ist dies sofort
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

​

prewarm()

function prewarm(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<SpareProcess>;

​

Beispiel

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

// Beim Anwendungsstart, bevor der Ordner der Sitzung bekannt ist
const spare = await prewarm({ options: { maxTurns: 3 } });

// Später, wenn der Benutzer eine Sitzung in einem Ordner startet
const claimedQuery = spare.claim({
  prompt: "What files are here?",
  options: { cwd: "/path/to/project" },
});

spare.claimed.catch((error: Error) => {
  // Wenn die Nachricht nicht mit "option_not_applied" beginnt, wurde der Prompt nicht ausgeführt:
  // starten Sie diese Sitzung stattdessen mit query()
  console.error("Claim failed:", error.message);
});

try {
  for await (const message of claimedQuery) {
    console.log(message);
  }
} catch (error) {
  // Nach einem abgelehnten Claim wirft die beanspruchte Query einen Fehler, sobald sie das Fehlerergebnis ausgegeben hat
  console.error(`Session ended with an error: ${error}`);
}

​

tool()

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
): SdkMcpToolDefinition<Schema>;

​

Parameter

​

ToolAnnotations

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

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

​

createSdkMcpServer()

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  instructions?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
  alwaysLoad?: boolean;
  timeout?: number;
}): McpSdkServerConfigWithInstance;

​

Parameter

​

listSessions()

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

​

Parameter

​

Rückgabetyp: SDKSessionInfo

​

Beispiel

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

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

​

getSessionMessages()

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

​

Parameter

​

Rückgabetyp: SessionMessage

​

Beispiel

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

​

getSessionInfo()

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

​

Parameter

​

renameSession()

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

​

Parameter

​

tagSession()

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

​

Parameter

​

forkSession()

function forkSession(
  sessionId: string,
  options?: ForkSessionOptions
): Promise<ForkSessionResult>;

​

Parameter

• sessionId keine UUID ist
• die Sitzung nicht gefunden werden kann oder keine Nachrichten enthält
• upToMessageId mit keiner Nachricht im Transkript übereinstimmt

​

resolveSettings()

• policyHelper: resolveSettings() liest MDM-Quellen, einschließlich macOS plist und Windows HKLM/HKCU, führt aber nicht den vom Administrator konfigurierten policyHelper-Subprozess aus.
• Server-verwaltete Einstellungen: resolveSettings() ruft server-verwaltete Einstellungen nicht ab. Übergeben Sie sie als options.serverManagedSettings, um sie einzubeziehen.
• defaultMode: Der Snapshot gibt permissions.defaultMode unverändert aus jeder Ebene zurück, sodass er die Werte 'auto' und 'bypassPermissions' aus Projekt- und lokalen Einstellungen enthalten kann, die eine Live-Sitzung ignoriert.

function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;

​

Parameter

​

Rückgabetyp: ResolvedSettings

​

Beispiel

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

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

​

Typen

​

Options

​

Langsame oder hängende API-Antworten behandeln

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

const result = query({
  prompt: "Analyze this code",
  options: {
    env: {
      ...process.env,
      API_TIMEOUT_MS: "120000",
      CLAUDE_CODE_MAX_RETRIES: "2",
      CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",
    },
  },
});

• API_TIMEOUT_MS: Timeout pro Anfrage im Anthropic-Client, in Millisekunden. Standard 600000. Gilt für die Hauptschleife und alle Subagenten.
• CLAUDE_CODE_MAX_RETRIES: maximale Anzahl an API-Wiederholungsversuchen. Standard 10, begrenzt auf 15. Jeder Wiederholungsversuch erhält ein eigenes API_TIMEOUT_MS-Zeitfenster. Für unbeaufsichtigte Läufe, die längere Ausfälle überstehen müssen, setzen Sie CLAUDE_CODE_RETRY_WATCHDOG=1: Damit werden vorübergehende Kapazitätsfehler unbegrenzt erneut versucht, und ab Claude Code v2.1.199 wird der Standardwert für andere vorübergehende Fehler auf 300 angehoben und die Obergrenze dieser Variable aufgehoben.
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: Watchdog für hängende Subagenten. Solange der Stream-Watchdog aktiv ist, beträgt der Standard CLAUDE_STREAM_IDLE_TIMEOUT_MS plus 5 Minuten, was 600000 ergibt, sofern Sie diese Variable nicht erhöhen. Bei ausgeschaltetem Stream-Watchdog beträgt der Standard 600000. Vor v2.1.257 betrug der Standard immer 600000. Der Timer wird bei jedem Stream-Ereignis zurückgesetzt. Bei einem Hänger bricht Claude Code den Subagenten ab und meldet dies an den übergeordneten Agenten. Bei einem Hintergrund-Subagenten markiert es außerdem die Aufgabe als fehlgeschlagen und hängt ein eventuelles Teilergebnis an.
• CLAUDE_ENABLE_STREAM_WATCHDOG mit CLAUDE_STREAM_IDLE_TIMEOUT_MS: Stream-Watchdog, der die Anfrage abbricht, wenn die Header eingetroffen sind, der Response-Body aber nicht mehr gestreamt wird. Der Watchdog ist für alle Anbieter standardmäßig aktiv; setzen Sie CLAUDE_ENABLE_STREAM_WATCHDOG=0, um ihn zu deaktivieren. CLAUDE_STREAM_IDLE_TIMEOUT_MS hat den Standardwert 300000 und wird auf dieses Minimum begrenzt. Was Claude Code nach dem Abbruch tut, abhängig davon, wie weit die Antwort fortgeschritten war, beschreibt Automatische Wiederholungsversuche. Während der Watchdog eine Antwort abwartet, die ein Gateway hinter ANTHROPIC_BASE_URL mit Keep-alive-Pings offen hält, erhält ein Host, der includePartialMessages setzt, weiterhin ping-Stream-Ereignisse. Werten Sie diese Frames daher als Lebenszeichen, anstatt die Sitzung bei Stille per Timeout zu beenden. Vor v2.1.257 endeten die Frames 5 Minuten nach dem letzten echten Stream-Ereignis.

​

Query-Objekt

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<SDKControlInterruptResponse | undefined>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  applyFlagSettings(settings: {
    [K in keyof Settings]?: K extends 'effortLevel'
      ? 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
      : Settings[K] | null;
  }): Promise<void>;
  updateSettings(
    source: 'localSettings' | 'userSettings',
    settings: Record<string, unknown>,
  ): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  getContextUsage(opts?: {
    detail?: 'summary' | 'full';
  }): Promise<SDKControlGetContextUsageResponse>;
  readFile(
    path: string,
    options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }
  ): Promise<SDKControlReadFileResponse | null>;
  reloadPlugins(options?: {
    holdOnCacheImpact?: boolean;
  }): Promise<SDKControlReloadPluginsResponse>;
  reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
  reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

​

Methoden

​

applyFlagSettings()

• Wirksam ab dem nächsten Turn: effortLevel, ultracode, permissions, hooks, skillOverrides, fastMode, agent. Ein Wechsel von agent wendet ab dem nächsten Turn auch die Modellüberschreibung und die Hooks dieses Agenten an. Sein System-Prompt wirkt ab dem nächsten Turn oder, in einer Sitzung, die einen aufgezeichneten System-Prompt wiederverwendet, sobald die Sitzung komprimiert wird.
• Wirksam während des aktuellen Turns: model. Wenn Sie model wechseln, während Claude an einem Turn arbeitet, wird die Antwort, die Claude gerade erzeugt, mit dem alten Modell abgeschlossen, und der Rest des Turns verwendet ab dem nächsten Aufruf, den Claude Code an das Modell richtet, das neue Modell. Subagenten behalten ihr eigenes Modell. Vor v2.1.212 wartete ein Wechsel mitten im Turn auf den nächsten Turn.
• Keine Wirkung während der Sitzung: die Optionen für den System-Prompt. Diese werden einmalig beim Start aufgelöst, sodass die laufende Sitzung den ursprünglichen Wert behält, obwohl der Aufruf erfolgreich ist. Um sie zu ändern, starten Sie eine neue Sitzung.

• effortLevel: null setzt die Sitzung auf die Standard-Effort-Stufe des Modells zurück, nicht auf die Option effort von query() oder ein effortLevel aus einer Einstellungsdatei.
• agent: null führt den Hauptthread ab dem nächsten Turn ohne Agenten aus, anstatt die Option agent von query() oder ein agent aus einer Einstellungsdatei wiederherzustellen. Wenn der gelöschte Agent ein eigenes Modell angewendet hatte, kehrt die Sitzung zu dem Modell zurück, das sie beim Start aufgelöst hat.
• ultracode: null schaltet Ultracode aus, wie false, anstatt einen ultracode-Wert aus einer Einstellungsdatei wiederherzustellen. Die Sitzung behält ihre aktuelle Effort-Stufe; übergeben Sie daher effortLevel im selben Aufruf, um sie zu ändern.

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

const q = query({ prompt: messageStream });

// Override the model for the rest of the session
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// Later: clear the override; the model resets to Claude Code's default
await q.applyFlagSettings({ model: null });

​

updateSettings()

• "localSettings": akzeptiert outputStyle und führt ihn in die lokale Einstellungsdatei des Projekts, .claude/settings.local.json, zusammen. Der neue Stil wird bei der nächsten Anfrage der Sitzung wirksam.
• "userSettings": akzeptiert effortLevel und speichert ihn als Standard-Effort-Stufe für das aktuelle Modell der Sitzung unter modelSettings in Ihrer Benutzereinstellungsdatei. Die Übergabe von max schreibt nichts, da max nur für die Sitzung gilt. Die laufende Sitzung behält in jedem Fall ihre aktuelle Effort-Stufe; rufen Sie daher applyFlagSettings() auf, wenn Sie diese ebenfalls ändern möchten. Diese Quelle erfordert TypeScript SDK v0.3.277 oder höher, das Claude Code v2.1.277 bündelt.

​

toggleMcpServer()

• Ein stdio-, SSE- oder HTTP-Server, den Sie während der Sitzung mit setMcpServers() hinzugefügt haben: Das Entfernen seiner Tools erfordert Claude Code v2.1.285 oder höher.
• Ein prozessinterner Server, den Sie mit createSdkMcpServer() erstellt haben, unabhängig davon, ob Sie ihn in mcpServers oder mit setMcpServers() übergeben haben: Das Trennen der Verbindung und das Entfernen seiner Tools erfordert Claude Code v2.1.286 oder höher. Das Deaktivieren eines solchen Servers lässt außerdem seine noch laufenden Tool-Aufrufe fehlschlagen, sodass Claude für jeden davon sofort ein Fehlerergebnis erhält, ohne darauf zu warten, dass Ihr Handler zurückkehrt.

​

WarmQuery

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

​

Methoden

​

SpareProcess

interface SpareProcess extends AsyncDisposable {
  claim(params: {
    prompt: string | AsyncIterable<SDKUserMessage>;
    options: ClaimOptions;
  }): Query;
  readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;
  readonly exited: Promise<void>;
  close(): void;
}

​

Member

​

SDKControlInitializeResponse

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
  fast_mode_disabled_reason?: FastModeDisabledReason;
  hooks_applied?: boolean;
  sdk_mcp_manifests_parked?: Record<
    string,
    | "parked"
    | "already_connected"
    | "protocol_version_mismatch"
    | "malformed"
    | "not_honoured"
  >;
  claude_code_version?: string;
};

• true: Claude Code hat die Hooks registriert. Die erste Initialisierung einer Sitzung gibt diesen Wert zurück. Eine wiederholte Initialisierung, die über stdin der CLI gesendet wird, gibt ebenfalls true zurück. In diesem Fall ersetzen die Hooks der neuen Anfrage die zuvor registrierten Hooks.
• false: Claude Code hat die Hooks ignoriert. Eine wiederholte Initialisierung, die an eine Remote-Sitzung gesendet wird, gibt diesen Wert zurück, sodass ein zweiter Client, der einer Sitzung beitritt, die vom ersten Client registrierten Hooks nicht ersetzen kann.

• Das Feld erfordert Agent SDK v0.3.296 oder höher, das Claude Code v2.1.296 bündelt.
• Wenn das Feld undefined ist und Sie pathToClaudeCodeExecutable setzen, verweisen Sie damit auf Claude Code v2.1.296 oder höher.

​

SDKControlInterruptResponse

type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};

• Es erscheinen nur Nachrichten, die mit einer UUID in die Warteschlange gestellt wurden. Ein leeres Array bedeutet nicht, dass nichts anderes ausgeführt wird.
• Es werden nur Nachrichten des Hauptthreads aufgelistet. An einen Subagenten adressierte Nachrichten sind nicht erfasst.
• Die Liste kann UUIDs enthalten, die Ihr Client nie gesendet hat, etwa Auslöser geplanter Aufgaben. Ignorieren Sie UUIDs, die Sie nicht kennen, anstatt sie als Fehler zu behandeln.

​

SDKControlGetContextUsageResponse

• 'full': der Standard. Claude Code zählt jede Kategorie mit API-Anfragen zur Token-Zählung. Diese Anfragen erscheinen nicht im Nachrichtenstream, sodass eine Kostenverfolgung, die den Stream liest, sie nicht sieht. Auf der Anthropic API wird die Token-Zählung nicht berechnet.
• 'summary': Übergeben Sie { detail: 'summary' }, um stattdessen eine Antwort auf Basis der Nutzung der letzten Antwort und lokaler Schätzungen zu erhalten. Es werden keine Anfragen zur Token-Zählung gesendet, und die Zahlen pro Kategorie sind Näherungswerte.

type SDKControlGetContextUsageResponse = {
  categories: {
    name: string;
    tokens: number;
    color: string;
    isDeferred?: boolean;
    kind: "used" | "free" | "buffer" | "deferred";
  }[];
  totalTokens: number;
  maxTokens: number;
  rawMaxTokens: number;
  percentage: number;
  gridRows: {
    color: string;
    isFilled: boolean;
    categoryName: string;
    tokens: number;
    percentage: number;
    squareFullness: number;
  }[][];
  model: string;
  memoryFiles: {
    path: string;
    type: string;
    tokens: number;
  }[];
  mcpTools: {
    name: string;
    serverName: string;
    tokens: number;
    isLoaded?: boolean;
  }[];
  deferredBuiltinTools?: {
    name: string;
    tokens: number;
    isLoaded: boolean;
  }[];
  systemTools?: {
    name: string;
    tokens: number;
  }[];
  systemPromptSections?: {
    name: string;
    tokens: number;
  }[];
  agents: {
    agentType: string;
    source: string;
    tokens: number;
  }[];
  slashCommands?: {
    totalCommands: number;
    includedCommands: number;
    tokens: number;
  };
  skills?: {
    totalSkills: number;
    includedSkills: number;
    tokens: number;
    skillFrontmatter: {
      name: string;
      source: string;
      tokens: number;
    }[];
  };
  autoCompactThreshold?: number;
  isAutoCompactEnabled: boolean;
  messageBreakdown?: {
    toolCallTokens: number;
    toolResultTokens: number;
    attachmentTokens: number;
    assistantMessageTokens: number;
    userMessageTokens: number;
    redirectedContextTokens: number;
    unattributedTokens: number;
    toolCallsByType: {
      name: string;
      callTokens: number;
      resultTokens: number;
    }[];
    attachmentsByType: {
      name: string;
      tokens: number;
    }[];
  };
  apiUsage: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens: number;
    cache_read_input_tokens: number;
  } | null;
};

• categories enthält die Summen pro Kategorie. Das Feld kind jedes Eintrags klassifiziert die Zeile mit denselben Werten wie SDKContextUsageCategory. Klassifizieren Sie Zeilen anhand dieses Felds statt anhand des Anzeigenamens name. Das Feld erfordert Agent SDK v0.3.268 oder höher.
• mcpTools und agents ordnen Token einzelnen MCP-Tools und Subagenten zu.
• memoryFiles listet jede geladene Memory-Datei mit ihren Kosten auf.
• skills.skillFrontmatter ordnet die Token der Skill-Auflistung jedem enthaltenen Skill zu. Die Zählungen pro Skill messen den Auflistungseintrag jedes Skills so, wie Claude Code ihn tatsächlich sendet; dieser kann kürzer sein als das vollständige Frontmatter des Skills. Vergleichen Sie skills.totalSkills mit skills.includedSkills, um zu sehen, ob jeder gefundene Skill in die Auflistung aufgenommen wurde.

​

SDKControlReadFileResponse

type SDKControlReadFileResponse = {
  contents: string;
  absPath: string;
  truncated?: boolean;
  encoding?: 'base64';
};

​

Was readFile() lesen kann

• Eine reguläre Datei in einem der Arbeitsverzeichnisse der Sitzung, etwa cwd und additionalDirectories
• Einige von Claude Codes eigenen Dateien für die Sitzung, etwa Tool-Ergebnisse

​

SDKControlReloadPluginsResponse

type SDKControlReloadPluginsResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  plugins: {
    name: string;
    path: string;
    source?: string;
    version?: string;
  }[];
  mcpServers: McpServerStatus[];
  error_count: number;
  held?: boolean;
  cache_impact?: {
    mcp_servers_added: string[];
    mcp_servers_removed: string[];
    lsp_tool_change: ("adds" | "may-add" | "removes" | "may-remove") | null;
  };
};

• commands, agents und mcpServers: die Befehle, Subagenten und der MCP-Server-Status der Sitzung, in denselben Formen, die supportedCommands(), supportedAgents() und mcpServerStatus() zurückgeben. supportedAgents() gibt weiterhin die bei der Initialisierung erfasste Liste zurück; lesen Sie daher agents hier, um die Menge nach einem Neuladen zu erhalten
• plugins: jedes geladene Plugin mit seinem name und seinem Installationspfad path. version gibt wieder, was das Manifest des Plugins deklariert, und wird vom Plugin-Autor gesteuert; validieren Sie den Wert daher, bevor Sie ihm vertrauen. Er fehlt, wenn das Manifest keinen deklariert
• error_count: die Anzahl der Fehler beim Laden von Plugins

• true: Das Neuladen wurde nicht angewendet, und die Sammlungsfelder beschreiben die Sitzung in ihrem unveränderten Zustand. cache_impact gibt an, was das Anwenden ändern würde. Um trotzdem anzuwenden, rufen Sie reloadPlugins() erneut ohne die Option auf.
• false: Die Prüfung hat keine Auswirkung auf den Cache festgestellt, und das Neuladen wurde angewendet.
• Fehlend: Sie haben die Option nicht übergeben, oder die ausführbare Claude Code-Datei ist älter als v2.1.268 und hat das Neuladen angewendet.

​

SDKControlReloadSkillsResponse

type SDKControlReloadSkillsResponse = {
  skills: SlashCommand[];
};

​

SDKControlReloadOutputStylesResponse

type SDKControlReloadOutputStylesResponse = {
  available_output_styles: string[];
};

​

SDKControlMcpReadResourceResponse

type SDKControlMcpReadResourceResponse = {
  contents: {
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
    _meta?: Record<string, unknown>;
  }[];
};

​

AgentDefinition

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  autoCompactWindow?: number;
  background?: boolean;
  omitClaudeMd?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

​

AgentMcpServerSpec

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

​

SettingSource

type SettingSource = "user" | "project" | "local";

​

Standardverhalten

​

Warum settingSources verwenden

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

// Do not load user, project, or local settings from disk
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

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

// Load only project settings, ignore user and local
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Only .claude/settings.json
  }
});

​

Vorrang von Einstellungen

1. Lokale Einstellungen (.claude/settings.local.json)
2. Projekteinstellungen (.claude/settings.json)
3. Benutzereinstellungen (~/.claude/settings.json)

​

PermissionMode

type PermissionMode =
  | "default" // Standard permission behavior
  | "acceptEdits" // Auto-accept file edits
  | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
  | "plan" // Planning mode - explore without editing
  | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
  | "auto"; // A model classifier reviews actions such as shell commands and network requests

​

CanUseTool

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    mcpServer?: { name: string; source: string };
    decisionReason?: string;
    defaultToNo?: boolean;
    suppressAlwaysAllowRule?: boolean;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

​

PermissionResult

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

​

ToolConfig

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

​

McpServerConfig

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

​

McpStdioServerConfig

type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

​

McpSSEServerConfig

type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};

​

McpHttpServerConfig

type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};

​

McpSdkServerConfigWithInstance

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  timeout?: number;
  instance: McpServer;
};

​

McpClaudeAIProxyServerConfig

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

​

SdkPluginConfig

type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};

plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];

​

Nachrichtentypen

​

SDKMessage

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKTaskUpdatedMessage
  | SDKBackgroundTasksChangedMessage
  | SDKThinkingTokensMessage
  | SDKSessionStateChangedMessage
  | SDKWorkerShuttingDownMessage
  | SDKCommandsChangedMessage
  | SDKNotificationMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKMemoryRecallMessage
  | SDKRateLimitEvent
  | SDKElicitationCompleteMessage
  | SDKPermissionDeniedMessage
  | SDKPromptSuggestionMessage
  | SDKAPIRetryMessage
  | SDKMirrorErrorMessage
  | SDKInformationalMessage
  | SDKConversationResetMessage;

​

SDKAssistantMessage

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // From Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
  aborted?: true;
  agent_id?: string;
  timestamp?: string;
  context_usage?: SDKContextUsage;
  usage_report?: SDKUsageReport;
  user_message_uuid?: string;
  user_message_uuids?: string[];
  resume_reason?: string;
};

• 'model_not_found': Das ausgewählte Modell existiert nicht oder ist nicht für Ihr Konto oder Ihre Bereitstellung verfügbar
• 'overloaded': Die API hat einen 529-Fehler zurückgegeben, weil der Server ausgelastet ist, im Gegensatz zu 'rate_limit', das ein 429-Fehler gegen Ihr Kontingent ist
• 'account_on_hold': Ihr Konto ist gesperrt
• 'cloud_credential_error': Claude Code konnte keine verwendbaren AWS- oder Google Cloud-Anmeldedaten auf der Maschine, auf der es läuft, abrufen, daher erreichte keine Anfrage den Cloud-Anbieter. Die übliche Ursache ist eine Cloud-Anmeldung, die abgelaufen ist oder auf dieser Maschine nie abgeschlossen wurde, obwohl ein kurzzeitig unerreichbarer Anmeldedatendienst denselben Wert meldet. Siehe AWS- oder Google Cloud-Anmeldedaten konnten nicht geladen werden. Erfordert TypeScript Agent SDK v0.3.267 oder später, das Claude Code v2.1.267 bündelt

• Die Sitzung authentifiziert sich mit claude.ai-Anmeldedaten
• Die Anmeldedaten weisen einen bekannten Plantyp aus oder tragen den Scope user:profile
• Das Konto nutzt keine nutzungsbasierte Abrechnung

​

SDKUserMessage

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  agent_id?: string;
  message: MessageParam; // From Anthropic SDK
  pasted_content?: MessageParam["content"][];
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  priority?: "now" | "next" | "later";
  origin?: SDKMessageOrigin;
  inline_pastes?: string[];
};

• pasted_content: Wenn die Einträge zusammen mit den darin enthaltenen Inhaltsblöcken mehr als 1.000 ergeben, ignoriert Claude Code das gesamte Feld.
• inline_pastes: Claude Code verwendet die ersten 100 nicht leeren Einträge und ignoriert den Rest.

• shouldQuery: Setzen Sie es auf false, um die Nachricht zum Transkript hinzuzufügen, ohne einen Assistenten-Turn auszulösen. Die Nachricht wird gehalten und in die nächste Benutzer-Nachricht zusammengeführt, die einen Turn auslöst. Verwenden Sie dies, um Kontext einzufügen, z. B. die Ausgabe eines Befehls, den Sie außerhalb des Bands ausgeführt haben, ohne einen Modell-Aufruf dafür auszugeben.
• client_composed: Setzen Sie es auf true, um Claude Code die Nachricht so zu liefern, wie sie geschrieben ist. Claude Code erweitert dann nicht @path oder @server:resource-Erwähnungen und führt keinen Text aus, der mit / beginnt, als Befehl aus. Während die verbatimPrompts-Option aktiv ist, setzt das SDK das Feld auf jede Nachricht. Erfordert TypeScript Agent SDK v0.3.280 oder später und Claude Code v2.1.248 oder später.
• priority: steuert, wann eine Nachricht, die Sie während eines laufenden Turns senden, Claude erreicht:
  • 'next' oder kein priority-Feld: Claude liest die Nachricht im selben Turn, sobald die laufenden Tool-Aufrufe abgeschlossen sind. Endet der Turn vorher, startet die Nachricht den nächsten Turn.
  • 'later': Claude Code hält die Nachricht zurück, bis der Turn endet, und sendet sie als neuen Turn.
  • 'now' mit origin: { kind: "human" }: Ab Claude Code v2.1.286 wird Arbeit, die im Hintergrund fortgesetzt werden kann, dorthin verschoben, und Claude liest die Nachricht im selben Turn. Zur verschiebbaren Arbeit gehören Shell-Befehle, Subagenten und MCP-Tool-Aufrufe. Ab v2.1.287 gehören auch WebFetch- und WebSearch-Aufrufe dazu. Wenn Claude nur eine Antwort schreibt oder die laufende Arbeit nicht verschoben werden kann, unterbricht Claude Code stattdessen den Turn, und Claude liest die Nachricht als Nächstes.
  • 'now' ohne diesen Origin: Claude Code unterbricht den Turn, und Claude liest die Nachricht als Nächstes.

const message: SDKUserMessage = {
  type: "user",
  message: { role: "user", content: "Skip the integration tests and summarize what you have so far" },
  parent_tool_use_id: null,
  priority: "now",
  origin: { kind: "human" },
};

• Das Agent-Tool: tool_use_result ist AgentOutput. Rendern Sie daraus, statt den tool_result-Text zu parsen. Der content eines completed-Ergebnisses enthält den Bericht des Subagenten oder, bei einem Subagenten, dessen Bericht über einen SubagentHandback-Tool-Aufruf läuft, anstelle des Berichts einen kurzen Hinweis auf diese Übergabe. Im Auto-Modus ab Claude Code v2.1.271 berichtet jeder Subagent, der ein completed-Ergebnis erzeugt, auf diese Weise, sofern er kein Fork ist, und Claude erhält den Bericht als separate Nachricht vom Subagenten.
• Ein WebFetch- oder WebSearch-Aufruf, den Claude Code in den Hintergrund verschoben hat, um eine 'now'-Nachricht zuzustellen: Bei der Benutzernachricht, die das tool_result dieses Aufrufs enthält, ist tool_use_result auf { detachedToolCall: true } gesetzt. Der Aufruf läuft weiter, und Claude erhält sein Ergebnis, sobald er abgeschlossen ist. Es folgt kein zweites tool_result für diese tool_use_id. Wenn Ihre Anwendung also für jeden Tool-Aufruf eine Zeile darstellt, markieren Sie diese Zeile als in den Hintergrund verschoben, wenn diese Nachricht eintrifft. Erfordert Claude Code v2.1.287 oder höher.
• Ein MCP-Tool, dessen Ergebnis resource_link-Blöcke enthält: tool_use_result ist ein Objekt mit einem resourceLinks-Array aus SDKMcpResourceLink-Einträgen. Claude erhält jeden Link als Textzeile im tool_result-Block. Lesen Sie daher resourceLinks, um die vom Server zurückgegebenen Dateien darzustellen, statt diesen Text zu parsen. Claude Code lässt resourceLinks weg, wenn das Ergebnis keine Links enthält, sowie bei Ergebnissen von Subagenten, behält höchstens 50 Links pro Ergebnis und fügt keine weiteren Links hinzu, sobald das Array 64 KiB serialisiertes JSON erreicht. resourceLinks erfordert Agent SDK v0.3.257 oder höher.
• Ein MCP-Tool, das structuredContent zurückgibt: tool_use_result ist ein Objekt, dessen Member structuredContent enthält, was der Server gesendet hat, und dessen Member content den McpOutput-Wert enthält. Ergebnisse von Subagenten enthalten kein structuredContent.
• Ein MCP-Tool, dessen structuredContent zu mehr als 1.048.576 Zeichen JSON serialisiert wird: Claude Code lässt structuredContent in tool_use_result weg und setzt stattdessen structuredContentOmitted: true, damit Ihre Anwendung ein verworfenes Objekt von einem Tool unterscheiden kann, das keines gesendet hat. Die anderen Member wie content und resourceLinks bleiben erhalten, und was Claude erhält, ändert sich nicht. Claude Code ab v2.1.287 wendet diese Obergrenze an. Zwei Arten von Tools verhalten sich anders:
  • Tools von prozessinternen SDK-Servern sind ausgenommen und liefern das Objekt vollständig.
  • Ein Tool, dessen tools/list-Eintrag eine MCP-Apps-ui://-Ressource deklariert, hat ab Claude Code v2.1.295 ein Limit von 8.388.608 Zeichen; Versionen vor v2.1.295 nehmen es aus.

​

SDKUserMessageReplay

type SDKUserMessageReplay = {
  type: "user";
  uuid: UUID;
  session_id: string;
  message: MessageParam;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
  isReplay: true;
};