Referensi Agent SDK - TypeScript

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

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

function tool<Schema extends ZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
): SdkMcpToolDefinition<Schema>

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

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
}

type AgentDefinition = {
  description: string;
  tools?: string[];
  prompt: string;
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
}

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

// Muat semua pengaturan seperti yang dilakukan SDK v0.0.x
const result = query({
  prompt: "Analisis kode ini",
  options: {
    settingSources: ['user', 'project', 'local']  // Muat semua pengaturan
  }
});

// Muat hanya pengaturan proyek, abaikan user dan local
const result = query({
  prompt: "Jalankan pemeriksaan CI",
  options: {
    settingSources: ['project']  // Hanya .claude/settings.json
  }
});

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

// Definisikan semuanya secara programatis (perilaku default)
// Tidak ada dependensi filesystem - settingSources default ke []
const result = query({
  prompt: "Review PR ini",
  options: {
    // settingSources: [] adalah default, tidak perlu dispesifikasi
    agents: { /* ... */ },
    mcpServers: { /* ... */ },
    allowedTools: ['Read', 'Grep', 'Glob']
  }
});

type PermissionMode =
  | 'default'           // Perilaku izin standar
  | 'acceptEdits'       // Otomatis menerima edit file
  | 'bypassPermissions' // Lewati semua pemeriksaan izin
  | 'plan'              // Mode perencanaan - tidak ada eksekusi

type CanUseTool = (
  toolName: string,
  input: ToolInput,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
  }
) => Promise<PermissionResult>;

type PermissionResult = 
  | {
      behavior: 'allow';
      updatedInput: ToolInput;
      updatedPermissions?: PermissionUpdate[];
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
    }

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 SDKMessage = 
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage;

type SDKAssistantMessage = {
  type: 'assistant';
  uuid: UUID;
  session_id: string;
  message: APIAssistantMessage; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
}

type SDKUserMessage = {
  type: 'user';
  uuid?: UUID;
  session_id: string;
  message: APIUserMessage; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
}

type SDKUserMessageReplay = {
  type: 'user';
  uuid: UUID;
  session_id: string;
  message: APIUserMessage;
  parent_tool_use_id: string | null;
}

type SDKResultMessage = 
  | {
      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: NonNullableUsage;
      permission_denials: SDKPermissionDenial[];
    }
  | {
      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: NonNullableUsage;
      permission_denials: SDKPermissionDenial[];
    }

type SDKSystemMessage = {
  type: 'system';
  subtype: 'init';
  uuid: UUID;
  session_id: string;
  apiKeySource: ApiKeySource;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
}

type SDKPartialAssistantMessage = {
  type: 'stream_event';
  event: RawMessageStreamEvent; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
}

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

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: ToolInput;
}

type HookEvent = 
  | 'PreToolUse'
  | 'PostToolUse'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'SubagentStop'
  | 'PreCompact';

type HookCallback = (
  input: HookInput, // Union dari semua tipe input hook
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
}

type HookInput = 
  | PreToolUseHookInput
  | PostToolUseHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStopHookInput
  | PreCompactHookInput;

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
}

type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PreToolUse';
  tool_name: string;
  tool_input: ToolInput;
}

type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PostToolUse';
  tool_name: string;
  tool_input: ToolInput;
  tool_response: ToolOutput;
}

type NotificationHookInput = BaseHookInput & {
  hook_event_name: 'Notification';
  message: string;
  title?: string;
}

type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: 'UserPromptSubmit';
  prompt: string;
}

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: 'SessionStart';
  source: 'startup' | 'resume' | 'clear' | 'compact';
}

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: 'SessionEnd';
  reason: 'clear' | 'logout' | 'prompt_input_exit' | 'other';
}

type StopHookInput = BaseHookInput & {
  hook_event_name: 'Stop';
  stop_hook_active: boolean;
}

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: 'SubagentStop';
  stop_hook_active: boolean;
}

type PreCompactHookInput = BaseHookInput & {
  hook_event_name: 'PreCompact';
  trigger: 'manual' | 'auto';
  custom_instructions: string | null;
}

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
}

type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: 'PreToolUse';
        permissionDecision?: 'allow' | 'deny' | 'ask';
        permissionDecisionReason?: string;
      }
    | {
        hookEventName: 'UserPromptSubmit';
        additionalContext?: string;
      }
    | {
        hookEventName: 'SessionStart';
        additionalContext?: string;
      }
    | {
        hookEventName: 'PostToolUse';
        additionalContext?: string;
      };
}

