Microsoft Agent Framework のエージェントを Foundry でホストされるエージェントとしてホストする

Microsoft Agent Framework ホスティングパッケージを使用して、Foundry でホストされるエージェントのプロトコルを介して Agent Framework エージェントを公開します。ホスティングパッケージを使用すると、コード内でエージェントロジックを保持できます。Foundry は、ホストされるランタイム、セッション、スケール、ID、プロトコルエンドポイントを管理します。

この記事では、最小限の Agent Framework エージェントを作成し、応答または呼び出しプロトコルを使用してエージェントを公開し、HTTP を使用してテストし、Azure Developer CLI を使用して Foundry にデプロイします。

前提条件

Azure サブスクリプション。無料で作成できます。
フォンドリープロジェクト。
gpt-4.1やgpt-4oなど、デプロイされたチャットモデル。
ホストされたエージェントをデプロイするプロジェクトにおけるFoundry Project Managerロール。詳細については、「ホストされたエージェントのデプロイ」を参照してください。
Azure CLI がサインインしました (az login) ため、DefaultAzureCredential は認証できます。

Python 3.10 以降。

.NET 10 SDK 以降。

パッケージをインストールする

Agent Framework と Foundry ホスティングパッケージをインストールします。

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

agent_framework_foundry_hosting パッケージは、Foundry プロトコル用のホストサーバーを提供します。

ResponsesHostServer OpenAI と互換性のある /responses エンドポイント用。
InvocationsHostServer ジェネリック /invocations エンドポイントの場合。

Agent Framework と Foundry ホスティングパッケージをプロジェクトに追加します。

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

呼び出しプロトコルの場合は、Invocations サーバーパッケージも追加します。

dotnet add package Azure.AI.AgentServer.Invocations

これらのパッケージは、Foundry プロトコルのホスト拡張機能を提供します。

OpenAI 互換の/responsesエンドポイント用のAddFoundryResponsesとMapFoundryResponses。
汎用/invocationsエンドポイント用のAddInvocationsServerとMapInvocationsServer。

ホスティングプロトコルを選択する

ホストされるエージェントは、1 つ以上のプロトコルを公開できます。ほとんどの会話エージェントの応答から始めます。

プロトコル	エンドポイント	次の場合に使用します。
Responses	`/responses`	OpenAI と互換性のあるチャット、ストリーミング、応答履歴、会話スレッドが必要です。
呼び出し	`/invocations`	カスタム JSON シェイプ、Webhook スタイルのエンドポイント、または非会話処理が必要です。

プロトコルの動作とセッションの背景については、「ホストされたエージェント」および「ホストされたエージェントセッションの管理」を参照してください。

環境変数を構成する

ローカル開発のプロジェクトエンドポイントとモデルのデプロイ名を設定します。

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

PowerShell では次のとおりです。

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Foundry でホストされているエージェントと同じコードを実行すると、プラットフォームは実行時に FOUNDRY_PROJECT_ENDPOINT と AZURE_AI_MODEL_DEPLOYMENT_NAME を挿入します。

応答プロトコル

ストリーミング、応答履歴、会話スレッドを含む OpenAI と互換性のあるチャットエンドポイントが必要な場合は、応答プロトコルを使用します。

応答ホストを作成する

Foundry モデルを使用する最小限の Agent Framework エージェントを使用して、 main.py という名前のファイルを作成します。

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

このスニペットの機能:FoundryChatClientを介して Foundry モデルによってサポートされる Agent Framework エージェントを作成し、エージェントをResponsesHostServerに渡します。ホストは HTTP サーバーを起動し、 POST /responsesを介してエージェントを公開します。既定では、サーバーはポート 8088にバインドされます。

リファレンス: Microsoft Agent Framework のドキュメント

アプリをローカルで実行します。

python main.py

応答プロトコルを使用して Foundry モデルを使用する最小限の Agent Framework エージェントを使用して、 Program.cs ファイルを作成します。

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

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

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

このスニペットの機能: Foundry プロジェクトクライアントから AIAgent を作成し、Foundry Responses ホストとして AddFoundryResponses に登録し、 POST /responses エンドポイントを MapFoundryResponsesにマップします。既定では、ホストはポート 8088で機能します。

リファレンス: AIProjectClient | DefaultAzureCredential

アプリをローカルで実行します。

dotnet run

応答エンドポイントをテストする

ストリーミング以外の応答要求をローカルサーバーに送信します。

Bash：

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

サーバーは、応答テキストと応答 ID を含む JSON オブジェクトで応答します。ストリーミング応答の場合は、 stream を true に設定します。ホストは、 response.created、 response.output_text.delta、 response.completedなどの Responses API サーバー送信イベントを出力します。

複数ターンの会話

会話を続けるには、次の要求の previous_response_id フィールドに前の応答 ID を渡します。

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

エージェントが Foundry で実行されている場合、同じパターンがホストされるエージェント応答エンドポイントを介して動作します。後で同じホストされたサンドボックスファイルシステムも必要になる場合は、 agent_session_id を含めるか、 conversation ID を使用します。詳細については、「ホストされたエージェントセッションの管理」を参照してください。

呼び出しプロトコル

呼び出し元が Responses API 要求図形を使用できない場合、またはシナリオがチャット会話でない場合は、呼び出しプロトコルを使用します。呼び出しホストは、 agent_session_id クエリパラメーターと応答ヘッダーを使用してセッションの状態を管理します。

