はじめに

AIエージェントは、外界と通信できるときに真に有用になる。REST APIはシステムが機能を提供する最も一般的な手段であるため、エージェントはオンデマンドでそれらを呼び出せる必要がある。課題は、ほとんどのAPIが自律的な意思決定者ではなく人間駆動のクライアント（ダッシュボード、モバイルアプリ）向けに設計されていることだ。エージェントがAPIを利用できるようになる前に、APIコントラクトをエージェントが理解し呼び出せる形式に変換する必要がある。

APIのツール化

エージェントの観点から見ると、ツールとは名前、説明、そして一連のパラメータを持つ関数である。エージェントから構造化された入力（たとえば都市名）を受け取り、構造化された結果を返す薄いラッパーを構築する。

import requests

def get_weather(city: str) -> dict:
    url = "https://api.example.com/weather"
    params = {"q": city, "units": "metric"}
    response = requests.get(url, params=params, timeout=10)
    response.raise_for_status()
    return response.json()

ラッパーはHTTPの詳細（ヘッダー、ステータスコード、JSON解析）を隠し、クリーンな関数シグネチャを公開する。エージェントに見えるのは関数名、そのdocstringまたは説明、そして型付きパラメータだけである。

エージェント向けの説明の構造化

説明は、いつどのようにツールを呼び出すかをエージェントに伝えるものである。優れたツール説明は3つの要素で構成される：ツールの機能を示す1行サマリー、いつ使うか（同じく重要なこととして、いつ使うべきかでないか）の注記、そしてフォーマットや制約を含むすべてのパラメータの説明。

{
  "name": "get_weather",
  "description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions outdoors. Do not use for forecasts beyond 24 hours.",
  "parameters": {
    "city": {
      "type": "string",
      "description": "City name in English, e.g. 'Hanoi' or 'Tokyo'"
    }
  }
}

説明は事実ベースで書く。「powerful」「advanced」といった誇張表現は避けよう。エージェントはマーケティング言語ではなく実用性に基づいて呼び出しを判断する。

レート制限・ページネーション・エラーの処理

APIは予測可能な形で失敗する。エージェントが生のスタックトレースではなく有用なフィードバックを得られるよう、ラッパーはこれらの失敗を処理しなければならない。

レート制限については、Retry-Afterヘッダーが存在する場合はそれを尊重し、429応答が繰り返された場合は指数バックオフを行う。無限待機を防ぐため、最大試行回数を設定したリトライループで呼び出しを囲む。

import time
import requests

def call_with_retry(url, params, max_attempts=3):
    for attempt in range(max_attempts):
        response = requests.get(url, params=params, timeout=10)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response.json()
    raise Exception("Rate limited after retries")

ページネーションについては、ラッパーがpageやcursorパラメータを受け取り、より多くのページが利用可能かどうかを明確なシグナルで返すように設計する。ページ取得を続けるかどうかはエージェントに判断させよう。コストと関連性については、ハードコードされたループよりもエージェントの方がうまく推論できる。

エラーについては、例外を盲目的に送出するのではなく構造化オブジェクトを返す。ステータスコード、人間が読める簡潔な理由、可能であれば復旧方法のヒントを含める。これにより、エージェントはパラメータを修正して再試行したり、ツールを切り替えたり、問題をユーザーに報告したりできる。

まとめ

すべてのAPIを、3つの層を持つツールとして扱おう：クリーンな関数シグネチャ、エージェントが選択に使える precise な説明、そしてHTTPの厄介な現実（リトライ、ページネーション、エラー報告）を処理する堅牢なラッパー。ラッパーとは、不安定な外部サービスと、適切な判断のために予測可能な入力を必要とする推論エージェントとの間のコントラクトである。

よくある間違い

いつ使うべきでないかを指定しない説明でAPIをラップしてしまうこと。生の例外をエージェントに伝播させ、構造化エラーオブジェクトを返さないこと。ページネーションループをハードコードし、エージェントがページをスキップしたり早期に停止したりできないようにすること。Retry-Afterヘッダーを無視し、固定の遅延を使ってより速くBANされてしまうこと。