type ToolInput = 
  | AgentInput
  | BashInput
  | BashOutputInput
  | FileEditInput
  | FileMultiEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | KillShellInput
  | NotebookEditInput
  | WebFetchInput
  | WebSearchInput
  | TodoWriteInput
  | ExitPlanModeInput
  | ListMcpResourcesInput
  | ReadMcpResourceInput;

interface AgentInput {
  /**
   * Deskripsi singkat (3-5 kata) dari tugas
   */
  description: string;
  /**
   * Tugas untuk dilakukan agen
   */
  prompt: string;
  /**
   * Jenis agen khusus yang digunakan untuk tugas ini
   */
  subagent_type: string;
}

interface BashInput {
  /**
   * Perintah yang akan dieksekusi
   */
  command: string;
  /**
   * Timeout opsional dalam milidetik (maks 600000)
   */
  timeout?: number;
  /**
   * Deskripsi yang jelas dan ringkas tentang apa yang dilakukan perintah ini dalam 5-10 kata
   */
  description?: string;
  /**
   * Set ke true untuk menjalankan perintah ini di latar belakang
   */
  run_in_background?: boolean;
}

interface BashOutputInput {
  /**
   * ID shell latar belakang untuk mengambil output
   */
  bash_id: string;
  /**
   * Regex opsional untuk memfilter baris output
   */
  filter?: string;
}

interface FileEditInput {
  /**
   * Path absolut ke file yang akan dimodifikasi
   */
  file_path: string;
  /**
   * Teks yang akan diganti
   */
  old_string: string;
  /**
   * Teks pengganti (harus berbeda dari old_string)
   */
  new_string: string;
  /**
   * Ganti semua kemunculan old_string (default false)
   */
  replace_all?: boolean;
}

interface FileMultiEditInput {
  /**
   * Path absolut ke file yang akan dimodifikasi
   */
  file_path: string;
  /**
   * Array operasi edit yang dilakukan secara berurutan
   */
  edits: Array<{
    /**
     * Teks yang akan diganti
     */
    old_string: string;
    /**
     * Teks pengganti
     */
    new_string: string;
    /**
     * Ganti semua kemunculan (default false)
     */
    replace_all?: boolean;
  }>;
}

interface FileReadInput {
  /**
   * Path absolut ke file yang akan dibaca
   */
  file_path: string;
  /**
   * Nomor baris untuk mulai membaca
   */
  offset?: number;
  /**
   * Jumlah baris yang akan dibaca
   */
  limit?: number;
}

interface FileWriteInput {
  /**
   * Path absolut ke file yang akan ditulis
   */
  file_path: string;
  /**
   * Konten yang akan ditulis ke file
   */
  content: string;
}

interface GlobInput {
  /**
   * Pola glob untuk mencocokkan file
   */
  pattern: string;
  /**
   * Direktori untuk dicari (default ke cwd)
   */
  path?: string;
}

interface GrepInput {
  /**
   * Pola regular expression untuk dicari
   */
  pattern: string;
  /**
   * File atau direktori untuk dicari (default ke cwd)
   */
  path?: string;
  /**
   * Pola glob untuk memfilter file (mis. "*.js")
   */
  glob?: string;
  /**
   * Jenis file untuk dicari (mis. "js", "py", "rust")
   */
  type?: string;
  /**
   * Mode output: "content", "files_with_matches", atau "count"
   */
  output_mode?: 'content' | 'files_with_matches' | 'count';
  /**
   * Pencarian tidak sensitif huruf besar-kecil
   */
  '-i'?: boolean;
  /**
   * Tampilkan nomor baris (untuk mode content)
   */
  '-n'?: boolean;
  /**
   * Baris yang ditampilkan sebelum setiap kecocokan
   */
  '-B'?: number;
  /**
   * Baris yang ditampilkan setelah setiap kecocokan
   */
  '-A'?: number;
  /**
   * Baris yang ditampilkan sebelum dan setelah setiap kecocokan
   */
  '-C'?: number;
  /**
   * Batasi output ke N baris/entri pertama
   */
  head_limit?: number;
  /**
   * Aktifkan mode multiline
   */
  multiline?: boolean;
}

interface KillShellInput {
  /**
   * ID shell latar belakang yang akan dibunuh
   */
  shell_id: string;
}

interface NotebookEditInput {
  /**
   * Path absolut ke file notebook Jupyter
   */
  notebook_path: string;
  /**
   * ID sel yang akan diedit
   */
  cell_id?: string;
  /**
   * Sumber baru untuk sel
   */
  new_source: string;
  /**
   * Jenis sel (code atau markdown)
   */
  cell_type?: 'code' | 'markdown';
  /**
   * Jenis edit (replace, insert, delete)
   */
  edit_mode?: 'replace' | 'insert' | 'delete';
}

