Microsoft Foundry

はじめに

必要な NuGet パッケージをプロジェクトに追加します。

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

2 種類のエージェント

Microsoft Foundry 統合では、次の 2 つの異なる使用パターンが公開されています。

タイプ	生成された型	説明	次の場合に使用します。
応答エージェント	ChatClientAgent	アプリは、 AIProjectClient.AsAIAgent(...)を介して実行時にモデル、命令、ツールをプログラムで提供します。 サーバー側エージェント リソースは作成されません。	エージェント定義を所有しており、シンプルで柔軟なセットアップが必要です。 これは、ほとんどのサンプルで使用されるパターンです。
Foundry エージェント (バージョニング済み)	FoundryAgent	サーバー管理 — エージェント定義は、Foundry ポータルを使用するか、 AIProjectClient.AgentAdministrationClientを使用してプログラムによって作成およびバージョン管理されます。 ProjectsAgentVersionまたはProjectsAgentRecordまたはAgentReferenceをAIProjectClient.AsAIAgent(...)に渡します。	サービス API を使用して Foundry ポータルで管理される厳密なバージョン管理されたエージェント定義が必要です

応答エージェント (直接推論)

AsAIAgentのAIProjectClientをモデルと命令と共に直接使用します。 これは、ほとんどのシナリオで推奨される開始点です。

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

このパスはコード優先であり、サーバーマネージド エージェント リソースは作成しません。

Foundry エージェント (バージョン付き)

AI Projects SDK のネイティブ AIProjectClient.AgentAdministrationClient API を使用して、バージョン管理されたエージェント リソースを取得し、 AsAIAgentでラップします。 エージェントは Foundry ポータルで直接作成および構成することも、 AIProjectClient.AgentAdministrationClientを使用してプログラムで構成することもできます。

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

エージェントの使用

ChatClientAgent (応答) とFoundryAgent (バージョン管理) の両方が標準AIAgent インスタンスであり、セッション、ツール、ミドルウェア、ストリーミングを含むすべての標準操作をサポートします。

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

エージェントを実行して操作する方法の詳細については、 エージェントの概要に関するチュートリアルを参照してください。

Tools

AIProjectClient.AsAIAgent(...) (応答パス) から作成された Foundry エージェントは、標準の Agent Framework ツール サーフェイスをサポートします。完全な一覧とサポートされている機能マトリックスについては、ツールの概要を参照してください。 バージョン管理されたエージェント定義 (FoundryAgent) から読み込まれた Foundry エージェントの場合、エージェントのツールはクライアントではなく Foundry エージェント定義によって所有されます。

ツール	メモ
関数ツール	Supported.
ツールの承認	Supported. フレームワークの関数呼び出しチャット クライアントによって提供されます。
コード インタープリター	Supported.
ファイル検索	Supported.
ホストされている MCP ツール	Supported.
ローカル MCP ツール	Supported.
Foundry ツールボックス	Supported.

ツールボックス

Pythonのファウンドリー

Pythonでは、Foundry 固有のすべてのクライアントが agent_framework.foundry の下に住むようになりました。

• agent-framework-foundry は、cloud Foundry コネクタ ( FoundryChatClient、 FoundryAgent、 FoundryEmbeddingClient、 FoundryMemoryProvider) を提供します。
• agent-framework-foundry-local は、ローカル モデルの実行に FoundryLocalClient を提供します。

PythonにおけるFoundryチャットおよびエージェントのパターン

シナリオ	Python図形	次の場合に使用します。
Foundry Responses エンドポイントを使用したプレーン推論	Agent(client=FoundryChatClient(...))	アプリはエージェント定義、ツール、会話ループを所有しており、Foundry プロジェクトにモデルをデプロイする必要があります。
Foundry エージェント サービスにおけるサービス管理エージェント	FoundryAgent(...)	Foundry ポータルまたはサービス API で作成および構成された PromptAgent または HostedAgent に接続する必要があります。

Installation

pip install agent-framework-foundry
pip install azure-identity

同じ agent-framework-foundry パッケージには、Foundry モデルとエンドポイントの埋め込みの FoundryEmbeddingClient も含まれています。

コンフィギュレーション

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

プロンプト エージェントの FOUNDRY_AGENT_VERSION を使用します。 ホストエージェントでは、これを省略できます。

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient と FoundryAgent はプロジェクトエンドポイントを使用します。 FoundryEmbeddingClient では、個別のモデル エンドポイントが使用されます。

適切なPythonクライアントを選択する

