Microsoft Foundry

はじめに

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

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

2 種類のエージェント

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

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

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));

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

ツールボックス

Pythonのファウンドリー

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

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

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

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クライアントを選択する

を使用してエージェントを作成する 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 パスであり、ツール、構造化出力、ストリーミングをサポートします。

を使用して埋め込みを作成する 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 を省略し、代わりにホストされるエージェント名を使用します。

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

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

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

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

基になるサービス セッションを自分で管理する必要がある場合 (たとえば、セッションを特定のテナントまたはユーザーにバインドする場合)、プレビュー 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

2 つの消費パターン

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

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()をトリガーした場合、ツールボックスのフェッチ中ではなく実行時に処理されます。

サンプル