API呼び出しエージェントの理解、構築、最適化ガイド To-DoリストAPI version: 1.0.0 paths: /tasks: post: summary: 新しいタスクを追加 requestBody: required: true

技術企業における人工知能の役割は急速に進化している。人工知能のユースケースは、受動的な情報処理から、タスクを実行できるプロアクティブなエージェントへと進化している。2025年3月にGeorgianとNewtonXが実施した世界的なAI導入調査によると、成長段階および企業企業の91%の技術エグゼクティブが、エージェント型AIを使用または使用予定であると報告されている。

API呼び出しエージェントは、このエージェントへのシフトの主要な例である。API呼び出しエージェントは、Large Language Models（LLM）を利用して、ソフトウェアシステムとのやり取りを行う。たとえば、自然言語コマンドを正確なAPI呼び出しに変換することで、エージェントはリアルタイムデータを取得したり、ルーティンワークを自動化したり、他のソフトウェアシステムを制御したりすることができる。この機能により、AIエージェントは人間の意図とソフトウェア機能の間に役立つ中間者となる。

企業は現在、API呼び出しエージェントを以下のさまざまなドメインで使用している。

• 消費者アプリケーション: AppleのSiriやAmazonのAlexaのようなアシスタントは、日常のタスクを簡素化するために設計されており、スマートホームデバイスの制御や予約を行うことができる。
• 企業ワークフロー: 企業は、データの取得、レポートの生成、内部システムからの情報の統合などの繰り返しタスクを自動化するために、APIエージェントを展開している。
• データ取得と分析: 企業は、APIエージェントを使用して、独自のデータセット、サブスクリプションベースのリソース、パブリックAPIへのアクセスを簡素化し、インサイトを生成している。

この記事では、エンジニアリング中心のアプローチを使用して、API呼び出しエージェントの理解、構築、最適化について説明する。この記事の内容は、GeorgianのAI Labが実施した実践的な研究と開発に基づいている。AI Labの研究における主な質問は、「組織がAPIを持っている場合、自然言語を使用してそのAPIと通信できるエージェントを構築するための最も効果的な方法は何か？」である。

API呼び出しエージェントの動作と、パフォーマンスのためにこれらのエージェントを成功裏に設計およびエンジニアリングする方法について説明する。最後に、エンジニアリングチームがAPI呼び出しエージェントを実装するために使用できる体系的なワークフローを提供する。

I. 主要定義:

• APIまたはアプリケーション・プログラミング・インターフェイス: 異なるソフトウェア・アプリケーションが通信し、情報を交換できるようにするルールとプロトコルのセット。
• エージェント: 環境を認識し、決定を下し、特定の目標を達成するために行動するように設計されたAIシステム。
• API呼び出しエージェント: 自然言語の指示を正確なAPI呼び出しに変換する特殊なAIエージェント。
• コード生成エージェント: ソフトウェア開発を支援するAIシステムで、コードの作成、変更、デバッグを行う。関連しているが、ここでの焦点は、APIを「呼び出す」エージェントに主に置かれている。人工知能はこれらのエージェントを「構築」するのにも役立つ。
• MCP（モデル・コンテキスト・プロトコル）: Anthropicによって開発されたプロトコルで、LLMが外部ツールやデータソースに接続して利用する方法を定義する。

II. コア・タスク: 自然言語をAPIアクションに変換する

API呼び出しエージェントの基本的な機能は、ユーザーの自然言語のリクエストを解釈し、それを1つまたは複数の正確なAPI呼び出しに変換することである。これには、以下のプロセスが含まれる。

1. 意図の認識: ユーザーの目標を理解すること、たとえ曖昧に表現されていたとしても。
2. ツールの選択: 使用可能なオプションのセットから、意図を満たすことができる適切なAPIエンドポイント（または「ツール」）を識別すること。
3. パラメータの抽出: ユーザーのクエリから、選択されたAPI呼び出し（または呼び出し）に必要なパラメータを識別して抽出すること。
4. 実行とレスポンスの生成: API呼び出しを行い、レスポンスを受け取り、それをまとめて回答または次のアクションを生成すること。