シナリオ	優先クライアント	メモ
Azure OpenAI リソース	OpenAIChatCompletionClient / OpenAIChatClient	OpenAI プロバイダー ページを使用します。
Microsoft Foundry プロジェクト推論	Agent(client=FoundryChatClient(...))	Foundry Responses エンドポイントを使用します。
MicrosoftのFoundryサービス管理エージェント	FoundryAgent	プロンプト エージェントと HostedAgents に推奨されます。
Microsoft Foundry モデル- エンドポイント埋め込み	FoundryEmbeddingClient	FOUNDRY_MODELS_ENDPOINTとFOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODELを使用します。
Foundry ローカル ランタイム	Agent(client=FoundryLocalClient(...))	Foundry Local を参照してください。

を使用してエージェントを作成する FoundryChatClient

FoundryChatClient は Foundry プロジェクト内のデプロイ済みモデルに接続し、Responses エンドポイントを使用します。 アプリが命令、ツール、セッション処理を所有する必要がある場合は、標準の Agent とペアリングします。

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient は、直接推論用の Foundry 優先のPython パスであり、ツール、構造化出力、ストリーミングをサポートします。

Tools

FoundryChatClient は、ホストされている Foundry ツールごとに静的ファクトリ メソッドを提供します。 ファクトリは、tools=でAgentに渡すか、client.get_response(..., tools=[...])に直接渡す SDK ツール オブジェクトを返します。 FoundryAgent では、エージェントのツールは Foundry エージェント定義自体に含まれています。FoundryAgent で何が機能し、何が機能しないかを参照してください。

ファクトリはクラス メソッドであるため、ツールを作成するためにインスタンスは必要ありません。

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

ツールのサポート

次の表に、Python FoundryChatClient が現在公開しているすべてのツールを示します。 FoundryAgent は同じツールで動作しますが、コードで渡すのではなく、Foundry エージェント定義で構成する必要があります。

ツール	ファクトリオン FoundryChatClient	地位	Detail
関数ツール	n/a — 任意の Python の callable または @ai_function を渡せます	GA	Python プロセスでローカルに呼び出されます。
ツールの承認	n/a — 既存のツールをラップします	GA	ホストされている MCP および関数ツールで動作します。
コード インタープリター	get_code_interpreter_tool	GA	Foundry でのサンドボックス化されたコード実行。
ファイル検索	get_file_search_tool	GA	Foundry ベクター ストアを使用してアップロードされたファイルを検索します。
Web 検索	get_web_search_tool	GA	Microsoft が管理する Bing を利用した Web グラウンディング。 Azure OpenAI モデルのみ。
画像生成	get_image_generation_tool	GA	Foundry でホストされているイメージの生成。
ホスト型MCP	get_mcp_tool	GA	Foundry によって呼び出されたリモート MCP サーバー。
ローカル MCP	n/a — 使用 MCPStreamableHTTPTool / MCPStdioTool	GA	プロセス内で実行されます。は、任意のクライアントで動作します。
Foundry ツールボックス	MCPStreamableHTTPTool ツールボックスMCPエンドポイントへ	GA	FoundryChatClientから MCP 経由で利用され、FoundryAgent上でサーバー側に接続されます。
Bingグラウンディング	get_bing_grounding_tool	Experimental	Bing Search リソースを使用した Bring Your Own Grounding。
Bingカスタム検索	get_bing_custom_search_tool	プレビュー	Bing のグラウンディングは、厳選されたドメイン リストに限定されます。
Azure AI 検索	get_azure_ai_search_tool	Experimental	Foundry 接続を使用してAzure AI 検索インデックスを検索します。
SharePoint	get_sharepoint_tool	プレビュー	回答をSharePoint のコンテンツに基づかせます。
Microsoft Fabric	get_fabric_tool	プレビュー	Fabric データ エージェントに対してクエリを実行します。
メモリ検索	get_memory_search_tool	プレビュー	Foundry マネージド メモリ ストアを検索します。
コンピュータ利用	get_computer_use_tool	プレビュー	エージェントがデスクトップまたはブラウザー環境を駆動できるようにします。
ブラウザーの自動化	get_browser_automation_tool	プレビュー	Azure Playwright 接続を介してブラウザーを駆動します。
エージェント間通信(A2A)	get_a2a_tool	プレビュー	別の A2A エージェントをツールとして呼び出します。

Web 検索バリアント

Foundry では、Bingに基づく 3 つの接地オプションが公開されています。 シナリオに一致するものを選択します。

