マルチエージェントAgent SDK の設定の組み立て方｜モデルと上限
この記事の要点
- Agent SDK の設定は、設定ファイル・環境変数・始める時に渡す options の3つから読まれる。options は全部が任意
- 予備のモデル（fallbackModel）を入れておくと、混み合っている時に自動で切り替わり、次の依頼で元のモデルに戻る
- env の渡し方は言語で違う。TypeScript は置き換え、Python は上乗せ
Claude Agent SDK で AI エージェントを作り始めると、「どの設定を、どこに書けばいいのか」 で迷います。設定の項目は多いですが、最初に決めるのは「モデル・作業フォルダ・使ってよい道具・上限」の4つだけで足ります。
この記事では、公式ドキュメント「Configure your agent」（2026年11月12日確認）にもとづいて、設定の組み立て方を整理します。動く仕組みのほうは Agent SDK の動く仕組み で解説しています。
結論：最初は4つの項目だけ決めればよい
options の項目はすべて任意で、何も渡さなくても既定の値で動きます。 公式の例では、次の4つだけを決めて「プロジェクトのやり残しをまとめる、読むだけのエージェント」を作っています。
- model：使うモデル
- allowedTools：確認なしで使ってよい道具（例：読む・探すだけ）
- maxTurns：回数の上限
- cwd：作業フォルダ
ここで決めた道具の一覧は「確認なしで通すもの」で、それ以外の道具が使えなくなるわけではありません。一覧に無い道具を使う時は、権限のモードで通すかが決まります。くわしくは Agent SDK の権限設定 を見てください。
設定はどこから読まれるか
| 読まれる場所 | 中身 | 決め方 |
|---|---|---|
| 設定ファイル | settings.json・CLAUDE.md など | settingSources で範囲を選ぶ |
| settings の項目 | ファイルの場所か、JSON の文字 | ファイルの設定より強い（会社の管理用の設定だけはさらに上） |
| 環境変数 | 中継先・時間切れの長さなど | env で渡す |
| options | モデル・道具・上限など | 始める時に渡す |
どの設定ファイルを読むかの決め方は Agent SDK で CLAUDE.md を読み込む で解説しています。
モデルと、予備のモデル
model を書かないと、Claude Code の既定のモデルで始まります。 速さと費用を抑えたいエージェントなら、小さめのモデルを指定します。
もう1つ入れておきたいのが 予備のモデル（fallbackModel） です。いつものモデルが混み合っている時や使えない時に、自動で予備に切り替わります。いつものモデルは次の依頼の時にまた試されるので、混雑が終われば元に戻ります。 予備は1つでも、カンマ区切りで複数でも書けます。
なお、文章のばらつき（temperature）や出す長さ（max_tokens）といった項目は options にありません。代わりに、考える深さ（effort）や金額の上限で調整します。モデルの選び方は Claude Code のモデルの選び方 にまとめています。
環境変数の渡し方は言語で違う
ここが一番まちがえやすい点です。
| 言語 | env を渡した時の動き | 気をつけること |
|---|---|---|
| TypeScript | 環境が丸ごと置き換わる | 今の環境（PATH・HOME など）を一緒に入れ直す |
| Python | 今の環境の上に足される | 同じ名前は渡したほうが勝つ |
TypeScript で書き忘れると、PATH や API キーが消えて動かなくなります。env を渡さなければ、どちらの言語でも今の環境をそのまま引き継ぎます。使える環境変数は Claude Code 環境変数の設定方法 で解説しています。
作業フォルダ
cwd で、どのプロジェクトの設定・スキル・会話の保存先を使うかが決まります。 途中で作業フォルダを変える方法は無いので、別のフォルダで作業させたい時は新しい会話を始めます。作業フォルダの外のファイルを読ませたい時は、追加のフォルダ（additionalDirectories）を足します。ただし、足したフォルダの設定までは読まれません。
回数と金額の上限
| 上限 | 0 を入れた時 |
|---|---|
| maxTurns（回数） | 上限なしと同じ |
| maxBudgetUsd（金額） | 起動の時点で断られ、動かない |
1回きりの依頼（query）では、上限に届くと結果を返したあとにエラーになるので、受け取る部分を try で囲みます。続けて依頼を流し込む使い方では、会話は止まらず、回数の数え方は依頼ごとに戻りますが、金額は積み上がります。
動いている途中で変える
依頼を流し込む使い方なら、途中でモデルと権限のモードを切り替えられます。 TypeScript では query が返すもの、Python では ClaudeSDKClient から切り替えます。
- setModel：モデルを切り替える。何も渡さないと既定のモデルに戻る
- setPermissionMode：権限のモードを切り替える
モデルを切り替えると、それまでの会話の読み込み直しが、新しいモデルの料金で一度かかります。 モデルごとにキャッシュが別だからです。何度も切り替えるより、作業の区切りで切り替えるほうが費用を抑えられます。キャッシュの仕組みは Claude Code のプロンプトキャッシュ で解説しています。
よくある質問
どの項目がどの機能に効くのか一覧はありますか？
公式ドキュメントには、項目と機能の対応表があります。たとえば systemPrompt は指示文、mcpServers は外のサービス、agents はサブエージェント、outputFormat は決めた形の出力、resume は続きからの再開です。迷ったら、やりたいことから機能を選ぶ表を先に見ます。
中継サーバー（ゲートウェイ）を通したい時は？
env で ANTHROPIC_BASE_URL を中継先の住所にします。会社のネットワークでの設定は Claude Code プロキシ設定 もあわせて見てください。
まとめ
- 最初は モデル・道具・回数・作業フォルダ の4つだけ決める
- 予備のモデル を入れておくと、混雑の時に止まりにくい
- env は TypeScript は置き換え、Python は上乗せ
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
