Claude Agent SDKでエージェントを作ると、最初に迷うのが「どの設定をどこに書くか」です。モデルの指定、APIの接続先、作業フォルダ、暴走を止める上限は、すべてquery()に渡すoptionsで指定できますが、設定ファイルや環境変数も同時に効きます。この記事では、2026年11月9日に確認した公式ドキュメント「Configure your agent」とTypeScript・Pythonのリファレンスを基に、設定の組み立て方とTypeScriptとPythonで挙動が違う点を整理します。権限の細かい決め方はAgent SDKの権限設定で扱っています。
設定が届く3つの経路
Agent SDKのセッションが読む設定は、次の3か所から来ます。
- options:
query()に渡すオブジェクトです。TypeScriptではOptions、PythonではClaudeAgentOptionsという型で、どの項目も省略できます。何も渡さなければSDKの既定で動きます。 - 設定ファイル: ユーザー、プロジェクト、ローカルの
settings.jsonとCLAUDE.mdです。 - 環境変数: Claude Code本体が読む変数です。
envオプションで渡すか、プロセスの環境に置きます。
まずはoptionsだけで試すのが分かりやすいです。次のTypeScriptの例は、リポジトリを読むだけのエージェントに、モデルと上限を指定しています。
import { query } from "@anthropic-ai/claude-agent-sdk";
const options = {
model: "claude-sonnet-5",
allowedTools: ["Read", "Grep"],
maxTurns: 5,
maxBudgetUsd: 0.5,
cwd: "/srv/repos/my-app",
};
for await (const message of query({ prompt: "READMEの古い記述を挙げて", options })) {
if (message.type === "result") console.log(message.subtype);
}
Pythonでは同じ項目がallowed_tools、max_turns、max_budget_usdのようにスネークケースになります。
ここで間違えやすいのがallowedToolsです。これは「承認なしで実行してよいツール」の一覧で、使えるツールを絞る設定ではありません。一覧にないツールはpermissionModeとcanUseToolの判断に回ります。特定のツールを使わせたくないときはdisallowedTools(Pythonはdisallowed_tools)で止めます。
機能ごとの項目は、それぞれ専用の記事にまとめています。
| TypeScript | Python | 設定するもの |
|---|---|---|
permissionMode | permission_mode | 承認なしでできる範囲 |
systemPrompt | system_prompt | エージェントへの指示 |
mcpServers | mcp_servers | 外部ツールのサーバー |
agents | agents | サブエージェントの定義 |
hooks | hooks | 実行途中のコールバック |
outputFormat | output_format | 構造化出力のスキーマ |
resume | resume | 保存済みセッションの再開 |
settingSourcesとsettingsの使い分け
設定ファイルの扱いを決める項目は2つあり、役割が異なります。
| 項目 | 役割 | 指定できる値 |
|---|---|---|
settingSources / setting_sources | ファイルから読む範囲を選ぶ | user、project、localの組み合わせ。[]で3つとも読まない |
settings | 追加の設定を直接渡す | ファイルパスかインラインのJSON文字列。TypeScriptはオブジェクトも可 |
優先順位は高い順に、組織の管理ポリシー、settingsなどプログラムからの指定、ローカル(.claude/settings.local.json)、プロジェクト(.claude/settings.json)、ユーザー(~/.claude/settings.json)です。
settingSourcesを省略すると、CLIの既定どおりすべての範囲を読みます。開発者のPCの設定に左右されたくないサーバーでは、[]を渡すと再現性を確保しやすくなります。ただし[]でも、端末に配布された管理ポリシーは読み込まれます。組織の認証情報で対象の構成なら、サーバー管理の設定も取得されます。
Pythonには1つ注意点があります。skillsを指定してsetting_sourcesを省略すると、読まれるのはユーザーとプロジェクトだけになります。ローカル設定も読ませたいときは、setting_sourcesを明示します。読み込みの範囲ごとに何が使えるようになるかは、Agent SDKでClaude Codeの機能を使う記事を参照してください。
モデルと予備モデルを指定する
modelにはエイリアスか完全なモデル名を渡します。指定がなければ、設定や環境で選ばれたモデル、それもなければClaude Codeの既定モデルで始まります。処理が軽いエージェントで小さなモデルを固定すると、速度と費用を抑えられます。
主モデルが過負荷や利用不可のときに備えて、fallbackModel(Pythonはfallback_model)で予備を指定できます。値は1つでも、カンマ区切りの複数でもかまいません。
options = ClaudeAgentOptions(
model="claude-opus-5",
fallback_model="claude-sonnet-5",
)
予備に切り替わった後も、主モデルはユーザーのターンが始まるたびに試し直されるので、障害が収まれば元に戻ります。TypeScriptでは、fallbackModelにmodelと同じ値を渡すと起動時にエラーになります。
Messages APIのtemperature、top_p、max_tokensに当たる項目は、optionsにはありません。出力の量や費用を調整したいときは、effortや後述の費用上限を使います。これらのパラメータを直接指定する必要があれば、Messages APIを直接呼びます。
環境変数と作業ディレクトリ
envはセッションを動かすClaude Codeのプロセスに環境変数を渡す項目で、ここには言語による大きな違いがあります。
| 言語 | envを渡したときの動き |
|---|---|
| TypeScript | 子プロセスの環境を置き換える |
| Python | 継承した環境の上にマージする(同名は渡した値が優先) |
TypeScriptで1つだけ変数を足すつもりでenv: { MY_VAR: "1" }と書くと、PATHやANTHROPIC_API_KEYが子プロセスから消えます。必ずprocess.envを展開してから足します。env自体を省略すれば、どちらの言語でも環境は継承されます。
const options = {
env: { ...process.env, ANTHROPIC_BASE_URL: "https://llm-proxy.internal" },
};
作業ディレクトリはcwdで指定し、省略すると自分のプロセスのカレントディレクトリになります。cwdはファイルの置き場所を示すだけでなく、どのプロジェクトの設定とフックを読むか、どこからスキルを探すか、保存したセッションをどのプロジェクトに結び付けるかも決めます。途中で変えるメソッドはないため、別のディレクトリで動かすには新しいセッションを始めます。
cwdの外のファイルを扱わせるには、additionalDirectories(Pythonはadd_dirs)に足します。各パスはClaude Codeに--add-dirとして渡され、projectの設定ソースを読む場合は、そのディレクトリのスキル、コマンド、サブエージェントも読み込まれます。
ターンと費用の上限
無人で動かすエージェントには、ターン数のmaxTurns / max_turnsと費用のmaxBudgetUsd / max_budget_usdを設定しておくと安心です。どちらも既定では無制限です。上限に達すると結果メッセージのsubtypeがerror_max_turnsまたはerror_max_budget_usdになります。
上限に達した後の動きは入力の形式で変わります。
- 1回限りの
query(): 結果メッセージを返した後に例外が発生します。続きの処理があるなら、ループをtryで囲みます。 - ストリーミング入力: セッションは続きます。ターン数はメッセージごとに数え直しますが、費用は累積し、上限に達した後のメッセージは同じ結果で終わります。
/clearで費用の累計はリセットされます。
try:
async for message in query(prompt=task, options=options):
if isinstance(message, ResultMessage):
print(message.subtype)
except Exception as err:
# 上限に達した結果を受け取った後、ここへ来る
print("stopped:", err)
値の0は両者で意味が逆になる点に注意してください。maxTurns: 0は未指定と同じで制限なしになりますが、maxBudgetUsd: 0は不正な値としてCLIが起動時に拒否し、セッションは始まりません。
費用の上限はクライアント側の見積もりに基づくため、設定額を少し超えることがあります。余裕を持たせた値にします。また数えるのはその呼び出し自体の費用だけで、再開したセッションから復元された累計は含まれません。費用の読み取り方はAgent SDKのコスト追跡で扱っています。
実行中に設定を変える
ストリーミング入力のセッションでは、実行中にモデルと権限モードを切り替えられます。TypeScriptではquery()が返すオブジェクトのメソッド、PythonではClaudeSDKClientのメソッドとして呼びます。Pythonのquery()はただのイテレーターで、これらのメソッドを持たないためです。
| TypeScript | Python | 働き |
|---|---|---|
setModel() | set_model() | モデルを切り替える |
setPermissionMode() | set_permission_mode() | 権限モードを切り替える |
applyFlagSettings() | なし | 設定キーを実行中のセッションに適用する |
updateSettings() | なし | 許可されたキーを設定ファイルへ書き込む |
const session = query({ prompt: messageStream, options });
// 調査は軽いモデルで進め、難しい段階で切り替える
await session.setModel("claude-opus-5");
await session.setPermissionMode("acceptEdits");
切り替えには落とし穴が3つあります。
setModel()を引数なしで呼ぶと、optionsで渡したmodelではなくClaude Codeの既定モデルに戻ります。- Autoモードの途中で、Autoモードに対応しないモデルへ切り替えると、権限モードは
defaultに変わります。 - プロンプトキャッシュはモデルごとに別なので、切り替え直後のリクエストは会話全体が新しいモデルの料金でキャッシュなしで計算されます。頻繁な切り替えは費用を増やします。
updateSettings()の第1引数は"localSettings"か"userSettings"で、TypeScript SDK v0.3.257以降で使えます。"userSettings"に書けるキーはeffortLevelだけで、現在のモデルの既定として保存されますが、実行中のセッションの努力レベルは変わりません。実行中に努力レベルを変えたいときはapplyFlagSettings()を使います。
参照した一次情報は、Claude Code公式の「Configure your agent」、TypeScript SDKリファレンス、Python SDKリファレンスです。各項目の型と既定値はSDKのバージョンで変わることがあるので、導入前に最新版を確認してください。