AIエージェントのツール設計とは？名前・引数・返り値で誤操作を減らす方法

AIエージェントのツール設計とは？名前・引数・返り値で誤操作を減らす方法

「ツールは動くのに仕事が完了しない」という問題は、接続の不具合とは別に起こります。ここでは、問い合わせ対応で注文の配送先を変更する例を使い、名前・引数・返り値を中心に見直す方法を説明します。

接続できてもツールを使いこなせない理由

ツールは、検索、計算、データの参照や更新などを実行する機能です。AIエージェントは、目的に応じてツールを選び、その結果を受けて次の行動を判断します。ただし、AIが呼び出しを要求することと、システムが実行を許可することは別の段階です。

たとえば「この注文の配送先を変えたい」という依頼では、まずAIが注文参照のツールを選び、注文番号を引数として渡します。実行側は入力や権限を確認して注文情報を取得し、結果を返します。AIは配送状況や変更可否を読み、情報が不足していれば質問し、条件がそろえば変更を要求します。

この流れは途中の情報が曖昧だと崩れます。「データを処理する」という説明だけでは、参照と更新のどちらに使う機能か判断しにくくなります。似たツールが複数あれば選択に迷い、引数が単に「番号」なら注文番号と顧客番号を混同しかねません。結果に大量の履歴が含まれると、肝心の変更可否を読み落とす原因にもなります。

関連する用語は、担当する役割で分けると整理できます。これらは組み合わせて使えますが、同じ問題を解決するものではありません。

多数の候補から必要なツールを探す仕組みや、複数の呼び出しをまとめる方法もあります。本記事で扱うのは、それらで選ばれた一つひとつの機能を、AIが適切に使える形にするための設計です。

仕事に合わせてツールの責務を分ける

ツールの単位は、利用者が達成したい仕事と、その途中で必要になる判断から決めます。既存のAPI、つまりシステムの機能を外から利用する窓口を、すべてそのままAIに公開する必要はありません。社内検索なら回答の根拠となる文書を探すこと、問い合わせ対応なら対象の状況を把握して適切な手続きを進めることが出発点です。

配送先変更では、注文が存在するか、発送前か、現在の配送先はどこかを確認します。これらを毎回別々に取得する構成では、呼び出しや情報の突き合わせが増えます。一つの注文参照ツールが、確認に必要な情報をまとめて返せば、AIはその結果から次の行動を判断しやすくなります。

一方、注文を参照するだけで配送先まで変更される設計は避けます。情報を読む操作と、保存済みの内容を書き換える操作では、必要な権限や確認が異なるためです。参照結果を受け取り、変更対象と新しい住所を確定してから、別の更新ツールを呼ぶ流れにします。

たとえば注文管理、顧客管理、配送管理に情報が分かれていても、利用者にとっては「この注文を確認する」という一つの仕事です。内部では複数のAPIを使いながら、AIには判断に必要な情報を一つの結果として返す設計もできます。

ただし、何でもできる万能ツールにまとめると、操作の選択肢や引数の組み合わせが増え、権限を管理しにくくなります。細かく分けすぎても手順が長くなります。読み取りは仕事に必要な範囲でまとめ、更新は対象と影響が明確な単位に分けたうえで、実際の課題で使いやすさを確かめます。

名前と説明文で選択の迷いを減らす

名前は「何を」「どうするか」が分かる形にします。たとえば process_data では、対象も処理内容も読み取れません。注文参照と配送先変更を分けるなら、次のように機能名と説明を対応させます。ここで示す名前は設計例です。

説明文には、使う場面だけでなく、混同しやすい使い方との違いを記します。「住所変更」だけでは、今回の注文の届け先を変えるのか、今後の注文にも使う顧客の登録住所を変えるのかが分かりません。似た機能ほど、対象や変更の影響範囲を明示する価値があります。

また、必要な情報や前提条件も伝えます。「注文IDを取得してから使う」「変更可否を確認する」といった条件があれば、AIは不足している作業に気づきやすくなります。ただし、説明が長ければよいわけではありません。関係のない社内事情や同じ注意書きの繰り返しは削り、選択に必要な違いを残します。

order_ のような共通の接頭辞で関連機能をまとめる方法は、名前空間の設計に当たります。注文と顧客の機能を見分ける助けになりますが、特定の命名形式が常に最適とは限りません。名前を統一した後も、似た機能を選び間違える場面が減ったかを確認します。同じ仕事をするツールの重複も、合わせて見直します。

引数の意味と入力検証を設計する

引数は、ツールを実行するために渡す対象や条件です。id だけでは何の識別子か不明なため、order_id や customer_id のように対象を示します。「山田さん」のような表示名と、システムが一意に対象を区別するIDも分けて扱います。同名の人がいると、名前だけでは更新対象を確定できないからです。

配送先変更なら、次のように項目ごとのルールを決めます。文字列、数値といった型や、必須かどうかをまとめた定義を「スキーマ」と呼びます。

