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

エージェントの使用

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