• get_web_search_tool (GA) — セットアップ不要の既定値; Microsoft が管理する Bing リソース。 Azure OpenAI モデルのみ。 user_locationとsearch_context_sizeに制限されます。
• get_bing_grounding_tool (試験段階) — Bing Search Azure リソースを使用して独自の Grounding を使用します。 count、freshness、market、set_lang、および OpenAI Foundry 以外のモデルをサポートします。
• get_bing_custom_search_tool（プレビュー）— 独自の Bing Custom Search インスタンスを使用して、グラウンディングを厳選したドメインのセットに制限します。

3 つすべてが、Azureコンプライアンス境界の外側に検索データを送信します。 完全な比較については、 Web グラウンドの概要 を参照してください。

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

イメージの生成

get_image_generation_tool は Foundry のホストイメージ生成ツールを構成します。 モデルは応答で画像コンテンツを生成します。管理する追加のファイルはありません。

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Bing グラウンディング

get_bing_grounding_tool は、Grounding with Bing Search Foundry ツールをラップするものです。 自分で Bing Search リソースを使用して Grounding を作成し、Foundry プロジェクト接続として追加してから、接続 ID を渡します。

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Bing カスタム検索

get_bing_custom_search_tool では、グラウンディングが Bing Custom Search リソースで定義された許可リストに制限されます。

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Azure AI 検索

get_azure_ai_search_tool を使用すると、エージェントは Foundry プロジェクト接続を介してAzure AI 検索インデックスに対してクエリを実行できます。

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

SharePoint

get_sharepoint_tool は、Foundry SharePoint 接続を介して到達可能なSharePointコンテンツの回答を根拠とします。

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool は Foundry 接続を介してエージェントを Microsoft Fabric データ エージェントに接続し、エージェントがFabric データに関する質問に回答できるようにします。

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

メモリ検索

get_memory_search_tool では、エージェントは、必要に応じてユーザーまたはテナントをスコープとする Foundry マネージド メモリ ストアを検索できます。

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

コンピューターの使用

get_computer_use_tool は、コンピューター使用プレビュー ツールを構成します。モデルは、ポインターとキーボードの操作を発行することで、デスクトップまたはブラウザー環境を駆動できます。

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

ブラウザー自動化

get_browser_automation_tool は、Foundry 接続を介してエージェントを Azure Playwright Testing リソースに接続します。 エージェントは、Playwright を介して実際のブラウザーを駆動できます。

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

エージェント間コミュニケーション (A2A)

get_a2a_tool は、Foundry エージェントが呼び出すことができるように、リモート A2A エージェントをツールとして公開します。 保存されている A2A 接続の base_url (および必要に応じて agent_card_path) または project_connection_id を指定します。

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

一般的な A2A ガイダンス (検出、セッション、ストリーミング) については、「 エージェント間プロバイダー」ページを参照してください。

を使用して埋め込みを作成する FoundryEmbeddingClient

Foundry モデル エンドポイントからテキストまたは画像を埋め込む場合は、 FoundryEmbeddingClient を使用します。

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

サービスマネージド エージェントにFoundryAgentを使用して接続する

エージェント定義が Foundry に存在する場合は、 FoundryAgent を使用します。 これは、プロンプト エージェントと HostedAgents に推奨されるPython API です。

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

HostedAgent の場合は、 agent_version を省略し、代わりにホストされるエージェント名を使用します。

何が機能し、何が機能しないのか FoundryAgent

FoundryAgent は、Foundry に既に存在するエージェント (Prompt Agent または Hosted Agent) に接続します。 エージェントの定義 (命令とそのツール構成) は、Python コードではなく Foundry に存在します。 つまり、いくつかの Agentレベルの機能は、 Agent(client=FoundryChatClient(...)) やその他のチャット クライアントでサポートされるエージェントとは動作が異なります。

Tools

FoundryAgent(...) に渡されるツールの種類	Behavior
FunctionTool (ローカル Python呼び出し可能)	サポートされていますが、一致する関数定義が Foundry エージェントに既に存在する場合にのみサポートされます。 Foundry ランタイムは、エージェント定義に基づいてモデルに公開するツールを決定します。 モデルが関数を呼び出すと、Foundry はクライアントにツール呼び出しを返し、フレームワークはローカルの Python コール可能オブジェクトをあなたのプロセス内で（Foundry 内ではなく）呼び出し、その結果を送り返します。 FunctionToolクライアント側を渡すと、そのローカル実装が提供されます。Foundry エージェントで関数が宣言されていない場合、モデルでは呼び出されません。
ホストされるツール (Web 検索、コード インタープリター、ファイル検索、MCP、画像の生成など)	無視。 これらは、Foundry ポータルまたはサービス API を使用して、Foundry エージェント定義自体で構成する必要があります。 Foundry ランタイムはエージェント定義にアタッチされているツールについてのみ認識するため、クライアント側で渡しても効果はありません。

