AI SDK Tool Calling は「AI に道具を渡す」前に、どこで止めてどこで実行するかを決めろ
このノートは原文の代替ではありません。読むべきポイントと実装上の意味を整理し、原典への入口を示します。
要点まとめ
- AI に道具を持たせる時は、何ができるかより先に、勝手に実行してよいのか、どこで実行するのか、入力が崩れていないかを決めないと危ない。
- この docs の価値は、tool を単なる function signature ではなく、入力型、承認、実行 host を分けて設計する部品として扱っている点にある。
- `execute` は必須ではなく、tool call を queue や別 worker に逃がせる。つまり model 提案と副作用実行を同じ process に縛らなくてよい。
- `needsApproval` と `tool-approval-request` により、危険操作を 1 回の自動実行で終わらせず、承認付きの二段階に分ける前提が明示されている。
読み終えたら次へ
この1本で終わらせず、同じ目的・同じテーマ・近い原典へ進めます。
何が変わったのか
この docs は tool を `description`、`inputSchema`、`execute`、`strict` を持つ object として整理しています。特に重要なのは `execute` が optional だという点です。つまり、同じ process でそのまま副作用を起こさず、client や queue に転送して別 worker で処理する設計が最初から想定されています。 さらに approval の流れも protocol 的に扱っています。`needsApproval` を付けると、一度 `tool-approval-request` を返し、承認または拒否を messages に足してから再度 model を呼ぶ二段構えになります。承認は後付けの `if` ではなく、会話と実行の境界として前に出されています。
なぜ重要か
日本語圏では tool use の説明が「関数を呼べて便利」で終わりやすく、危険な副作用をどこで止めるかが後回しになりがちです。この docs は、そこを SDK 設計の責務として前へ出しています。 PM や創業者にも重要です。AI agent の失敗は、答えを少し間違えることより、送信、更新、削除を早すぎる場所で自動実行することのほうが高くつきます。だから読むべき論点はモデルの賢さではなく、approval と execution host の切り分けです。
技術的ポイント
- `inputSchema` は tool が受け取れる入力形を定義し、call の validation にも使われる。
- `execute` は optional で、tool call を client や queue に渡して別 process で処理する設計も許されている。
- `needsApproval` を付けた tool は自動実行されず、最初の呼び出しでは `tool-approval-request` が返る。
- `strict: true` は対応 provider では schema に合う call だけを出しやすくするが、未対応 provider では無視されることがある。
- `inputExamples` は schema だけでは足りない入力意図を補うが、provider ごとに効き方が違う。
英日キーワード
| 英語 | 日本語 | 補足 |
|---|---|---|
| tool calling | ツール呼び出し | モデルが外部処理の利用を提案する仕組み。実行場所、承認、入力検証を別に設計しないと事故の入口になる。 |
| inputSchema | 入力スキーマ | tool が受け取れる入力形を定義する型。説明用 metadata ではなく、崩れた call を止める基準にもなる。 |
| strict mode | 厳格モード | schema に合う call だけを出しやすくする設定。provider 差があるため、これだけで validation 完了とは言えない。 |
| needsApproval | 承認要求設定 | 危険な tool を即実行せず、まず承認待ちに上げるための指定。副作用操作の stop line になる。 |
| tool-approval-request | ツール承認要求 | tool 実行前に返る承認待ちイベント。会話と実行を 1 回で済ませず二段階に分けるための仕組み。 |
| queue-based execution | キュー経由実行 | tool call と実際の副作用処理を別 worker に分ける構成。同一 process 即実行より事故範囲を絞りやすい。 |
試すなら
- まず今の tool を read-only と副作用ありに分け、副作用ありだけ `needsApproval` 候補にする。
- 送信、削除、支払い、公開のような重い操作は、`execute` を同一 process に置かず queue や worker に逃がせないか検討する。
- `inputSchema` を「とりあえず string 1 個」で済ませず、実際に止めたい入力崩れを型で表す。
- strict mode を試す場合も、provider ごとの差とサーバー側 validation を別に確認する。
注意点
- この docs は SDK の能力を示すが、承認者を誰にするか、queue の再実行方針をどうするかまでは決めてくれない。
- strict mode は便利でも万能ではない。未対応 provider や複雑 schema では期待通りに効かない可能性がある。
- approval を入れても、実行 host が広い権限を持ちすぎていれば事故範囲は小さくならない。
この記事は役に立ちましたか
公益的に続けるため、役に立った点や読みづらかった点だけを短く送れます。メールアドレスは不要です。