AI エージェントの Thinking Effort を理解する：開発者が知っておくべきこと

AI エージェントの Thinking Effort を理解する

第I部 · 思い込みを問い直す

AI に「もっと考えさせる」ことが、なぜ常に良い結果につながるとは限らないのか。

thinking effort の設定は実際に何を変えるのか、そしていつ上げるべきなのか。このスライドは、この問いを 21 枚のスライドで追う。概念、reasoning とエージェント実行の違い、実際のエンジニアリング事例、本番向けのアーキテクチャ、そして直感ではなく証拠で判断する方法である。

同じモデル、同じプロンプトなのに結果が違う？

第I部 · 思い込みを問い直す

同じに見えるリクエストを 2 回実行して、1 回目はきれいな答え、2 回目は的外れな答えが返ってくることがある。ある設定のせいにする前に、変わったものをすべて挙げてみよう。タスクには、道が 1 つしかなく直接解けるものがある。一方で、妥当な道が複数あり、システムが慎重に検討したり追加の証拠を集めたりすると答えが良くなるものもある。

• タスクの複雑さと曖昧さによって、妥当な答えがいくつあるかが変わる。
• 利用できるコンテキストとツールの出力が、モデルが実際に知り得ることを決める。
• サンプリングのランダム性により、同じプロンプトでも 2 回の実行が食い違うことがある。
• モデルの挙動と設定も影響し、effort は設定の一部にすぎない。

effort を上げても、自動的に賢くなるわけではない

第I部 · 思い込みを問い直す

よくある思い込みは 3 つあり、どれも役に立つ形で間違っている。

1. 「effort を上げれば必ず良い答えが出る。」 一部のタスクでは助けになる。しかし正しさは保証されず、簡単なタスクではコストが増えるだけのことが多い。
2. 「長く考えるほど、深く正確な推論になる。」 長さは質ではない。長い推論の連鎖でも、長いだけで間違っていることがある。
3. 「エージェントのステップが多いほど有能になる。」 ステップが増えると、誤りを直すのと同じくらい簡単に誤りが積み重なる。

Thinking Effort は推論リソースの話であり、待ち時間を延ばすことではない

第II部 · 技術の基礎

thinking effort は、**モデルやプラットフォーム固有の制御（存在する場合）**であり、タスクの推論にどれだけの労力を割くかに影響する。これは公開 API 上の設定であって、モデル内部をのぞく窓ではない。

つまり、同じ言葉でも API によって意味が異なる。各レベルが固定の token 数、ステップ数、計算量に対応すると想定してはいけない。

タスクの複雑さが reasoning effort を左右すべきである

第II部 · 技術の基礎

タスク A は、JSON オブジェクトを TypeScript のインターフェースに変換する作業だ。出力は一目で確認できる。追加の熟考で結果が変わることはほとんどない。

タスク B は、分散システムで断続的に起きる競合状態の調査だ。ここでは慎重な推論が効く。仮説を比較し、エッジケースを考え、コンポーネント間の挙動をつなぎ合わせる。

ただし、複雑さだけが軸ではない。本番データのマイグレーションのように、説明は短くても結果が深刻なタスクは、慎重な推論、追加の確認、人によるレビューに値することがある。

モデルの推論とエージェントの実行は別物である

第II部 · 技術の基礎

thinking effort は、モデルと API がこの制御に対応している場合に、1 回のモデル呼び出しの中で適用される推論のことだ。

エージェントループ は外側のサイクルである。モデルがコンテキストを受け取り、応答またはツール呼び出しを生成し、ツールの結果を受け取り、停止条件に達するまで続ける（推論と行動を交互に行う古典的な説明が ReAct である）。

この 2 つは独立して変化する。1 回の呼び出しで多くの推論を行い、ツールを一切使わないこともある。逆に、エージェントが数十回ツールを呼びながら、各ステップ自体は単純なこともある。

AI エージェントはモデルだけではない

第II部 · 技術の基礎

概念上の流れ：ユーザーのタスクとコンテキスト → モデルの推論 → 回答するかツールを呼ぶかの判断 → ツールの実行 → 更新されたコンテキスト → 次の判断。タスクが完了するか停止条件が働くまで繰り返される。

effort が作用するのは、このループの 1 つのステップ、つまりモデル呼び出しの内部の推論だ。全体の性能は、コンテキストの質、どのツールがあるか、ハーネスがリトライや停止をどう制御するか、そして何かが結果を検証するかどうかにも左右される。スライド 15 では、このループを本番向けのリファレンスアーキテクチャにする。

