Foundry がホストするエージェント

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

Agent Framework ホスティング統合を使用すると、最小限のコードで Foundry Responses または Invocations プロトコルを使用して、Agentでラップされたワークフローを含むWorkflow.as_agent()を公開できます。

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

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

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

Note

Python agent-framework-foundry-hosting統合はプレリリースです。 マネージド ホスティング サービスMicrosoft Foundry Hosted Agents が一般提供されています。

前提条件

• 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 以降

プレリリース ホスティング パッケージ、Foundry クライアント、Azure認証パッケージをインストールします。

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

Foundry では、プラットフォームは呼び出し元のユーザー コンテキストと呼び出しコンテキストを提供します。ホスティング インフラストラクチャでは、それらを使用してユーザーごとの状態を分離し、要求コンテキストを Foundry サービスに転送します。 ローカル実行はそのプラットフォーム コンテキストを受け取らないので、アプリケーションは必要に応じて独自の ID と状態制御を提供する必要があります。

応答プロトコル

応答プロトコルは、ほとんどのエージェントに推奨される開始点です。 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.",
)

server = ResponsesHostServer(agent)
server.run()

ResponsesHostServerはエージェントをラップし、Foundry Responses プロトコルを介して公開します。 非ワークフロー エージェントの場合、既定の history_source="agent_server" では、構成済みのエージェント サーバー応答プロバイダーがモデルの履歴ソースとして使用されます。 ホストは、クライアントが既定で履歴を格納するときに、ダウンストリーム モデル サービスが 2 つ目のコピーを保持できないようにします。

既定の履歴ソースと、load_messages=Trueを含むHistoryProviderを組み合わせないでください。 また、 conversation_id、 previous_response_id、またはダウンストリーム サービス継続オプション conversation 設定しないでください。 ホストは、重複する履歴を防ぐために、これらの構成を拒否します。

エージェントの履歴プロバイダーまたはダウンストリーム モデル サービスが会話履歴を管理する必要がある場合は、 ResponsesHostServer(agent, history_source="agent") を使用します。 このモードでは、エージェント サーバーからの現在の要求入力のみが渡され、エージェントの履歴とサービス ストレージの動作が保持されます。 カスタム SupportsAgentRun 実装では、このモードを使用する必要があります。 store パラメーターは分離されたままです。応答 API の入力と出力を両方のモードで保持する応答プロバイダーを選択します。

ホストは指定されたエージェントを所有し、ホスティング固有のコンテキスト プロバイダーを追加する場合があります。 エージェントを別のホストで再利用したり、ホスト構築後に直接呼び出したりしないでください。

状態を保持し、長時間にわたる会話を処理する

ResponsesHostServer は、デフォルトで Foundry を利用したストアを設定します。 非ワークフロー エージェントの場合、 AgentSessionStoreProvider は FoundryAgentSessionStoreを提供します。 ワークフロー エージェントの場合、 CheckpointStoreProvider は FoundryCheckpointStoreを提供します。 FunctionApprovalStoreProvider は、保留中の承認用の FoundryFunctionApprovalStore を提供します。 これらのストアでは、ホスト環境では Foundry State Store が使用され、ローカルで実行する場合はローカルの Agent Server の状態が使用されます。

history_source="agent"では、構成されたセッション ストアは、InMemoryHistoryProviderからのメッセージを含め、AgentSessionによって保持されるプロバイダーの状態を保持します。

ストレージをカスタマイズするには、 StoreProvider を agent_session_store_provider または function_approval_store_providerに渡します。 checkpoint_store_provider を ContextScopedStoreProvider に渡します。 たとえば、独自の非ワークフロー エージェント セッション ストアを使用する SessionStore と StoreProvider[SessionStore] を実装します。

azure.ai.agentserver.responsesからResponsesServerOptionsをインポートし、options パラメーターを使用してResponsesHostServerに渡します。 実行時間の長い会話オプションは、エージェントの種類によって異なります。

Capability	エージェントの種類	要件と動作
回復性のあるバックグラウンド応答	ワークフローのみ	ResponsesServerOptions(resilient_background=True)を設定します。 store=trueとbackground=trueを使用して応答要求を送信します。 再起動後、ホストは最新の永続的ワークフロー チェックポイントを再開するか、チェックポイントが存在しない場合は元の入力を再生します。 ホストによって管理されるため、ワークフローでチェックポイント ストレージを構成しないでください。 最後に永続化されたチェックポイント以降の処理は再実行される可能性があるため、外部副作用は冪等にしてください。
制御可能な会話	非ワークフローのみ	ResponsesServerOptions(steerable_conversations=True)を設定し、store=trueを使用して応答要求を送信します。 同じ conversation 値を再利用して、1 つの線形チェーンをオンのままにします。 または、直前の previous_response_id を送信し、解決された agent_session_idを保持します。 ホストは、フォークを作成する古い先行タスクを拒否します。

ResponsesHostServer は、非ワークフロー エージェントに対して回復性を備えたバックグラウンド応答を有効にした場合、またはワークフロー エージェントに対して制御可能な会話を有効にした場合に、RuntimeError を発生させます。 完全な実装については、 カスタム ストレージ、 回復性の高い実行時間の長いワークフロー、および 実行時間の長いエージェントサンプル を参照してください。

OAuth 同意要求を処理する

Foundry でホストされる MCP ツールでユーザーの同意が必要な場合、 ResponsesHostServer は oauth_consent_request 出力項目を含む不完全な応答を返します。 そのconsent_linkをユーザーに提示し、ユーザーが同意を完了した後、不完全な応答のIDをprevious_response_idとして続行します。 ホストは、この再試行のエージェント セッションを保持し、絶対 HTTPS 同意リンクのみを公開します。

呼び出しプロトコル

呼び出しプロトコルを使用すると、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()

Warning

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

完全な呼び出しのデプロイについては、 Foundry でホストされる Telegram サンプルを参照してください。 ホストされたエージェント Webhook の前に API Management が配置され、永続的な会話履歴にマネージド ID、Key Vault、Cosmos DB が使用されます。

Note

Foundry でホストされるエージェントの Go サポートは近日公開予定です。 最新の状態については、 Agent Framework Go リポジトリ を参照してください。

Tip

ホストされるエージェント プロジェクトの例については、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>

Tip

マニフェストには、ローカル 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と永続的なホスティング
• A2A エージェントをセルフホストする
• Python のサンプル
• C# のサンプル