カスタム ツールを統合する方法

エージェントのカスタム ツールは、シナリオに最適な方法に応じて、いくつかの方法で定義できます。 エージェントが使用できるように会社に Azure Functions が既に実装されている場合や、公開されている OpenAPI 仕様によって、エージェントが探している機能を提供している場合があります。

関数呼び出し

関数呼び出しにより、エージェントはユーザー入力に基づいて定義済みの関数を動的に実行できます。 この機能は、エージェントがデータの取得やユーザー クエリの処理などの特定のタスクを実行する必要があり、エージェント内からコードで実行できるシナリオに最適です。 関数が他の API を呼び出して追加情報を取得したり、プログラムを開始したりする場合があります。

例: 関数の定義と使用

まず、エージェントが呼び出すことができる関数を定義します。 たとえば、偽の降雪追跡機能を次に示します。

import json

def recent_snowfall(location: str) -> str:
    """
    Fetches recent snowfall totals for a given location.
    :param location: The city name.
    :return: Snowfall details as a JSON string.
    """
    mock_snow_data = {"Seattle": "0 inches", "Denver": "2 inches"}
    snow = mock_snow_data.get(location, "Data not available.")
    return json.dumps({"location": location, "snowfall": snow})

Azure AI SDK を使用して関数をエージェントに登録します。

# Define a function tool for the model to use
function_tool = FunctionTool(
    name="recent_snowfall",
    parameters={
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "The city name to check snowfall for."},
        },
        "required": ["location"],
        "additionalProperties": False
    },
    description="Get recent snowfall totals for a given location.",
    strict=True,
)

# Add the function tool to a list of tools for the agent
tools: list[Tool] = [function_tool]

# Create your agent with the toolset
agent = project_client.agents.create_version(
    name="snowfall-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions="You are a weather assistant tracking snowfall. Use the provided functions to answer questions.",
        tools=tools,
    )
)

エージェントは、プロンプトに関数で取得できる情報が必要であると判断したときに、 recent_snowfall を動的に呼び出すようになりました。

Azure Functions

Azure Functions には、リアルタイム処理用のサーバーレス コンピューティング機能が用意されています。 この統合は、イベントドリブン ワークフローに最適です。これにより、エージェントは HTTP 要求やキュー メッセージなどのトリガーに応答できます。

例: キュー トリガーでの Azure Functions の使用

まず、Azure 関数を開発してデプロイします。 この例では、特定の場所の降雪をフェッチする関数が Azure サブスクリプションにあるとします。

Azure 関数が配置されたら、それを Azure 関数ツールとしてエージェント定義に追加します。

tool = AzureFunctionTool(
    azure_function=AzureFunctionDefinition(
        input_binding=AzureFunctionBinding(
            storage_queue=AzureFunctionStorageQueue(
                queue_name="STORAGE_INPUT_QUEUE_NAME",
                queue_service_endpoint="STORAGE_QUEUE_SERVICE_ENDPOINT",
            )
        ),
        output_binding=AzureFunctionBinding(
            storage_queue=AzureFunctionStorageQueue(
                queue_name="STORAGE_OUTPUT_QUEUE_NAME",
                queue_service_endpoint="STORAGE_QUEUE_SERVICE_ENDPOINT",
            )
        ),
        function=AzureFunctionDefinitionFunction(
            name="queue_trigger",
            description="Get weather for a given location",
            parameters={
                "type": "object",
                "properties": {"location": {"type": "string", "description": "location to determine weather for"}},
            },
        ),
    )
)

agent = project_client.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions="You are a helpful weather assistant. Use the provided Azure Function to get weather information for a location when needed.",
        tools=[tool],
    ),
)

エージェントは、ストレージ キューを介して Azure 関数に要求を送信し、結果を処理できるようになりました。

OpenAPI 仕様

OpenAPI で定義されたツールを使用すると、エージェントは標準化された仕様を使用して外部 API と対話できます。 この方法により、API の統合が簡略化され、さまざまなサービスとの互換性が確保されます。 Foundry Agent Service では、OpenAPI 3.0 で指定されたツールが使用されます。

例: OpenAPI 仕様の使用

最初に、API を記述する JSON ファイル (この例では weather_openapi.jsonと呼ばれます) を作成します。

{
  "openapi": "3.1.0",
  "info": {
    "title": "get weather data",
    "description": "Retrieves current weather data for a location based on wttr.in.",
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "https://wttr.in"
    }
  ],
  "auth": [],
  "paths": {
    "/{location}": {
      "get": {
        "description": "Get weather information for a specific location",
        "operationId": "GetCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "description": "City or location to retrieve the weather for",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
          "name": "format",
          "in": "query",
          "description": "Always use j1 value for this parameter",
          "required": true,
          "schema": {
            "type": "string",
            "default": "j1"
          }
        }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Location not found"
          }
        },
        "deprecated": false
      }
    }
  },
  "components": {
    "schemes": {}
  }
}

次に、OpenAPI ツールをエージェント定義に登録します。

from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails

with open(weather_asset_file_path, "r") as f:
      openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))

tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_weather,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

agent = project_client.agents.create_version(
    agent_name="openapi-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions="You are a weather assistant. Use the API to fetch weather data.",
        tools=[openapi_tool],
    ),
)

エージェントは OpenAPI ツールを使用して気象データを動的にフェッチできるようになりました。

使用可能なカスタム ツール オプション (またはその任意の組み合わせ) のいずれかを使用すると、Foundry Agent Service を使用して、強力で柔軟でインテリジェントなエージェントを作成できます。 これらの統合により、外部システム、リアルタイム処理、スケーラブルなワークフローとのシームレスな対話が可能になり、ニーズに合わせてカスタマイズされたカスタム ソリューションを簡単に構築できます。