effort のレベルの違いは、トレードオフの違いである

第II部 · 技術の基礎

	低い effort	高い effort
レイテンシ	低くなる傾向	高くなる傾向
コスト	低くなる傾向	高くなる傾向
難しい複数ステップのタスク	徹底さが足りないことがある	より徹底することがある
単純なタスク	たいてい十分	効果は小さく、コストは増える

これらは傾向であり、保証ではない。 差の大きさは、モデル、タスク、測り方によって変わる。一般化できる数値はないため、この記事では改善幅の数字を示さない。自分の数値を得る方法はスライド 16 と 17 で示す。

effort を上げる価値があるのはいつか？

第III部 · 実際のエンジニアリング事例

API が断続的に HTTP 500 を返す。reasoning effort の高いモデルは、複数の仮説を同時に保持し、依存関係を調べ、エッジケースを考えるのが得意かもしれない。それでも、誰も収集していないログを読むことはできない。

良いワークフローは、推論と観測を交互に行う。

1. 仮説を立て、それぞれを裏付ける、または否定する証拠が何かを明確にする。
2. その証拠（ログ、メトリクス、トレース）を集める。
3. 仮説を更新する。証拠が否定したものは捨てる。
4. 修正を適用し、症状が消えたことを検証する。

1 行の変更とシステム全体のリファクタリングに、同じ戦略は要らない

第III部 · 実際のエンジニアリング事例

• ローカル変数の名前変更。 ほぼ機械的な作業。コンパイラかテストスイートで決着がつく。
• 認証ミドルウェアのリファクタリング。 推論は、呼び出し側、セキュリティへの影響、後方互換性、そして挙動が保たれていることを示すテストをカバーする必要がある。
• デプロイ後のリグレッションの調査。 推論は、読めるものの範囲までしか役に立たない。差分、ログ、テスト結果、最近の変更履歴である。

問題に合った手段を選ぶ

第III部 · 実際のエンジニアリング事例

エージェントが間違えたとき、「もっと考えさせる」は複数ある手段の 1 つであり、常に正しいとは限らない。

• モデルが利用できる仮説を十分に検討していないなら、reasoning effort を上げると効くかもしれない。
• リポジトリの情報が足りないなら、考える量を増やすより検索ツールのほうが役に立つ。
• テスト結果が最初の仮説と矛盾するなら、その結果を使ってもう一度エージェントを反復させるのが正しい。
• タスクが広すぎるなら、どんな単一の設定よりも分解が効く。

説得力のある説明は、正しさの証明ではない

第III部 · 実際のエンジニアリング事例

モデルは、情報の不足、誤った前提、その他の限界から、もっともらしいが間違った結論を出すことがある。説明が流暢かどうかは、それが真実かどうかをほとんど教えてくれない。

コーディングエージェントでの検証とは、具体的な仕組みを指す。自動テスト、型チェックと lint、生成された差分の確認、ログと実行結果の確認、受け入れ基準の照合、そして適切な場合にはセキュリティチェックの実行である。これらのチェックの質は、推論がどれだけ深く見えたかとは独立に評価すること。

品質、レイテンシ、コスト

第IV部 · 本番システムでの活用

• 品質： 正しさ、タスクの完了、堅牢性、エッジケースの扱い。
• レイテンシ： 応答時間と、タスクを完了するまでの総時間。
• コスト： モデルの使用量、該当する場合は reasoning に関わる推論コスト、ツール呼び出し、そして何よりも成功したタスクあたりの総コスト。

目標は、どんな価格でも最高の品質にすることでも、何を犠牲にしても最小のレイテンシにすることでもない。ワークロードとそのビジネス要件にとって許容できるトレードオフを見つけることだ。この 3 つを 1 つの万能なスコアにまとめることはできない。

コストには 3 つの層があり、それぞれが別の問いに答える。

層	数えるもの	数値の出どころ
モデル呼び出し	input、キャッシュされた input、output、reasoning の各 token に、プロバイダーの token 単価を掛けたもの	各レスポンスの usage オブジェクトと、プロバイダーの料金ページ
エージェントの実行	実行中のすべてのモデル呼び出しに加え、ツールの実行、リトライ、サンドボックスや CI の時間、人によるレビュー	自分のトレースとインフラの請求
タスクの成果	総支出と総時間を、検証に合格したタスク数で割ったもの	自分の評価結果