たとえば、「Hey Siri、今日の天気はどうですか？」というリクエストでは、エージェントは天気APIを呼び出す必要があることを識別し、ユーザーの現在の位置（または位置の指定を許可）を決定し、天気情報を取得するAPI呼び出しを構築する必要がある。

「Hey Siri、今日の天気はどうですか？」というリクエストの場合、サンプルのAPI呼び出しは以下のようになる。

GET /v1/weather?location=New%20York&units=metric

この変換プロセスには、自然言語の曖昧さや、エージェントがマルチステップのやり取り全体でコンテキストを維持する必要性などの初期の課題が含まれる。

たとえば、エージェントは、前の会話や前のAPI呼び出しの結果を「覚えておく」ことが必要であることが多い。これは、コンテキストの喪失が、明示的に管理されなければ、一般的な障害モードとなる。

III. ソリューションのアーキテクチャ: 主要コンポーネントとプロトコル

有効なAPI呼び出しエージェントを構築するには、構造化されたアーキテクチャ・アプローチが必要である。

1. エージェントの「ツール」の定義

LLMがAPIを使用するには、そのAPIの機能をLLMが理解できるように説明する必要がある。各APIエンドポイントまたは関数は、通常、「ツール」として表現される。強力なツール定義には、以下のものが含まれる。

• ツールの目的と機能の明確な自然言語による説明。
• 入力パラメータ（名前、タイプ、必須またはオプション、説明）の正確な仕様。
• ツールが返す出力またはデータの説明。

2. モデル・コンテキスト・プロトコル（MCP）の役割

MCPは、LLMが外部ツールやデータソースを使用するためのより標準化された、堅牢な方法を提供するため、重要な要素である。

MCPの標準化は、ツールの統合が容易になり、ツール定義の再利用性が向上し、エージェントやモデル間で再利用できるようになるため、有益である。さらに、エンジニアリングチームにとって、OpenAPI仕様のような明確に定義されたAPI仕様から始めることがベストプラクティスである。Stainless.aiのようなツールは、これらのOpenAPI仕様をMCP構成に変換するのに役立つ。

3. エージェント・フレームワークと実装の選択

エージェントを構築するのに役立ついくつかのフレームワークがある。

• Pydantic: 独自のエージェント構造内で入力と出力のデータ構造を定義し、信頼性のためにタイプセーフティを確保するのに役立つ。多くのカスタムエージェント実装は、構造的完全性のためにPydanticを利用する。
• LastMileのmcp_agent: MCPと連携するように設計されたフレームワークで、Anthropicのような場所での研究に基づいて、有効なエージェントを構築するための慣行に沿った構造を提供する。
• 内部フレームワーク: また、AIコード生成エージェント（CursorやClineのようなツールを使用）を使用して、エージェント、ツール、および周囲のロジックのボイラープレートコードを書くのに役立つことがある。GeorgianのAI Labが企業と協力してagentic実装を行った経験から、これは非常に最小限のカスタムフレームワークを作成するのに役立つことがわかっている。

IV. 信頼性とパフォーマンスのためのエンジニアリング

エージェントが信頼性とパフォーマンスを持ってAPI呼び出しを行うことを保証するには、集中したエンジニアリング努力が必要である。2つの方法は、データセットの作成と検証、およびプロンプトエンジニアリングと最適化である。

1. データセットの作成と検証

エージェントのトレーニング（該当する場合）、テスト、最適化には、高品質のデータセットが必要である。これには、代表的な自然言語のクエリと対応する期待されるAPI呼び出しシーケンスまたは結果が含まれる。

• 手動作成: データセットを手動で作成すると、精度と関連性が高くなるが、時間がかかる可能性がある。
• 合成生成: データをプログラム的に生成するか、LLMを使用することで、データセットの作成を拡張することができるが、これには重大な課題がある。Georgian AI Labの研究では、合成的に生成されたAPI呼び出しとクエリの正確性と現実的な複雑さを確保することが非常に難しいことがわかった。生成された質問は、非常に簡単または不可能に複雑であることが多く、繊細なエージェントのパフォーマンスを測定することが難しかった。合成データの検証は、絶対に重要である。

