agent-interface-design

エージェントインターフェースの設計

例は1つの方法を教える一方で、ほかの方法をひそかに締め出します。ツールの呼び出し方を3通り見せると、モデルはその3通りを出力する傾向があります。適切に設計されたインターフェースなら、可能性の全体像を一度に教えられます。パラメーターが可能なことを示し、説明が期待されることを示せば、書き足すものはほとんどありません。

手順

1. 再設計する前に、ツールが実際にどのように誤用されているかを調べます。トランスクリプト、ログ、またはユーザーからの苦情を確認します。誤用はまずインターフェースに現れる症状であり、ドキュメントに現れる症状はその次です。修正はたいてい、説明文の追加ではなく、名前や型の変更です。
2. 意味をパラメーターに持たせます：
   • 自由記述を受け付けるのではなく、選択肢を列挙します。pending | in_progress | completed のステータスなら、文章で説明しなくても状態遷移全体を示せます。
   • 実装ではなく意図に基づいて名前を付け、正しい呼び出しが自然に読めるようにします。
   • 型システムで可能な限り、無効な状態を表現できないようにします。誤りを表現できないパラメーターなら、その誤りについて警告する必要もありません。
3. 動作に関する指示は、ツール自身の説明に、使用する箇所でのみ記載します。同じガイダンスをグローバルな前置きでも繰り返すと、コードベースに矛盾が生じます。
4. 使用例を追加したくなったら、それを診断のきっかけにします。たいてい、パラメーターの仕様が不十分だということです。まずインターフェースを修正します。特注のクエリ構文など、本当に推測できない形式に限り、例を残します。
5. 常時利用するものと、必要なときに見つけられればよいものを決めます。ほとんどのターンで必要なツールはコンテキストに含め、まれにしか使わないツールは必要になるまでコストがかからないよう、必要に応じて見つけられるようにします。
6. 最後に、設計上なお許容される誤りを明示し、それを許容できるほど低コストで済むか、明示的なガードレールが必要かを述べます。

ガードレール

• パラメーターの意味を説明しなければならない説明文は、パラメーターの名前を見直す必要があるということです。
• 取り消せない操作や重大な結果を伴う操作は、上記すべての例外です。その場合は、洗練さよりも明示的な制約と確認を優先します。
• 既存の呼び出し元をすべて確認する前に、シグネチャを再設計してはいけません。
• 目標は簡潔さではなく、表現力です。実際の動作を伝えていた説明を削ることは、長くなった説明よりも悪い結果です。