effort が作用するのは 1 つ目の層だが、判断は 3 つ目の層で行うべきものだ。1 回の呼び出しを安くする設定でも、実行の失敗が増え、完了させるためにリトライや人の手が必要になれば、タスクとしては高くつくことがある。

すべてのリクエストで最大 effort を既定にしない

第IV部 · 本番システムでの活用

適応的な戦略では、effort をタスクごとの判断として扱う。タスクを受け取り、複雑さ、不確実性、リスクを評価し、サポートされている設定を選び、実行し、検証し、検証に失敗したらエスカレーション、リトライ、または追加の証拠収集を行う。

ルーティングには、ルール、分類器、モデルベースのルーター、フィードバック駆動のポリシーが使える。

注意点が 2 つある。タスクの分類自体が間違うことがあるので、ルーターも他のコンポーネントと同様に評価すること。そして、選んだモデルや API がサポートする effort レベルだけを使うこと。

エージェントループのリファレンスアーキテクチャ

第IV部 · 本番システムでの活用

課題	提案する制御
暴走するループ	ステップ、token、経過時間の予算を、すべてのモデル呼び出しの前に確認する
進展のないループ	同じ引数での同じツール呼び出しが繰り返されたとき、または同じチェックが失敗し続けるときに停止する
ツールの失敗とタイムアウト	ツールごとにタイムアウトを設ける。リトライは冪等なツールだけに行う。エラーとタイムアウトは結果としてモデルに返し、隠さない
重大な結果を伴う行動	ツールごとのポリシー：読み取り専用のツールは許可し、書き込み、デプロイ、削除、支払いの前には人に確認し、それ以外は拒否する。コードはサンドボックスで実行する
コンテキスト	各ツール結果を状態とともに追加する。大きな出力は切り詰め、完全な成果物への参照を残す
オブザーバビリティ	モデル呼び出し、ツール呼び出し、チェックごとに 1 つのトレーススパンを作り、effort の設定と token 使用量を記録する
最終結果	検証器に合格したものだけを受け入れる

const LIMITS = { maxSteps: 30, maxOutputTokens: 400_000, maxWallClockMs: 15 * 60_000, maxRepeats: 3 };

async function runTask(task: Task): Promise<RunResult> {
  const ctx = newContext(task);
  const startedAt = Date.now();
  let outputTokens = 0;

  for (let step = 1; step <= LIMITS.maxSteps; step++) {
    if (outputTokens > LIMITS.maxOutputTokens || Date.now() - startedAt > LIMITS.maxWallClockMs) {
      return { outcome: "stopped", reason: "budget_exhausted", suspected: "orchestration" };
    }

    // The only place the effort setting acts.
    const turn = await trace("model_call", () => callModel(ctx, { effort: chooseEffort(task) }));
    outputTokens += turn.usage.outputTokens;

    if (turn.kind === "answer") {
      const check = await trace("verify", () => verify(task, turn.answer));
      if (check.passed) return { outcome: "verified", answer: turn.answer, check };
      ctx.append({ type: "verification_failed", findings: check.findings });
      continue;
    }

    const call = turn.toolCall;
    if (repeatCount(ctx, call) >= LIMITS.maxRepeats) {
      return { outcome: "stopped", reason: "no_progress", suspected: "reasoning" };
    }

    const policy = toolPolicy(call); // "allow" | "ask" | "deny"
    if (policy === "deny" || (policy === "ask" && !(await askHuman(call)))) {
      ctx.append({ type: "tool_denied", call });
      continue;
    }

    // Retry only idempotent tools; errors and timeouts go back to the model as results.
    const result = await trace("tool_call", () =>
      runTool(call, { timeoutMs: 60_000, retries: call.idempotent ? 2 : 0 }),
    );
    ctx.append({ type: "tool_result", call, result });
  }

  return { outcome: "stopped", reason: "step_limit", suspected: "orchestration" };
}

失敗した実行には、最初に壊れた分類をラベル付けする。 判断はトレースを読んで行う。推論：事実はコンテキストにあったのに、計画が間違っていた。ツール実行：エラー、タイムアウト、または不正な出力。オーケストレーション：失われたコンテキスト、ループ、または使い切った予算。検証：チェックが欠けていた、不安定だった、または間違っていた。コード中の suspected フィールドは最初の推測にすぎず、決めるのはトレースである。

effort を上げて本当に効果があるかを測る