重要な評価のために、小規模で高品質の、手動で検証されたデータセットは、大規模でノイズの多い合成データセットよりも、より信頼性の高い洞察を提供することが多い。

2. プロンプトエンジニアリングと最適化

LLMベースのエージェントのパフォーマンスは、エージェントの推論とツールの選択を導くプロンプトによって大きく影響を受ける。

• 有効なプロンプティングには、エージェントのタスクを明確に定義し、利用可能なツールを説明し、パラメータの抽出を構造化することが含まれる。
• DSPyのようなフレームワークを使用した体系的な最適化は、パフォーマンスを大幅に向上させることができる。DSPyを使用すると、エージェントのコンポーネント（例：思考生成、ツールの選択、パラメータのフォーマットのモジュール）を定義し、コンパイラのようなアプローチでデータセットからの少量の例を使用して、これらのコンポーネントの最適化されたプロンプトまたは構成を見つけることができる。

V. 有効なAPIエージェントへの推奨パス

堅牢なAPI呼び出しAIエージェントを開発することは、反復的なエンジニアリング・ディシプリンである。Georgian AI Labの研究の結果に基づいて、以下の体系的なワークフローを使用することで、成果を大幅に改善することができる。

1. 明確なAPI定義から始める: 利用するAPIのための、構造化されたOpenAPI仕様から始める。
2. ツールのアクセスを標準化する: OpenAPI仕様をMCPに変換する。Stainless.aiのようなツールを使用して、APIをエージェントが理解して使用できるようにする標準化された方法を作成する。
3. エージェントを実装する: 適切なフレームワークまたはアプローチを選択する。これには、データモデリングにPydanticを使用することや、MCPと連携するように設計されたLastMileのmcp_agentのようなフレームワークを使用することが含まれる。
   • これを行う前に、MCPをClaude DesktopやClineのようなツールに接続し、手動でこのインターフェイスを使用して、汎用エージェントがどれくらいよくMCPを使用できるか、MCPを正しく使用するのに何回のイテレーションが必要か、実装中に時間を節約できるその他の詳細を確認することを検討する。
4. 高品質の評価データセットをキュレーションする: 手動でデータセットを作成するか、徹底的に検証する。これは、信頼性の高いテストと最適化に不可欠である。
5. エージェントのプロンプトとロジックを最適化する: DSPyのようなフレームワークを使用して、エージェントのプロンプトと内部ロジックを改良し、データセットを使用して精度と信頼性の向上を推進する。

VI. ワークフローのイラストレーション例

以下は、API呼び出しエージェントの構築のための推奨ワークフローの簡略化された例である。

ステップ1: 明確なAPI定義から始める

シンプルなTo-Doリストを管理するAPIを想定する。
openapi: 3.0.0

info:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: タスクを作成しました

get:

summary: すべてのタスクを取得

responses:

‘200’:

description: タスクのリスト

ステップ2: ツールのアクセスを標準化する

OpenAPI仕様をMCP構成に変換する。Stainless.aiのようなツールを使用して、APIをエージェントが理解して使用できるようにする標準化された方法を作成する。

ステップ3: エージェントを実装する

Pydanticを使用して、MCPツールに対応する関数を作成する。次に、LLMを使用して、自然言語のクエリを解釈し、適切なツールとパラメータを選択する。

ステップ4: 高品質の評価データセットをキュレーションする

データセットを作成する。

ステップ5: エージェントのプロンプトとロジックを最適化する

DSPyを使用して、プロンプトを改良し、明確な指示、ツールの選択、パラメータの抽出に焦点を当て、カーキュレーションされたデータセットを使用して評価と改善を行う。

これらの構成要素を統合することで、エンジニアリングチームは、より有能で信頼性が高く、メンテナンスが容易なAPI呼び出しAIエージェントを構築することができる。