コンテンツにスキップ
mild worksai-tools-kb

How the agent loop works

facts ／Claude Code ／agent-sdk-loop

stable1 か月前 · 2026-08-23

概要

Agent SDK が回す実行ループの中身。メッセージのライフサイクル、ターンの数え方、上限の掛け方を扱う。CLI を動かしているのと同じループ。

仕様

ループの 1 周

段階起きることSDK が返すもの
1. プロンプト受領システムプロンプト・ツール定義・会話履歴と一緒に Claude が受け取るSystemMessage（subtype "init"、セッションメタデータ）
2. 評価と応答テキスト、ツール呼び出し要求、またはその両方AssistantMessage
3. ツール実行SDK が各ツールを実行し結果を集める。hook で実行前に介入・改変・拒否できる—
4. 反復2 と 3 を繰り返す。1 周が 1 ターン—
5. 結果返却ツール呼び出しの無い応答が出たら終わりAssistantMessage に続けて ResultMessage

ResultMessage は最終テキスト・トークン使用量・コスト・セッション ID を含む。

ターンと上限

  • ターン = ループ 1 周。Claude がツール呼び出しを含む出力を出し、SDK がそれを実行し、結果が Claude に戻るまで。この間、呼び出し側のコードに制御は戻らない
  • max_turns / maxTurns で上限を掛ける。ツール使用のターンのみを数える
  • max_budget_usd / maxBudgetUsd で支出しきい値によるターン上限を掛ける
  • 上限を設けない場合、Claude が自分で終わるまで走る

メッセージ型

型いつ出るか
SystemMessageセッションのライフサイクルイベント。subtype で区別する
AssistantMessageClaude の応答ごと（最後のテキストのみの応答を含む）。テキストブロックとツール呼び出しブロックを持つ
UserMessageツール実行ごとに、Claude へ返すツール結果を伴って。ループ途中でストリームした入力にも出る
StreamEventpartial messages を有効にしたときのみ。生の API ストリーミングイベント
ResultMessageループの終了。最終テキスト・トークン使用量・コスト・セッション ID

SystemMessage の subtype:

値意味
"init"セッションメタデータ。SessionStart / Setup hook が走る場合、その hook ライフサイクルメッセージが init より先に届く
"compact_boundary"compaction の後に発火する
"informational"ループからのプレーンテキストの状態表示
"worker_shutting_down"ホストの終了または Remote Control の切断により、現在のターンの後でループが終わる
  • TypeScript では "init" 以外の subtype は SDKSystemMessage の subtype ではなく、SDKMessage union の独立した型になる

言語ごとの型判定

判定方法注意
Pythonclaude_agent_sdk から import したクラスに isinstance()—
TypeScripttype 文字列フィールド（message.type === "result"）AssistantMessage と UserMessage は生の API メッセージを .message に包む。コンテンツブロックは message.message.content であって message.content ではない

制約・注意点

  • ResultMessage の後にも、prompt_suggestion などの後続システムイベントが少数届きうる。 result で break せず、ストリームを最後まで反復すること
  • ResultMessage の subtype を見て、タスクが成功したか上限に当たったかを判定する
  • 両 SDK は、ループの駆動に必須ではない observability イベント（レート制限の状態、タスク通知など）も返す

関連

  • facts/claude-code/agent-sdk.md
  • facts/claude-code/hooks.md — ツール実行前の介入
  • facts/claude-code/context-window.md — compaction
  • facts/claude-code/costs.md — 予算上限