メインコンテンツまでスキップ

API でエージェントを構築する

上級
What you'll learn
  • エージェントとは実際には何か——ループ内で動作するモデル——を定義する
  • 判断テストを使い、単一呼び出し・ワークフロー・エージェントを選び分ける
  • 適切なガードレールを備えた最小限のエージェントループを設計する
  • 自前で実装する代わりに Claude Agent SDK に頼るべきタイミングを知る
  • エージェントを堅牢にする：境界を設け、失敗を処理し、権限を制限し、評価する

エージェントとは、ループ内で動作するモデルです。ツールを呼び出し、結果を観察し、完了するまで次のステップを決定しながら目標を追求します。構築する前に、動作する最もシンプルな手段を選びましょう。

判断テスト（作り込みすぎない）​

すべてのタスクにエージェントが必要なわけではありません。まずこのツリーをたどってください——ほとんどのタスクは一番上で止まります。

3つの選択肢、シンプルな順に：

  • 単一呼び出し — 1つのプロンプトで答えが出ます。ほとんどのタスク。最も安く、最も信頼できます。
  • ワークフロー — コード内で固定された一連の呼び出しを自分でオーケストレーションします（決定論的な制御フロー）。ステップが既知の場合に使います。
  • エージェント — モデルが動的にステップを決定します。経路を本当にハードコードできない場合にのみ使います。
Watch out

適応性こそが目的であるときにエージェントを選んでください——印象的に聞こえるからではありません。自分で制御するワークフローのほうがテストもデバッグも簡単です。

ループを設計する​

最小限のカスタムエージェントは、4つの可動部品にすぎません。この順番で組み立てましょう：

Guided walkthrough1 of 4
  1. 目標、制約、利用可能なツールを明示します。これはモデルが毎ターン推論の拠り所にするものです。

Claude Agent SDK は、このループ——ツール、権限、コンテキスト処理——を一式そろえて提供するので、自前で実装する必要がありません。

Pro tip

自分でループを書く前に、Agent SDK がすでにカバーしていないか確認してください。ループ、権限、コンテキスト処理を同梱しているので、ツールと目標に集中できます。

堅牢にする​

ツールを呼び出せるループは、誤動作もしえます。次の4つの習慣がエージェントを信頼できるものに保ちます：

  • すべてに境界を設ける：反復回数、時間、コスト。エージェントはループしうる。
  • ツールの失敗を穏やかに処理する（エラーを結果として返す）。
  • リスクのある操作には**最小権限 + 人間の介在（human-in-the-loop）**を — エージェントのセキュリティを参照。
  • 信頼する前に実際のケースで評価する — 評価を参照。
Key takeaways
  • エージェントとは、目標に向けてツールを呼び出すループ内のモデルである——経路をハードコードできない場合にのみ使う
  • 判断の順序：単一呼び出し → ワークフロー → エージェント → マネージドエージェント；動作する最もシンプルなものを選ぶ
  • 最小限のループ = システムプロンプト + tool_use/tool_result ループ + ガードレール + コンテキスト管理
  • Claude Agent SDK はループ、ツール、権限、コンテキスト処理を一式提供する
  • 堅牢性 = 反復/時間/コストに境界を設ける、ツールの失敗を処理する、最小権限 + 人間の介在、そして信頼する前に評価する

理解度チェック​

理解度チェック

0/5
  1. この文脈でエージェントを最もよく表すのはどれですか？
  2. タスクに固定された既知のステップがあります。何を選ぶべきですか？
  3. カスタムエージェントが実際に正当化されるのはいつですか？
  4. ループにおいて、モデルが tool_use で応答したとき何が起きますか？
  5. エージェントを堅牢にするためのガードレールでは「ない」ものはどれですか？

次へ​