住所を一つの自由文で受けるか、項目に分けるかも設計判断です。項目に分ければ不足を特定しやすくなりますが、利用する地域や業務に合う構成が必要です。特に更新では、「値を渡さない」と「空文字を渡す」を同じ意味にすると、意図せず登録内容を消すおそれがあります。

形式が正しい入力でも、その操作を実行してよいとは限りません。実行側では、注文の存在、利用者の操作権限、変更可能な配送状態を確認します。権限は実行環境の認証情報などで判定し、AIが渡した「承認済み」という文字だけを根拠に許可しない設計が必要です。

IDが不明なら検索し、候補が複数なら利用者への確認などで絞り込みます。もっともらしいIDを推測して実行してはいけません。変更する注文と住所を確定し、業務上必要な承認を経て実行します。参照後に発送が進むこともあるため、更新の直前にも変更可能かを判定します。

返り値・ページング・エラーを整える

返り値は、ツールから戻る実行結果です。注文参照なら、注文ID、配送状況、現在の配送先、変更可否とその理由があれば、次の判断につながります。顧客の過去の全注文や無関係な内部ログまで返すと、重要な情報が埋もれます。情報を減らす基準は短さではなく、次の行動に必要かどうかです。

人が読む注文名だけを残し、後続の更新で必要な注文IDを削ると、再検索が必要になります。説明しやすい表示名と、操作に使う識別子は役割が異なります。また、配送先変更を実行できない場合は、その理由まで返すと、AIは利用者に状況を説明しやすくなります。

情報量は、目的に応じて調整します。通常の確認には簡潔な応答を返し、詳しい調査には詳細形式を選べる設計が考えられます。検索では期間や配送状況で絞り込み、それでも件数が多い場合に、結果を複数回に分けるページングを使います。

たとえば最初の20件だけを返すなら、続きがあることと、次の取得に使う情報を明示します。次のページの位置を表す値は「カーソル」と呼ばれます。件数制限や文字数制限で結果を途中までにした場合も、その事実を伝えなければ、AIが「これで全件」と誤解する可能性があります。

成功、検索で該当がなかった状態、処理の失敗も区別します。単に Error と返す代わりに、原因と次に取れる行動を示します。

エラーを具体化しても、無関係な顧客情報やシステムの内部情報まで返す必要はありません。利用者とAIが次の行動を選ぶために必要な範囲で説明します。修正できる入力ミスと、権限や業務ルールで実行できない状態を分けることが、無駄な再試行を減らします。

更新時のタイムアウトには注意が必要です。応答が届かなくても、システム側では変更が終わっている場合があります。このときは成否が不明だと伝え、処理記録や対象の状態を確認してから再実行の要否を決めます。同じ要求を重複して処理しないための識別子なども実行側で扱い、無条件な再試行に頼らない設計にします。

実タスクで設計の改善を確かめる

設計を直したら、実際の仕事に近い課題で改善を測ります。ツールの説明を読んで分かりやすいと感じるだけでは、AIの誤選択が減ったかは分かりません。評価用のデータや環境を用意し、正しい対象を選べたか、必要な変更が完了したかを確認できる課題にします。

• 発送前の注文について、指定された新しい配送先へ正しく変更する。
• 同名の顧客や複数の注文があるとき、必要な確認をして対象を絞る。
• 注文IDや住所の一部が不足しているとき、推測せずに情報を補う。
• 発送済みなど変更できない注文では、更新を実行せず理由を説明する。
• 検索結果が多いとき、絞り込みや次ページの取得を使い、必要な注文を見つける。

ここでの成功は、必ず変更することではありません。変更禁止の注文なら、操作を止めて適切に案内することが正解です。最終回答の文章だけでなく、実行履歴と注文の状態も確認します。「変更しました」と答えていても、別の注文を変更していれば失敗として扱います。

改善前後では、モデルや指示、権限、評価データなどの条件をそろえます。完了率に加え、誤選択と入力エラーの件数、所要時間、呼び出し数、トークン量を比較します。トークン量は、AIが処理する文章などの量の目安です。応答を短くして処理量が減っても、必要な情報が欠けて再検索や失敗が増えれば、全体の改善とはいえません。

失敗した記録では、最初に判断がずれた場所を探します。別の機能を選んだなら名前や説明、違うIDを渡したなら引数の意味や対象の確定方法、途中の検索結果を全件と読んだなら返り値の表示を見直します。修正後は同じ課題で比較し、さらに別の顧客や言い回しでも試して、評価例だけに合う設計になっていないかを確かめます。

責務を明確にし、判断に必要な応答を返し、現実的な課題で評価する考え方は、Anthropicの技術記事「Writing effective tools for agents — with agents」でも説明されています。

まず担当する仕事を整理し、名前と説明、引数と検証、返り値の順に見直すと、問題の所在を追いやすくなります。設計だけで誤操作を完全になくすことはできません。実行側の権限確認や状態確認を組み合わせ、実タスクの結果を見ながら改善を続けることが大切です。

更新履歴