呼び出しホストを作成する

応答の例と同じエージェントセットアップを使用しますが、InvocationsHostServerではなく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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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()


if __name__ == "__main__":
    main()

このスニペットの機能:POST /invocationsを使用してエージェントフレームワークエージェントをホストします。ホストは、 agent_session_id クエリパラメーターと応答ヘッダーを使用してセッションごとの状態を管理します。

リファレンス: Microsoft Agent Framework のドキュメント

呼び出しプロトコルでは、実装した InvocationHandler を使用して各要求を処理します。呼び出しサーバーとハンドラーを登録し、エンドポイントをマップします。

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

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

このスニペットの機能: 呼び出しサーバーサービスと InvocationHandler 実装を登録し、 /invocations エンドポイントをマップします。 MyInvocationHandlerを実装して、各要求の処理方法を定義します。完全なハンドラーの例については、.NET呼び出しのサンプルを参照してください。

リファレンス: AddInvocationsServer

呼び出しエンドポイントをテストする

ローカルサーバーに要求を送信します。

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

複数ターンの会話の場合は、応答ヘッダーの agent_session_id 値を次の要求の agent_session_id クエリパラメーターとして再利用します。

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

プラットフォームには、呼び出しプロトコルの会話履歴は格納されません。 agent_session_id クエリパラメーターを使用して、後で呼び出しを同じホストされたサンドボックスにルーティングします。

Deploy

Azure Developer CLI (azd) を使用してデプロイします。このフローでは、サンプルマニフェストと Docker を使用してエージェントコンテナーイメージをビルドし、Foundry でホストされるエージェントランタイムにロールアウトします。

ホスト型エージェントのデプロイには、プロジェクトにおける Foundry Project Manager ロールが必要です。詳細については、「ホストされたエージェントのデプロイ」を参照してください。

Azure Developer CLI 拡張機能をインストールする

サンプルを初期化する前に、AI エージェント拡張機能をインストールしてサインインします。

azd ext install azure.ai.agents
azd auth login

サンプルの Dockerfile で宣言されたコンテナーイメージ azd ai agent run ビルドするため、Docker はローカルで実行されている必要があります。コマンドの詳細については、Azure Developer CLI リファレンスを参照してください。

サンプルマニフェストから初期化する

新しいフォルダーを作成し、サンプルマニフェストから初期化します。マニフェスト URL を、使用するサンプルのものに置き換えます。

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.manifest.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml

azd ai agent initの指示に従います。 Foundry プロジェクトとモデルのデプロイがまだない場合は、初期化フローで作成を進めることができます。

Azure リソースをプロビジョニングする

初期化されたプロジェクトで新しい Foundry プロジェクトとモデルのデプロイを使用する場合は、最初にAzureリソースをプロビジョニングします。

azd provision

このコマンドは、他のリソースの中でも、Foundry インスタンス、モデルデプロイを含む Foundry プロジェクト、Application Insights インスタンス、およびホストされるエージェントイメージのコンテナーレジストリを含むリソースグループを作成します。

コンテナーをローカルで実行する

azdを使用してエージェントホストをローカルで実行します。

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!"}'

Foundry にデプロイする

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

azd deploy

デプロイによって、エージェントがコンテナーイメージにパッケージ化され、プロビジョニングされたコンテナーレジストリにプッシュされ、Foundry でホストされているエージェントランタイムにロールアウトされます。

Foundry ホスティングインフラストラクチャは、次のようなランタイム環境変数をエージェントに挿入します。

FOUNDRY_PROJECT_ENDPOINT: エージェントがデプロイされている Foundry プロジェクトのエンドポイント URL。
AZURE_AI_MODEL_DEPLOYMENT_NAME: azd ai agent init中に選択されたモデルデプロイ名。
APPLICATIONINSIGHTS_CONNECTION_STRING: プロジェクトの Application Insights インスタンスの接続文字列。

デプロイの概念、アクセス許可、および管理の詳細については、「ホストされたエージェントのデプロイ」および「ホストされたエージェントのライフサイクルの管理」を参照してください。

Troubleshooting

このチェックリストを使用して、Agent Framework でホストされるエージェントを開発する際の一般的な問題を診断します。

ホストされているコンテナーでモデルに到達できない

ホストされるエージェントのバージョンに AZURE_AI_MODEL_DEPLOYMENT_NAMEが含まれていること、およびエージェント ID に Foundry プロジェクトを呼び出すアクセス許可があることを確認します。プラットフォームセット FOUNDRY_PROJECT_ENDPOINT。コードは Foundry で実行するときにその変数を読み取る必要があります。

会話状態が継続されない

応答プロトコルの場合は、後で previous_response_id または conversation ID を渡します。

呼び出しプロトコルの場合、プラットフォームには会話履歴は格納されません。 agent_session_id クエリパラメーターを使用して、後で呼び出しを同じホストされたサンドボックスにルーティングします。

プロトコルバージョンの不一致

アップグレード後に要求が失敗した場合は、マニフェストとホスティングパッケージの両方でプロトコルバージョン 2.0.0 が使用されていることを確認します。プロトコルバージョン 1.0.0 と 2.0.0 には互換性がありません。

次のステップ

ホストされるエージェントをデプロイする

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-03