要するに、構築時に新しいツールを追加することはできません。 モデルが呼び出すことができるすべてのツール (ローカル Python関数を含む) は、Foundry のエージェント定義に既に含まれている必要があります。 FunctionToolを FoundryAgent(...) に渡すと、Foundry で定義された関数が呼び出されたときにPython プロセスで実行されるローカル実装のみが提供されます。新しいツールはエージェントに登録されません。

コンテキスト プロバイダー

context_providers=[...] は部分的にサポートされています。 コンテキスト プロバイダーが機能するかどうかは、プロバイダーが 実行 しようとした内容によって異なります。

コンテキスト プロバイダーの動作	FoundryAgentで動作しますか?
メッセージとして追加のコンテキスト (たとえば、取得されたメモリ、RAG スニペット、ユーザー プロファイル情報) を追加します。	Yes. 挿入されたコンテキストは要求と共に転送されます。
会話を永続的に保存または監視します（たとえば、対話ターンを外部ストアに書き込むなど）。	Yes. リクエスト/レスポンスの前後でローカルに実行されます。
ツールを動的に追加します (たとえば、 SkillsProvider、または invoking()からツールを返すプロバイダーなど)	いいえ。ツールが Foundry エージェント定義に既に含まれている場合を除きます。 Foundry ランタイムは、Foundry のエージェントにアタッチされているツールに対してモデルを実行します。ローカルにのみ存在するツールはモデルに公開されず、呼び出されません。

実行時に追加されるツールに依存する動的なツールの選択、スキルの読み込み、またはその他の動作が必要な場合は、代わりに Agent(client=FoundryChatClient(...)) を使用します。そのパスはモデル ループをローカルで所有し、ツールの種類とツールを追加するコンテキスト プロバイダーの完全なセットをサポートします。

実行オプション (default_options オプションと agent.run(...) オプション)

FoundryAgent(default_options=...)またはagent.run(..., **options)に渡すオプション (temperature、top_p、max_tokens、instructions、tool_choice、response_format、metadataなど) がすべて受け入れられているわけではありません。 Foundry のエージェント定義は信頼できるソースであるため、多くのオプションは暗黙的に無視されます。

プロンプト エージェントの場合、フレームワークは Foundry Responses API に要求を送信する前に、以下を明示的に削除またはオーバーライドします。

Option	FoundryAgentを使用した動作
model	無視。 モデルは Foundry エージェント定義から取得されます。
tools、 tool_choice、 parallel_tool_calls	リクエスト本文から削除されます。 ツールは Foundry エージェント定義で宣言する必要があります (前のセクションを参照)。 FunctionTool 呼び出し可能オブジェクトは引き続き関数呼び出しのためにローカルで接続されたままですが、ツールリスト自体はサービスに送信されません。
instructions およびシステム/開発者メッセージ	無視。 Foundry エージェント自身の指示が優先されます。 システム/開発者メッセージは、要求が送信される前にメッセージ 一覧から削除されます。
conversation_id	Used。また、Foundry エージェント セッションを参照する場合は、その Foundry エージェント セッションに対応付けられます。
extra_body	転送され、フレームワーク セットの agent_reference ペイロードとマージされます。
サンプリング パラメーター (temperature、 top_p、 max_tokens、 seed、 frequency_penalty、 presence_penalty、 stop、...)、 metadata、 user、 store、 response_formatなど。	Responses API に転送されます。 Foundry が実際にそれらを適用するかどうかは、エージェントとモデルの構成 (エージェント定義でオーバーライドまたは制約が可能) に依存するため、プロンプト エージェントに有効にしないでください。

ホストされるエージェントの場合、同じクライアント側の削除が適用されますが、それ以外のすべてが、特定のホストされるエージェントが実装する内容によって異なります。 ホストされるエージェントは、転送されるオプションを受け入れる、無視する、または再解釈することができます。 実行時オプションをアドバイザリとして扱い、呼び出しているホステッド エージェントに対する実際の動作を確認します。

デプロイされた (ホストされている) Foundry エージェントへの接続

サービス側セッション (/agents/{name}/sessions) を実行する HostedAgent の場合は、FoundryAgentでallow_preview=Trueを使用して、プレビュー応答画面にオプトインします。

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

基になるサービス セッションを自分で管理する必要がある場合 (たとえば、セッションを特定のテナントまたはユーザーにバインドする場合)、プレビュー AIProjectClient API を使用してセッションを作成し、 agent.get_session(...)でラップします。

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

