Agent SDK reference - TypeScript

概要

TypeScript Agent SDK（@anthropic-ai/claude-agent-sdk）で何ができるかと、導入時に踏む落とし穴をまとめる。

このページは API の全項目を写さない。 原典は約 30 万字の API リファレンスで、プロパティ 1 つの型が変わるたびに追従が要る。写すと必ず古くなり、途中までの表は「載っていない＝存在しない」と誤読される。関数ごとの引数と型は公式リファレンス（sources の URL）を直接読む。

ここに残すのは、原典を読めば書いてあるが探しにくいもの — 導入時に失敗する条件、Python SDK との挙動差、安定していない API。

仕様

インストール

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

SDK はプラットフォーム別のネイティブ Claude Code バイナリを optional dependency としてバンドルする（例: @anthropic-ai/claude-agent-sdk-darwin-arm64）
SDK バージョンはバンドルされた Claude Code バージョンと一致する（SDK v0.3.191 は Claude Code v2.1.191 をバンドル）
package manager が optional dependency をスキップすると Native CLI binary for <platform> not found をスローする。 pathToClaudeCodeExecutable に別途インストールした claude バイナリのパスを渡すと回避できる
Yarn 1.x は libc フィールドを適用しないため、Linux で glibc と musl の両方のパッケージが入る。SDK は正しいバリアントを起動する

Bun 単一実行ファイルへのコンパイル

bun build --compile でコンパイルすると、require.resolve が $bunfs 仮想ファイルシステム内で機能しないため、SDK がバイナリを見つけられない。

回避方法（@anthropic-ai/claude-agent-sdk v0.3.144 以降が必要）:

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";

関数の地図

引数と戻り値の型は公式リファレンスを見る。ここでは「何があるか」だけを示す。

関数	何をするか
`query()`	Claude Code とやり取りする主要関数。メッセージをストリームとして返す
`startup()`	`query()` の前に CLI サブプロセスを事前起動するウォームアップ
`tool()`	型安全な MCP ツール定義を作る（Zod 3 / Zod 4 の両方に対応）
`createSdkMcpServer()`	アプリケーションと同一プロセス内で動く MCP サーバーを作る
`listSessions()`	過去のセッションを軽量なメタデータ付きで一覧する
`getSessionMessages()`	過去のセッションのユーザー・アシスタントメッセージを読む
`getSessionInfo()`	単一セッションのメタデータを ID で取得する
`renameSession()`	カスタムタイトルを付けてセッション名を変える
`tagSession()`	セッションにタグを付ける（`null` で削除）
`resolveSettings()`	CLI を起動せずに、指定ディレクトリで有効な設定を解決する

tool() の extras には、tool search 向けの searchHint（遅延ツール一覧に出す一行説明）と alwaysLoad（遅延せず初期プロンプトに常に含める）がある
createSdkMcpServer() の alwaysLoad は、そのサーバーの全ツールを初期プロンプトに含める

`resolveSettings()` の性質

アルファ版。API は安定化前に変更されうる。

MDM ソース（macOS plist・Windows HKLM/HKCU）は読み取るが、policyHelper サブプロセスは実行しない
permissions.defaultMode: 'auto' は、プロジェクト設定・ローカル設定から来た場合でも返す。 ライブセッションはこれらを無視するため、解決結果と実際の挙動に差が出る
戻り値は effective（マージ後の有効設定）、provenance（各トップレベルキーを提供したソース）、sources（優先度の低い順に並んだソース別の生設定）を持つ

制約・注意点

env オプションはサブプロセス環境を置き換える（Python SDK は継承環境にマージする）。...process.env をスプレッドしないと PATH などが失われる
SDK バージョンとバンドルされた Claude Code バージョンは一致する（SDK v0.3.X は Claude Code v2.1.X）
resolveSettings() はアルファ版