Claude Agent SDKでエージェントを開発するときはエージェントループを操るべし
ども、大瀧です。
Claude Codeには、エージェントを開発するためのSDKとしてClaude Agent SDK(旧Claude Code SDK)が提供されます。Agent SDKはPython版とTypeScript版があり、Claude APIを利用するエージェントAIを数行のコードでアプリケーションに組み込むことができます。
本記事では、ClaudeによるエージェントAIを設計するための基本的な考え方とプラクティスを紹介します。
エージェントループのしくみ
Claudeには様々な機能がありますが、基本的なフローは以下のエージェントループで表すことができます。
引用: https://platform.claude.com/docs/en/agent-sdk/agent-loop
ユーザーからの依頼(プロンプト)をClaudeが受け取り、どのような処理を行うかを検討、必要に応じて様々な機能を選択してツールの呼び出しとしてリクエストします。Claudeはツールの実行結果を受けとり、その結果を元に次のツールの選定と呼び出しを繰り返します。これがエージェントループです。Claudeはプロンプトに対する対応が終わったと判断したら、ツールの呼び出しを止め、最終的な結果を返してループを終了します。
皆さんが普段利用しているClaude CodeやClaude Coworkに表示される「thinking」や、「ウェブを検索」の表示がエージェントループの一端とイメージいただくと良いでしょう。ツールにはファイルを操作する Read、Edit、WriteやWeb検索を実行するWebSearchなどがあり、Claude Agent SDKでは、呼び出すツールの許可設定をallowedToolsなどで行います。ツールについては、また別の記事で解説します。
エージェントループの終了条件
エージェントループの終了条件は、どのようなロジックにするのが良いでしょうか。Claudeからはループの各フェーズ(ここではターンと呼びます)でメッセージが返ってくるので、そのメッセージを解析して終了条件を評価します。メッセージには以下の種類があります。
SystemMessage: セッションにかかるメッセージAssistantMessage: ClaudeエージェントのメッセージUserMessage: ツールに関するメッセージResultMessage: 処理結果に関するメッセージ
Agent SDKを利用する場合はメッセージのインスタンスがResultMessageであることを条件にすれば良いですね。Agent SDKは内部でClaude APIなどのREST APIを呼び出して、そのレスポンスを解析して上記のメッセージインスタンスを返しています。Claude APIのレスポンスでは、stop_reasonという要素にターンの終了要因が含まれます。
主なstop_reasonの種類
end_turn: ターンの正常終了tool_use: ツールの利用待ちmax_tokens: リクエストで指定したトークン制限の超過refusal: 安全上の懸念からの対応拒否
基本はend_turnを判別しつつ、tool_useが返ってきた場合はアプリケーション側でツールの呼び出しで対応します(実際はAgent SDKがツールを判別して対応します)。
一方で、Claudeが返してきたテキストメッセージ(content.textなど)に"終了"など特定の文字列が含まれるかどうかという条件指定は推奨されません。エージェントは様々な場面でテキストメッセージを生成するため、終了条件の正確な判別には不適当です。
まとめ
ClaudeによるエージェントAIを設計するための基本的な考え方として、エージェントループとその終了条件をご紹介しました。Claudeをアプリケーションに組み込む手法のご紹介を続けていきますので、ご期待ください。
参考URL