エージェントの使用

FoundryChatClient と FoundryAgent はどちらも、ツールの呼び出し、セッション、ストリーミング応答など、標準の Python Agent エクスペリエンスと統合されます。 ローカル ランタイムの場合は、個別の Foundry ローカル プロバイダー ページを使用します。

ツールボックス

Foundry ツールボックスは、Microsoft Foundry プロジェクトで構成された、ホストされているツール構成 (コード インタープリター、ファイル検索、イメージ生成、MCP、Web 検索) の名前付きバージョン管理されたサーバー側バンドルです。 ツールボックスを使用すると、Foundry ポータルでツール構成を 1 回管理し、エージェント間で再利用できます。

Agent Framework は 消費 のみを対象とします。ツールボックスのバージョンの作成と更新は、Foundry ポータルまたは生の azure-ai-projects SDK (azure-ai-projects>=2.1.0) を使用して行われます。

FoundryAgent と FoundryChatClient

エージェントの種類	ツールボックスの動作
FoundryAgent (ホステッド)	ツールボックスの添付ファイルはサーバー側で行われます。 クライアント側の配線は必要ありません。
FoundryChatClient (直接推論)	get_toolbox()を使用してツールボックスをフェッチし、tools=として渡します。

2 つの消費パターン

Pattern	説明
ネイティブ (ホステッド ツール)	ツール構成は Foundry ランタイムで実行されます。 ツールボックスを tools=として直接渡します。
MCP	ツールボックスの MCP エンドポイントに対して MCPStreamableHTTPTool を使用します。 FoundryChatClientだけでなく、任意のチャット クライアントで動作します。

ツールボックスを取得する

FoundryChatClient.get_toolbox()を使用してツールボックスを取得します。

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

versionを省略すると、get_toolboxは 2 つの要求で既定のバージョンを解決します。 余分なラウンド トリップを回避するために、特定のバージョンをピン留めします。

toolbox = await client.get_toolbox("research_toolbox", version="v3")

暗黙的なフラット化

toolbox.toolsを記述する必要はありません。 フレームワークの normalize_tools は ToolboxVersionObject を認識し、自動的にフラット化します。 これらの作業はすべて次のとおりです。

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

フィルタリングツール select_toolbox_tools

ツールボックスに複数のツールがバンドルされているが、エージェントにサブセットのみが必要な場合は、 select_toolbox_tools を使用してフェッチ後にセットを絞り込みます。 これにより、不要なツール定義がモデルに送信されるのを回避できます。これにより、トークンの使用量が減り、公開する予定のないツールがモデルによって呼び出されるのを防ぐことができます。

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

ヘルパー関数 get_toolbox_tool_name(tool) と get_toolbox_tool_type(tool) は、それぞれツール エントリの選択名と生の種類を返します。 FoundryHostedToolTypeはTypeAlias (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str)として、include_types / exclude_typesでIDEによるガイド付き補完を行います。

MCP 消費経路

ツールボックスの MCP エンドポイント URL で MCPStreamableHTTPTool をポイントすることで、ツールボックスを MCP サーバーとして使用することもできます。

MCP エンドポイント URL は Foundry ポータルに表示されるか、次の形式に従います。

https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1

クライアントは Foundry ツールボックス エンドポイントに直接接続するため、 header_providerを介して Entra ID ベアラー トークンを使用して認証する必要があります。

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

制限事項

• ツールボックス内の MCP ツールでは、サーバー側認証が使用されます。 アップストリーム MCP サーバーへの認証は、 project_connection_id (Foundry プロジェクトで構成された OAuth 接続) を介して処理されます。 クライアントはアップストリーム サーバーのベアラー トークンを保持しません。
• ツールボックスを MCP サーバーとして使用するには、クライアント側の認証が必要です。 ツールボックスの MCP エンドポイントにMCPStreamableHTTPToolを指す場合、get_bearer_token_provider(credential, "https://ai.azure.com/.default")を通じて (例えば、header_provider経由で) Entra ID ベアラー トークンを指定する必要があります。
• 同意フローの処理はランタイムの問題です。 ツールボックス MCP ツールがCONSENT_REQUIRED中にagent.run()をトリガーした場合、ツールボックスのフェッチ中ではなく実行時に処理されます。

サンプル

Sample	説明
foundry_chat_client_with_toolbox.py	基本的なツールボックス フェッチ、バージョンのピン留め、ツールボックスの組み合わせ、フィルター処理
foundry_chat_client_with_toolbox_mcp.py	MCP 消費経路 MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	コンテキスト プロバイダーを使用したターンごとの動的ツールの選択