Agent SDK reference - TypeScript

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

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);
}

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

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

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

// Bayar biaya startup di muka
const warm = await startup({ options: { maxTurns: 3 } });

// Nanti, ketika prompt siap, ini langsung
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

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

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 } }
);

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

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

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})`);
}

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

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}`);
  }
}

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

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

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

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

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}`);

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",
    },
  },
});

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]?: Settings[K] | null }): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

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

// Override model untuk sisa sesi
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// Nanti: hapus override dan kembali ke pengaturan preseden lebih rendah
await q.applyFlagSettings({ model: null });

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

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
};

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

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

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

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

// Jangan muat pengaturan pengguna, proyek, atau lokal dari disk
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ["user", "project", "local"] // Muat semua pengaturan
  }
});

// Muat hanya pengaturan proyek, abaikan pengguna dan lokal
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Hanya .claude/settings.json
  }
});

// Pastikan perilaku konsisten di CI dengan mengecualikan pengaturan lokal
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // Hanya pengaturan bersama tim
    permissionMode: "bypassPermissions"
  }
});

// Tentukan semuanya secara terprogram.
// Lewatkan [] untuk opt out dari sumber pengaturan filesystem.
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

// Muat pengaturan proyek untuk menyertakan file CLAUDE.md
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Gunakan prompt sistem Claude Code
    },
    settingSources: ["project"], // Memuat CLAUDE.md dari direktori proyek
    allowedTools: ["Read", "Write", "Edit"]
  }
});

type PermissionMode =
  | "default" // Perilaku izin standar
  | "acceptEdits" // Auto-accept edit file
  | "bypassPermissions" // Bypass pemeriksaan izin; aturan ask eksplisit masih prompt
  | "plan" // Mode perencanaan - jelajahi tanpa mengedit
  | "dontAsk" // Jangan prompt untuk izin, tolak jika tidak pre-approved
  | "auto"; // Gunakan classifier model untuk approve atau deny setiap tool call

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

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

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

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

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

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

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

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

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

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

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

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;

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
};

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  message: MessageParam; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
};

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

type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      api_error_status?: number | null;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      ttft_ms?: number;
      ttft_stream_ms?: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      origin?: SDKMessageOrigin;
    }
  | {
      type: "result";
      subtype:
        | "error_max_turns"
        | "error_during_execution"
        | "error_max_budget_usd"
        | "error_max_structured_output_retries";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      errors: string[];
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      origin?: SDKMessageOrigin;
    };

type SDKSystemMessage = {
  type: "system";
  subtype: "init";
  uuid: UUID;
  session_id: string;
  agents?: string[];
  apiKeySource: ApiKeySource;
  betas?: string[];
  claude_code_version: string;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
  skills: string[];
  plugins: { name: string; path: string }[];
  capabilities?: string[];
};

type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
  ttft_ms?: number; // Waktu ke token pertama dalam ms, hadir hanya pada event message_start
};

type SDKCompactBoundaryMessage = {
  type: "system";
  subtype: "compact_boundary";
  uuid: UUID;
  session_id: string;
  compact_metadata: {
    trigger: "manual" | "auto";
    pre_tokens: number;
  };
};

type SDKStatusMessage = {
  type: "system";
  subtype: "status";
  status: string;
  uuid: UUID;
  session_id: string;
};

type SDKLocalCommandOutputMessage = {
  type: "system";
  subtype: "local_command_output";
  command: string;
  output: string;
  uuid: UUID;
  session_id: string;
};

type SDKHookStartedMessage = {
  type: "system";
  subtype: "hook_started";
  hook_name: string;
  uuid: UUID;
  session_id: string;
};

type SDKHookProgressMessage = {
  type: "system";
  subtype: "hook_progress";
  hook_name: string;
  progress: string;
  uuid: UUID;
  session_id: string;
};

type SDKHookResponseMessage = {
  type: "system";
  subtype: "hook_response";
  hook_name: string;
  response: unknown;
  uuid: UUID;
  session_id: string;
};

type SDKToolProgressMessage = {
  type: "system";
  subtype: "tool_progress";
  tool_name: string;
  progress: string;
  uuid: UUID;
  session_id: string;
};

type SDKAuthStatusMessage = {
  type: "system";
  subtype: "auth_status";
  status: string;
  uuid: UUID;
  session_id: string;
};

type SDKTaskNotificationMessage = {
  type: "system";
  subtype: "task_notification";
  task_id: string;
  message: string;
  uuid: UUID;
  session_id: string;
};

type SDKTaskStartedMessage = {
  type: "system";
  subtype: "task_started";
  task_id: string;
  uuid: UUID;
  session_id: string;
};

type SDKTaskProgressMessage = {
  type: "system";
  subtype: "task_progress";
  task_id: string;
  progress: string;
  uuid: UUID;
  session_id: string;
};

type SDKTaskUpdatedMessage = {
  type: "system";
  subtype: "task_updated";
  task_id: string;
  update: unknown;
  uuid: UUID;
  session_id: string;
};

type SDKBackgroundTasksChangedMessage = {
  type: "system";
  subtype: "background_tasks_changed";
  tasks: string[];
  uuid: UUID;
  session_id: string;
};

type SDKThinkingTokensMessage = {
  type: "system";
  subtype: "thinking_tokens";
  tokens: number;
  uuid: UUID;
  session_id: string;
};

type SDKSessionStateChangedMessage = {
  type: "system";
  subtype: "session_state_changed";
  state: string;
  uuid: UUID;
  session_id: string;
};

type SDKWorkerShuttingDownMessage = {
  type: "system";
  subtype: "worker_shutting_down";
  reason: string;
  uuid: UUID;
  session_id: string;
};

type SDKCommandsChangedMessage = {
  type: "system";
  subtype: "commands_changed";
  commands: string[];
  uuid: UUID;
  session_id: string;
};

type SDKNotificationMessage = {
  type: "system";
  subtype: "notification";
  message: string;
  uuid: UUID;
  session_id: string;
};

type SDKFilesPersistedEvent = {
  type: "system";
  subtype: "files_persisted";
  files: string[];
  uuid: UUID;
  session_id: string;
};

type SDKToolUseSummaryMessage = {
  type: "system";
  subtype: "tool_use_summary";
  summary: string;
  uuid: UUID;
  session_id: string;
};

type SDKMemoryRecallMessage = {
  type: "system";
  subtype: "memory_recall";
  memory: string;
  uuid: UUID;
  session_id: string;
};

type SDKRateLimitEvent = {
  type: "system";
  subtype: "rate_limit";
  limit: number;
  uuid: UUID;
  session_id: string;
};

type SDKElicitationCompleteMessage = {
  type: "system";
  subtype: "elicitation_complete";
  uuid: UUID;
  session_id: string;
};

type SDKPermissionDeniedMessage = {
  type: "system";
  subtype: "permission_denied";
  tool_name: string;
  tool_use_id: string;
  agent_id?: string;
  decision_reason_type?: string;
  decision_reason?: string;
  message: string;
  uuid: UUID;
  session_id: string;
};