AI 2026年4月16日

AIエージェントツール設計の7原則：信頼性を高める実践的アプローチ

AIエージェントは現代のソフトウェア開発において急速に存在感を増しています。しかし、その有用性はツール設計の質に大きく左右されます。AnthropicとOpenAIが公開しているベストプラクティスをもとに、信頼性の高いエージェントを構築するための7つの設計原則を解説します。

① 単一責任の原則（Single Responsibility）

各ツールは1つのことだけを担当させる——これが設計の出発点です。

悪い例として、manage_filesという関数がファイルの作成・読み込み・削除・移動をすべて処理するケースがあります。この設計はエージェントに「何でもできるツール」を与えているように見えて、実際には誤用のリスクを高めます。エージェントがどの操作を実行しているかを追跡しにくくなり、デバッグも困難になります。

python

# 悪い例
def manage_files(action, path, content=None):
    if action == "create": ...
    elif action == "delete": ...  # 誤って呼ばれるリスク

# 良い例
def read_file(path: str) -> str: ...
def write_file(path: str, content: str) -> None: ...
def delete_file(path: str) -> None: ...

責任を分離することで、ツールごとの動作が予測しやすくなり、ログや監査も容易になります。

② 冪等性の原則（Idempotency）

同じ入力を何度渡しても、同じ結果が返ること。これが冪等性です。

エージェントはネットワーク障害やタイムアウト後に同じ操作を再試行することがよくあります。冪等でないツールは、その際に重複作成・二重課金・データ破壊といった問題を引き起こします。

python

# 非冪等（危険）
def create_user(email: str):
    db.insert("users", {"email": email})  # 2回呼ぶと重複エラー

# 冪等（安全）
def create_or_update_user(email: str):
    db.upsert("users", {"email": email}, conflict="email")

特に外部APIや課金処理を伴うツールでは、冪等性キー（idempotency key）の設計が必須です。

③ エラー防止設計（Error Prevention by Design）

エラーハンドリングを「後付け」にするのではなく、設計段階から組み込む考え方です。

良いエラー設計には3つの層があります。

型と制約による防止：引数の型を厳密に定義し、無効な値が渡せないようにします。PythonであればLiteral型やPydanticが有効です。

実行前の検証：ファイルを削除する前に「そのファイルが存在するか」「権限があるか」を確認します。

復旧可能なエラーメッセージ：エラーが起きたとき、エージェントが次に何をすべきかわかるメッセージを返します。"Error: file not found" よりも "Error: '/tmp/data.csv' が見つかりません。list_files() で利用可能なファイルを確認してください" のほうがはるかに有用です。

④ 最小権限の原則（Least Privilege）

エージェントには、タスクを完了するために必要最小限の権限だけを与えます。

読み取り専用のレポート生成タスクに書き込み権限を与えてはいけません。顧客データの参照だけが必要なエージェントに、削除操作のツールを渡してはいけません。

この原則はセキュリティ上の理由だけでなく、エージェントの「迷い」を減らすためにも重要です。使えるツールが少ないほど、エージェントは適切な選択をしやすくなります。

実装上は、ツールセットをタスクのスコープに応じて動的に絞り込む設計が推奨されます。

⑤ 明示的な入出力の定義（Explicit I/O Contracts）

ツールの引数と戻り値を、型・制約・意味まで含めて明文化します。

エージェントがツールを選択する際、参照できるのはツールの説明文（description）とスキーマだけです。曖昧な定義は誤用の温床になります。

python

def search_orders(
    customer_id: str,         # "cust_" プレフィックス必須（例: "cust_123"）
    status: Literal["pending", "shipped", "delivered"],
    date_from: date,          # ISO 8601形式
    limit: int = 10           # 最大100
) -> list[Order]:
    """
    顧客の注文を検索します。
    Returns: 注文リスト。該当なしの場合は空リストを返します（例外ではない）。
    """