第IV部 · 本番システムでの活用

実際のワークロードを代表する評価セットを作る。実際のタスクで構成し、各タスクには、結果を見る前に書いた検証器を用意する。そのうえで、モデルがサポートする設定を、effort 以外は同じ条件で比較する。

それ以外はすべて固定する。 次のものを固定し、記録する。

• モデルのスナップショット ID と SDK のバージョン
• システムプロンプト、ツール定義、ハーネスのバージョン
• 各タスクの開始時のコンテキスト：リポジトリのコミット、フィクスチャ、取得したドキュメント
• 出力の上限（max_output_tokens または max_tokens）と、スライド 15 のループの予算
• 検証器とその合格基準

変えるのは effort の値だけにし、モデルのドキュメントに記載された値だけを使い、設定を時間的に交互に実行する。そうすれば、プロバイダー側の変更や遅い時間帯が 1 つの設定にだけ重なることを避けられる。

各タスクを設定ごとに複数回実行する。 同じプロンプトでも 2 回の実行は食い違うことがあるので、タスクごとに 1 回の実行では、設定と同じくらい運を測ることになる。実行回数は始める前に決め、同じタスクでタスクごとに設定を比較し、平均だけでなく区間を報告する。成功率には Wilson の区間のような二項分布の区間が使える。レイテンシとコストには、タスク単位のブートストラップを使う。

回答の長さや reasoning token の数で成功を判断してはいけない。どちらも費やした労力を測るものであり、得られた品質を測るものではない。

埋めて使えるベンチマークのテンプレート

第IV部 · 本番システムでの活用

最初の実行の前にすべての指標を定義しておく。そうすれば、結果を見てから数値を選ぶことはできない。

指標	定義	注意点
検証済みタスク成功率	最終結果が検証器に合格した実行数を、全実行数で割ったもの	主要な数値
初回成功率	検証のフィードバックもリトライもなく、最初の回答で合格した実行数を、全実行数で割ったもの	成功のうち、どれだけがループの回復によるものか
テスト合格率	各実行の最後に、合格したテスト数を実行したテスト数で割ったもの	部分点であり、検証済み成功の代わりにはならない
レイテンシの中央値と P95	実行ごとの、タスク開始から最終結果までの経過時間	P95 が意味を持つには多くの実行が必要
成功したタスクあたりのコスト	失敗した実行も含む全実行の総支出を、検証済みの成功数で割ったもの	可能ならツールとインフラのコストも加える
平均リトライ回数	実行ごとの、チェックの失敗やツールのエラーの後に行われたモデル呼び出しの数	モデル呼び出しの総数とは分けて数える

なぜ想定ではなく測るのか。effort を上げると、熟考を要するタスクでは助けになり得る一方で、レイテンシと output token も増えやすい。どちらの効果が勝つかは、モデル、タスクの構成、検証器の強さによって決まり、モデルが変われば変わることもある。

reasoning effort を明示的なエンジニアリング上の判断にする

第IV部 · 本番システムでの活用

プロバイダーが対応している場合、effort はリクエストのパラメータである。ドキュメントに記載された形の OpenAI Responses API リクエストを示す。reasoning token の数もレスポンスから読み取っている。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "high" }, // the setting this slide is about
  input: "Analyze this production bug...",
});

console.log(response.output_text);
console.log(response.usage?.output_tokens_details.reasoning_tokens);

この設定は、どれだけ推論を適用するかを表すものだ。モデルの非公開の推論を返すものではなく、利用できるのはオプトインの要約だけである。

同じリクエストを Anthropic の Messages API と Gemini の Interactions API で書くと次のようになる。

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const message = await anthropic.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000, // thinking counts toward this cap
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "Analyze this production bug..." }],
});

console.log(message.usage.output_tokens_details?.thinking_tokens);

import { GoogleGenAI } from "@google/genai";

const gemini = new GoogleGenAI({});

const interaction = await gemini.interactions.create({
  model: "gemini-3.8-flash",
  input: "Analyze this production bug...",
  generation_config: { thinking_level: "high" },
});

console.log(interaction.output_text);
console.log(interaction.usage?.total_thought_tokens);

名前は似ていても、契約は異なる。 共通の形式はない。

