AIエージェントのツール設計9原則を解説！従来のAPI設計との決定的な違いとは

AIエージェントの実用化が進む中、ツール設計の重要性が再認識されています。しかし、従来のAPI設計の常識をそのまま適用すると、エージェントが期待通りに動作しない事態に陥ります。

AnthropicやOpenAI、Composioといった最前線の企業が公開する設計ガイドラインには、人間の開発者ではなく「LLMが理解し、正しく呼び出せる」ための独自の原則が詰まっています。本記事では、これらの実践知見を整理し、AIエージェント向けツール設計の9つの原則を深掘りします。

1. スキーマ定義は「LLMの理解」を最優先する

従来のAPI設計では、スキーマは主に型安全性やバリデーションのために存在しました。しかしAIエージェント向けツールでは、**LLMがスキーマを読んで正しい判断を下せるか**が最重要です。

2. ツールの粒度設計：分割 vs 統合の判断基準

ツールを細かく分割すべきか、統合すべきか。この判断は従来のマイクロサービス設計とは異なる基準で行います。

**分割すべきケース**:

**統合すべきケース**:

3. 命名規則と名前空間の戦略

LLMはツール名から機能を推測します。そのため、命名は人間以上に重要です。

4. strict modeによるエラー削減

OpenAIやAnthropicは、ツール呼び出し時の「strict mode」をサポートしています。これを有効にすることで、スキーマ違反を事前に検知し、無駄なAPI呼び出しを削減できます。

5. 冪等性キーの実装

AIエージェントは同じツールを複数回呼び出す可能性があります。重複実行を防ぐため、冪等性キーの実装は必須です。

def create_order(order_id: str, idempotency_key: str, items: list):
    # idempotency_keyで重複チェック
    if is_duplicate(idempotency_key):
        return get_cached_response(idempotency_key)
    # 処理実行
    result = process_order(order_id, items)
    cache_response(idempotency_key, result)
    return result

6. エラーレスポンス設計の重要性

エラーメッセージは、LLMが次のアクションを判断する材料になります。

7. レスポンスサイズの最適化

LLMのコンテキストウィンドウは有限です。不要な情報を含めると、後続の判断精度が低下します。

8. ツール実行の可視性確保

デバッグとモニタリングのため、ツール実行をトレースできる仕組みが必要です。

9. バージョニング戦略

ツールの仕様変更は、すでに学習済みのエージェントに影響します。

従来のRESTful API設計との本質的な違い

従来のAPI設計では、「人間の開発者が仕様書を読んで理解する」ことが前提でした。しかしAIエージェント向けツールでは、**仕様書とコードの境界が曖昧**になります。スキーマそのものがLLMへの指示書として機能するため、descriptionフィールドの一文が成否を分けることすらあります。

ChatGPTのFunction CallingとClaudeのTool Useを比較すると、両者ともJSON Schemaベースですが、パラメータの解釈精度には微妙な差があります。Claudeは長文のdescriptionをより正確に理解する傾向がある一方、ChatGPTはシンプルで構造化された情報を好みます。この違いを踏まえ、マルチモデル対応する場合は、最大公約数的な設計が求められます。

メリットと注意点の両面分析

**メリット**:

**注意点**:

適用範囲と導入タイミング

これらの原則は、特に以下のようなケースで威力を発揮します。

逆に、単純な1ツール1タスクのエージェントや、社内実験レベルであれば、ここまで厳密な設計は不要かもしれません。ただし、将来的な拡張を見据えるなら、初期段階から原則を意識しておくことを強く推奨します。

アクション1: 既存ツールのスキーマレビュー

現在使用しているツールのスキーマを見直してみましょう。以下のチェックリストを使います。

アクション2: ツールの粒度を再評価する

現在のツールセットをリストアップし、以下の観点で統合・分割を検討してください。

1. **使用頻度の分析**: よく一緒に呼ばれるツールは統合候補

2. **エラー率の確認**: エラーが多いツールは、パラメータが複雑すぎる可能性

3. **LLMの選択ログ分析**: 似たツール間で選択ミスが多い場合、命名や説明の改善が必要

アクション3: 簡易的な冪等性キーの実装

まずは重要度の高いツール（課金処理、データ変更など）から冪等性対応を始めます。

import hashlib
import json
from functools import wraps

response_cache = {}

def idempotent(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        # パラメータからキーを生成
        key_data = json.dumps({"args": args, "kwargs": kwargs}, sort_keys=True)
        idempotency_key = hashlib.sha256(key_data.encode()).hexdigest()
        
        if idempotency_key in response_cache:
            return response_cache[idempotency_key]
        
        result = func(*args, **kwargs)
        response_cache[idempotency_key] = result
        return result
    return wrapper

@idempotent
def create_payment(amount: float, currency: str, customer_id: str):
    # 決済処理
    pass

この情報は @ohno さんの投稿を参考にしています。