ファウンドリホストエージェント

Microsoft Foundry Agent Service の Hosted agents を使用すると、コンテナー化されたアプリケーションとして Agent Framework エージェントをMicrosoftマネージド インフラストラクチャにデプロイできます。 プラットフォームは、スケーリング、セッション状態の永続化、セキュリティ、およびライフサイクル管理を処理するため、エージェントのロジックに集中できます。

Agent Framework ホスティング統合を使用すると、任意の Agent またはワークフローを取得し、最小限のコードで Foundry Responses または Invocations プロトコルを介して公開できます。

ホストされているエージェントを使用する場合

必要に応じ、Foundry でホストされるエージェントを選択します。

• マネージド インフラストラクチャ - コンテナー、Web サーバー、またはスケーリング ルールを自分で構成する必要はありません。
• 組み込みのセッション管理 — プラットフォームは、ターンとアイドル期間にわたって $HOME およびアップロードされたファイルを保持します。
• 専用エージェント ID — デプロイされたすべてのエージェントは、モデル、ツール、ダウンストリーム サービスに安全にアクセスするための独自の Entra ID を取得します。
• OpenAI と互換性のあるエンドポイント - クライアントは、応答プロトコルを介して任意の OpenAI 互換 SDK を使用してエージェントと対話できます。

メモ

Foundry でホストされているエージェントは現在プレビュー段階です。 最新の可用性、制限、および価格については、 Foundry でホストされるエージェントのドキュメント を参照してください。

前提条件

• Azure サブスクリプション
• Azure 開発者 CLI (azd) と AI エージェントの拡張機能: azd ext install azure.ai.agents

ローカル テストの場合は、次のものが必要です。

• Microsoft Foundry プロジェクト（たとえば、モデル展開を含む gpt-4o）
• Azure CLI のインストールと認証 (az login)

• .NET 10 SDK 以降

ホスティング NuGet パッケージをインストールします。

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease

• Python 3.10 以降

ホスティング Python パッケージをインストールします。

pip install agent-framework agent-framework-foundry-hosting

応答プロトコル

応答プロトコルは、ほとんどのエージェントに推奨される開始点です。 OpenAI と互換性のある /responses エンドポイントが公開され、プラットフォームによって会話履歴、ストリーミング、セッションのライフサイクルが自動的に管理されます。

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

AgentHost.CreateBuilderは、Foundry ホスティング環境用に事前構成されたアプリケーション ホストを作成します。 AddFoundryResponsesはエージェントを Responses プロトコル ハンドラーに登録し、MapFoundryResponses/responses HTTP エンドポイントをマップします。

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

ResponsesHostServerはエージェントをラップし、Foundry Responses プロトコルを介して公開します。 storeでFalseをdefault_optionsに設定すると、ホスティング インフラストラクチャによって履歴が自動的に管理されるため、会話履歴の重複を回避できます。

呼び出しプロトコル

呼び出しプロトコルを使用すると、HTTP 要求と応答を完全に制御できます。 OpenAI と互換性のないカスタム ペイロード、非会話型処理、またはストリーミング プロトコルが必要な場合に使用します。

C# の呼び出しプロトコルでは、受信要求を処理するカスタム InvocationHandler を実装します。

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

AddInvocationsServer メソッドは、Invocations プロトコル サービスを登録します。 InvocationHandlerを実装して、エージェントが各要求を処理する方法を定義します。

軽量セットアップの場合は、InvocationsHostServer パッケージのagent_framework_foundry_hostingを使用します。 エージェントは、 ResponsesHostServer と同様にラップされ、セッション管理が自動的に処理されます。

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

要求処理を完全に制御するには、InvocationAgentServerHost パッケージのazure.ai.agentserver.invocationsを直接使用し、独自の呼び出しハンドラーを実装します。

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

Warnung

カスタム ハンドラーの例のメモリ内セッション ストアは、再起動時に失われます。 運用環境では永続ストレージ (Cosmos DB など) を使用します。

ヒント

ホストされるエージェント プロジェクトの例については、Python サンプルまたは C# サンプルを参照してください。 または、 azd ai agent init コマンドを使用して、新しいホステッド エージェント プロジェクトを最初からスキャフォールディングします。 詳細な手順については、この クイック スタート ガイド を参照してください。

ローカルでの実行

Azure Developer CLI (azd) は、ホストされたエージェントをローカルで実行してテストする最も簡単な方法を提供します。

プロジェクトを初期化する

新しいフォルダーを作成し、サンプル マニフェストから初期化します。

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

ヒント

マニフェストには、ローカル YAML ファイルへのパスまたはリモート マニフェストへの URL を指定できます。

環境変数の設定

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

エージェント ホストを実行する

azd ai agent run

エージェント ホストは、 http://localhost:8088で開始されます。

エージェントを呼び出す

azd ai agent invoke --local "Hello!"

または、 curlを使用します。

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

または、PowerShell で次の手順を実行します。

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Foundry へのデプロイ

エージェントをローカルで検証したら、Microsoft Foundry にデプロイします。

1. リソースをプロビジョニング する (Foundry プロジェクトがまだない場合):

   azd provision
   

   これにより、Foundry インスタンス、プロジェクト、モデル デプロイ、Application Insights、コンテナー レジストリを含むリソース グループが作成されます。

2. エージェントをデプロイします。

   azd deploy
   

   これにより、エージェントがコンテナー イメージとしてパッケージ化され、Azure Container Registryにプッシュされ、Foundry Agent Service にデプロイされます。

Foundry ホスティング インフラストラクチャは、実行時に次の環境変数をエージェント コンテナーに自動的に挿入します。

Variable	説明
FOUNDRY_PROJECT_ENDPOINT	Foundry プロジェクトのエンドポイント URL。
AZURE_AI_MODEL_DEPLOYMENT_NAME	モデルの展開名（azd ai agent initで設定）。
APPLICATIONINSIGHTS_CONNECTION_STRING	テレメトリ用の接続文字列としての Application Insights。

デプロイ後、エージェントは専用の Foundry エンドポイントを介してアクセスでき、Foundry ポータルからテストすることもできます。

次のステップ

ホスト型エージェントの概念

• Foundry SDK を使用してホストされるエージェントをデプロイする
• ホストされているエージェントを管理する
• Azure Functions (Durable) ホスティング
• A2A ホスティング
• Python のサンプル
• C# のサンプル