プロバイダーと API	リクエストのフィールド	ドキュメント記載の値	reasoning の使用量フィールド	出典
OpenAI, Responses	reasoning: { effort }	none、minimal、low、medium、high、xhigh、max	usage.output_tokens_details.reasoning_tokens	Reasoning models
Anthropic, Messages	output_config: { effort }	low、medium、high、xhigh、max	usage.output_tokens_details.thinking_tokens	Effort、Steering thinking
Google, Interactions	generation_config: { thinking_level }	minimal、low、medium、high	usage.total_thought_tokens	Thinking
Google, generateContent	JavaScript SDK では config.thinkingConfig.thinkingLevel	同じ 4 つのレベル	usageMetadata.thoughtsTokenCount	API リファレンス。フィールドの位置は SDK の型で確認

各リストはモデル全体の和集合であり、個々のモデルが受け付けるのはその一部である。また、名前が同じでも挙動が同じとは限らない。あるモデルの high は、同じベンダーのモデルであっても、別のモデルの high と揃えて調整されてはいない。

effort を選ぶための出発点となるヒューリスティック

第V部 · 実践のためのまとめ

要因	低い effort を示すもの	高い effort を示すもの	多くの場合より良い手段
タスクの複雑さ	道が 1 本、局所的な変更	相互に作用する多くの部分、複数の妥当な道	深いのではなく広いタスクは分解する
不確実性と曖昧さ	正確な仕様	比較検討すべき競合する仮説	推論ではなく仕様が曖昧なら、確認の質問をする
コンテキスト	必要なものがすべてプロンプトにある	揃ってはいるが入り組んだコンテキスト	事実が欠けているなら、ファイル、ログ、ドキュメントを取得する
外部情報の必要性	なし	それだけでは理由にならない	ツールを呼ぶ。effort は事実を生み出せない
誤った結果の代償	簡単に元に戻せる	高くつく、または取り返しがつかない	effort に加えて、人による承認とより強いチェック
自動検証	強く速いテストがあり、反復が安い	チェックが弱いかないので、最初の答えがより重要	effort を上げる前に、足りないテストを書く
レイテンシとコストの予算	対話型、大量、厳しい予算	タスクあたりの価値が高いオフラインやバッチの作業	1 つのグローバル設定ではなく、タスクごとにルーティングする（スライド 14）

使い方：各ルートは、その種類のワークロードに対してプロバイダーのガイダンスが推奨するレベル、またはドキュメントの既定値から始める。effort を上げるのは、トレースした失敗の大半が推論の失敗であり（スライド 15）、かつ差を示せるほど検証器が強いルートだけにする。低いレベルでも検証済みの成功が保たれるなら、レベルを下げる。そのうえでスライド 16 と 17 のベンチマークを実行し、表よりも数値を優先すること。

thinking effort を上げる前に、この 5 つの問いを確認する

第V部 · 実践のためのまとめ

これは繰り返し使える判断カードとして残してほしい。問い 1 と問い 5 に「はい」と答えられないなら、設定を上げるのはまだ早いだろう。

最良のエージェントは、最も多く考えるものではない。必要なところに effort を配分するものだ。

第V部 · 実践のためのまとめ

1. thinking effort は、モデルがタスクを処理する方法に影響し得る。ただし正しさは保証しない。
2. reasoning、ツール利用、コンテキストの取得、検証は、それぞれ異なる問題を解く。
3. 適切な設定は、自分のワークロードを評価して決まる。

「どうすれば AI にもっと考えさせられるか」ではなく、「このタスクを確実に完了するには、どれだけの推論が必要か」と問おう。

参考文献とさらに読む

プロバイダーのページはすべて 2026 年 10 月 22 日に最終確認した。

• OpenAI, Reasoning models：reasoning.effort、reasoning token、要約。GPT-6 Astra のモデルページ：サポートされる effort の値。
• Anthropic, Effort と Steering thinking：モデルごとの effort レベルと既定値、adaptive thinking、thinking token とコスト。
• Google, Gemini thinking：Interactions API の thinking_level、モデルごとのレベル、thought の要約と thinking token の使用量。generateContent リファレンス：usageMetadata.thoughtsTokenCount。
• 型チェックに使った SDK：openai 7.42.0、@anthropic-ai/sdk 1.1.0、@google/genai 2.30.0。
• Anthropic, Building effective agents（2024 年 12 月）：ワークフロー、エージェント、複雑さを加えるべき場面。
• Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models（2022）。
• Snell et al., Scaling LLM Test-Time Compute Optimally can be More Effective than Scaling Model Parameters（2024）。
• Chen et al., Reasoning Models Don’t Always Say What They Think（2025）。