Azure AI エージェントにツールを追加する
Tip
詳細については、「 テキストと画像 」タブを参照してください。
エージェントがアクションを実行できるツールは、API の呼び出し、コードの実行、ファイルの検索、外部サービスの操作などです。 ツールがないと、エージェントは既に認識されている内容に基づいてのみテキストを生成できます。 ツールを使うと、世界に作用できるようになります。
Microsoft Agent Framework では、プロバイダーによってホストおよび管理されるサービス提供のツールと、自分で作成してエージェントに登録するカスタム関数ツールという 2 つの広範なカテゴリのツールがサポートされています。
サービスが提供するツール
Foundry プロバイダーを使用する場合は、追加の実装なしで、さまざまなホストされたツールを使用できます。 それらを有効にするには、それらをエージェント構成に含め、プロバイダーが実際の実行を処理します。
最も一般的に使用されるサービス提供ツールは次のとおりです。
| ツール | それが何をするか |
|---|---|
| コード インタープリター | 計算とデータ分析のために、サンドボックス環境でPythonコードを実行します |
| ファイル検索 | アップロードされたドキュメントを検索して情報を取得する |
| Web 検索 | インターネットから最新の情報を取得します。 |
| ホストされている MCP ツール | プロバイダー ランタイムによって直接呼び出される MCP (モデル コンテキスト プロトコル) サーバー |
| Azure AI 検索 | Foundry 接続を使用してAzure AI 検索 インデックスに対してクエリを実行する |
| Foundry ツールボックス | Foundry プロジェクトで管理される、ホストされているツール構成の名前付きバージョン付きバンドル |
Note
Azure AI 検索、Bingグラウンド、SharePointなど、一部のツールはプレビュー段階または試験段階です。 Foundry エージェントで使用できますが、他のプロバイダー間でサポートが制限されている可能性があります。
カスタム関数ツール
カスタム関数ツールを使用すると、内部 API の呼び出し、データベースのクエリ、計算の実行、Python関数で実行できるその他の任意のロジックを使用して、エージェントを拡張できます。
関数をツールとして登録するには、作成時に関数をエージェントに直接渡します。 フレームワークは、関数のシグネチャを検査し、関数の実行内容、期待されるパラメーター、および返される内容をモデルに伝えるスキーマを生成します。
モデルがツールを確実に呼び出すには、関数を明確に記述する必要があります。 Agent Framework では、次の 2 つの方法がサポートされています。
-
説明付きの型注釈 - Pythonの
Annotated型を各パラメーターのフィールドの説明と共に使用します。 関数の docstring は、ツールの説明として機能します。 -
@toolデコレーター — ツールの名前と説明をデコレーター引数として明示的に指定し、モデルに表示される内容を完全に制御できます。 入力構造を正確に制御する必要がある場合は、Pydantic モデルを使用して明示的なスキーマを指定することもできます。
どちらの場合も、フレームワークはスキーマの生成とツールの呼び出しを自動的に処理します。 モデルでツールを呼び出す必要があると判断されると、フレームワークは関数を実行し、最終的な応答が生成される前に結果をモデルに返します。
複数のツールを追加する
1 つのエージェントに複数のツールを登録できます。 エージェントの作成時に関数の一覧を渡すと、モデルは会話の各部分に最適なツールを自動的に選択します。 ルーティング ロジックを記述する必要はありません。フレームワークは、会話コンテキストと指定したツールの説明に基づいてツールオーケストレーションを処理します。
ツールの承認
実行前にツールの呼び出しで人間によるレビューが必要なシナリオでは、Agent Framework は ツール承認 パターンをサポートします。 ツールで承認モードが有効になっている場合、エージェントはその関数を呼び出す前に一時停止し、確認を要求します。 これは、元に戻せない、高価な、または機密データを含むアクションに役立ちます。 承認動作は、approval_mode デコレーターの @tool パラメーターを使用して、ツールごとに構成できます。
エージェントをツールとして使用する
エージェントは、あるエージェントを別のエージェントのツールとして使用して構成できます。 内部エージェントを関数ツールに変換し、それを外部エージェントに渡すと、特定のタスクを委任できます。 これにより、特殊なエージェントが特定のドメインを処理し、調整エージェントがそれらの間で要求をルーティングするモジュール設計が可能になります。これは、マルチエージェント モジュールでより詳細に調べられたパターンです。
カスタム ツールのベスト プラクティス
- 明確な説明を記述します。モデルが適切なツールを選択する機能は、指定した説明に完全に依存します。 関数の動作と使用するタイミングについて具体的に説明します。
- すべてのパラメーターに注釈を付けます。モデルが有効な呼び出しを構築できるように、各入力を記述します。特に、パラメーター名だけでは説明できない場合に使用します。
- 意味のあるデータを返します。ツールは、構造化された解釈可能な出力を返す必要があります。 モデルは、応答を生成する際に戻り値を直接使用します。
- ツールに集中して、各ツールで 1 つの作業を適切に行う必要があります。 複数の責任を 1 つの関数に結合すると、モデルが正しく呼び出すのが困難になります。
- エラーを適切に処理します。ツールで予期しない入力が発生した場合、または外部サービスが失敗した場合は、例外を発生させる代わりに有益なエラー メッセージを返して、モデルが役立つ応答を行えるようにします。