interface WebFetchInput {
  /**
   * URL untuk mengambil konten
   */
  url: string;
  /**
   * Prompt untuk dijalankan pada konten yang diambil
   */
  prompt: string;
}

interface WebSearchInput {
  /**
   * Query pencarian yang digunakan
   */
  query: string;
  /**
   * Hanya sertakan hasil dari domain ini
   */
  allowed_domains?: string[];
  /**
   * Jangan pernah sertakan hasil dari domain ini
   */
  blocked_domains?: string[];
}

interface TodoWriteInput {
  /**
   * Daftar todo yang diperbarui
   */
  todos: Array<{
    /**
     * Deskripsi tugas
     */
    content: string;
    /**
     * Status tugas
     */
    status: 'pending' | 'in_progress' | 'completed';
    /**
     * Bentuk aktif dari deskripsi tugas
     */
    activeForm: string;
  }>;
}

interface ExitPlanModeInput {
  /**
   * Rencana yang akan dijalankan oleh pengguna untuk persetujuan
   */
  plan: string;
}

interface ListMcpResourcesInput {
  /**
   * Nama server opsional untuk memfilter sumber daya
   */
  server?: string;
}

interface ReadMcpResourceInput {
  /**
   * Nama server MCP
   */
  server: string;
  /**
   * URI sumber daya yang akan dibaca
   */
  uri: string;
}

type ToolOutput = 
  | TaskOutput
  | BashOutput
  | BashOutputToolOutput
  | EditOutput
  | MultiEditOutput
  | ReadOutput
  | WriteOutput
  | GlobOutput
  | GrepOutput
  | KillBashOutput
  | NotebookEditOutput
  | WebFetchOutput
  | WebSearchOutput
  | TodoWriteOutput
  | ExitPlanModeOutput
  | ListMcpResourcesOutput
  | ReadMcpResourceOutput;

interface TaskOutput {
  /**
   * Pesan hasil akhir dari subagen
   */
  result: string;
  /**
   * Statistik penggunaan token
   */
  usage?: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens?: number;
    cache_read_input_tokens?: number;
  };
  /**
   * Total biaya dalam USD
   */
  total_cost_usd?: number;
  /**
   * Durasi eksekusi dalam milidetik
   */
  duration_ms?: number;
}

interface BashOutput {
  /**
   * Output stdout dan stderr yang digabungkan
   */
  output: string;
  /**
   * Kode keluar dari perintah
   */
  exitCode: number;
  /**
   * Apakah perintah dibunuh karena timeout
   */
  killed?: boolean;
  /**
   * ID shell untuk proses latar belakang
   */
  shellId?: string;
}

interface BashOutputToolOutput {
  /**
   * Output baru sejak pemeriksaan terakhir
   */
  output: string;
  /**
   * Status shell saat ini
   */
  status: 'running' | 'completed' | 'failed';
  /**
   * Kode keluar (saat selesai)
   */
  exitCode?: number;
}

interface EditOutput {
  /**
   * Pesan konfirmasi
   */
  message: string;
  /**
   * Jumlah penggantian yang dibuat
   */
  replacements: number;
  /**
   * Path file yang diedit
   */
  file_path: string;
}

interface MultiEditOutput {
  /**
   * Pesan sukses
   */
  message: string;
  /**
   * Total jumlah edit yang diterapkan
   */
  edits_applied: number;
  /**
   * Path file yang diedit
   */
  file_path: string;
}

type ReadOutput = 
  | TextFileOutput
  | ImageFileOutput
  | PDFFileOutput
  | NotebookFileOutput;

interface TextFileOutput {
  /**
   * Konten file dengan nomor baris
   */
  content: string;
  /**
   * Total jumlah baris dalam file
   */
  total_lines: number;
  /**
   * Baris yang benar-benar dikembalikan
   */
  lines_returned: number;
}

interface ImageFileOutput {
  /**
   * Data gambar yang dikodekan Base64
   */
  image: string;
  /**
   * Tipe MIME gambar
   */
  mime_type: string;
  /**
   * Ukuran file dalam byte
   */
  file_size: number;
}

interface PDFFileOutput {
  /**
   * Array konten halaman
   */
  pages: Array<{
    page_number: number;
    text?: string;
    images?: Array<{
      image: string;
      mime_type: string;
    }>;
  }>;
  /**
   * Total jumlah halaman
   */
  total_pages: number;
}

interface NotebookFileOutput {
  /**
   * Sel notebook Jupyter
   */
  cells: Array<{
    cell_type: 'code' | 'markdown';
    source: string;
    outputs?: any[];
    execution_count?: number;
  }>;
  /**
   * Metadata notebook
   */
  metadata?: Record<string, any>;
}

interface WriteOutput {
  /**
   * Pesan sukses
   */
  message: string;
  /**
   * Jumlah byte yang ditulis
   */
  bytes_written: number;
  /**
   * Path file yang ditulis
   */
  file_path: string;
}

interface GlobOutput {
  /**
   * Array path file yang cocok
   */
  matches: string[];
  /**
   * Jumlah kecocokan yang ditemukan
   */
  count: number;
  /**
   * Direktori pencarian yang digunakan
   */
  search_path: string;
}

type GrepOutput = 
  | GrepContentOutput
  | GrepFilesOutput
  | GrepCountOutput;

interface GrepContentOutput {
  /**
   * Baris yang cocok dengan konteks
   */
  matches: Array<{
    file: string;
    line_number?: number;
    line: string;
    before_context?: string[];
    after_context?: string[];
  }>;
  /**
   * Total jumlah kecocokan
   */
  total_matches: number;
}

interface GrepFilesOutput {
  /**
   * File yang berisi kecocokan
   */
  files: string[];
  /**
   * Jumlah file dengan kecocokan
   */
  count: number;
}

interface GrepCountOutput {
  /**
   * Jumlah kecocokan per file
   */
  counts: Array<{
    file: string;
    count: number;
  }>;
  /**
   * Total kecocokan di semua file
   */
  total: number;
}

interface KillBashOutput {
  /**
   * Pesan sukses
   */
  message: string;
  /**
   * ID shell yang dibunuh
   */
  shell_id: string;
}

interface NotebookEditOutput {
  /**
   * Pesan sukses
   */
  message: string;
  /**
   * Jenis edit yang dilakukan
   */
  edit_type: 'replaced' | 'inserted' | 'deleted';
  /**
   * ID sel yang terpengaruh
   */
  cell_id?: string;
  /**
   * Total sel dalam notebook setelah edit
   */
  total_cells: number;
}

interface WebFetchOutput {
  /**
   * Respons model AI terhadap prompt
   */
  response: string;
  /**
   * URL yang diambil
   */
  url: string;
  /**
   * URL akhir setelah redirect
   */
  final_url?: string;
  /**
   * Kode status HTTP
   */
  status_code?: number;
}

interface WebSearchOutput {
  /**
   * Hasil pencarian
   */
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    /**
     * Metadata tambahan jika tersedia
     */
    metadata?: Record<string, any>;
  }>;
  /**
   * Total jumlah hasil
   */
  total_results: number;
  /**
   * Query yang dicari
   */
  query: string;
}

interface TodoWriteOutput {
  /**
   * Pesan sukses
   */
  message: string;
  /**
   * Statistik todo saat ini
   */
  stats: {
    total: number;
    pending: number;
    in_progress: number;
    completed: number;
  };
}

interface ExitPlanModeOutput {
  /**
   * Pesan konfirmasi
   */
  message: string;
  /**
   * Apakah pengguna menyetujui rencana
   */
  approved?: boolean;
}

interface ListMcpResourcesOutput {
  /**
   * Sumber daya yang tersedia
   */
  resources: Array<{
    uri: string;
    name: string;
    description?: string;
    mimeType?: string;
    server: string;
  }>;
  /**
   * Total jumlah sumber daya
   */
  total: number;
}

interface ReadMcpResourceOutput {
  /**
   * Konten sumber daya
   */
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
  }>;
  /**
   * Server yang menyediakan sumber daya
   */
  server: string;
}

type PermissionUpdate = 
  | {
      type: 'addRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'replaceRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'removeRules';
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'setMode';
      mode: PermissionMode;
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'addDirectories';
      directories: string[];
      destination: PermissionUpdateDestination;
    }
  | {
      type: 'removeDirectories';
      directories: string[];
      destination: PermissionUpdateDestination;
    }

type PermissionBehavior = 'allow' | 'deny' | 'ask';

type PermissionUpdateDestination = 
  | 'userSettings'     // Pengaturan pengguna global
  | 'projectSettings'  // Pengaturan proyek per-direktori
  | 'localSettings'    // Pengaturan lokal yang diabaikan Git
  | 'session'          // Hanya sesi saat ini

type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
}

type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';

type ConfigScope = 'local' | 'user' | 'project';

type NonNullableUsage = {
  [K in keyof Usage]: NonNullable<Usage[K]>;
}

type Usage = {
  input_tokens: number | null;
  output_tokens: number | null;
  cache_creation_input_tokens?: number | null;
  cache_read_input_tokens?: number | null;
}

type CallToolResult = {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    // Field tambahan bervariasi berdasarkan tipe
  }>;
  isError?: boolean;
}

class AbortError extends Error {}