セルフホスト エージェント フレームワーク アプリケーション

セルフホスティングを使用すると、独自の ASP.NET Core アプリケーション、コンテナー、サービス、またはランタイムで Agent Framework エージェントまたはワークフローを実行できます。 アプリケーションは、ルーティング、ID、承認、要求ポリシー、ストレージ、デプロイ、スケーリングを制御します。 サポートする必要があるクライアントに基づいて、ホストにプロトコル統合を追加します。

エージェント エンドポイントを既存のアプリケーション インフラストラクチャと統合する必要がある場合は、このオプションを使用します。 Microsoft Foundry に代わってエージェントを実行させる場合は、Foundry Hosted Agents を参照してください。 Azure Functionsトリガーまたは永続的な実行が必要な場合は、「Durable Extension」を参照してください。

Important

.NET ホスティング パッケージはプレリリースです。 プレリリース バージョンを明示的にインストールし、運用環境のデプロイを更新する前にリリース ノートを確認してください。

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

ホスティング ヘルパーが提供するもの

Microsoft.Agents.AI.Hosting パッケージは、エージェントとワークフローを .NET 汎用ホストと統合します。

• AddAIAgent は、名前付き AIAgent を依存性注入に登録します。
• AddWorkflow は、名前付きワークフローを登録します。 標準エージェント インターフェイスを介してプロトコル統合でワークフローを使用できるようにするチェーン AddAsAIAgent 。
• IHostedAgentBuilder は、そのエージェントに関連付けられているホスティング サービスを構成します。
• AgentSessionStore 必要に応じて、アプリケーションまたはプロトコル指定の継続 ID によって AgentSession インスタンスを読み込んで保存します。

ホスティング パッケージは、HTTP サーバーまたはプロトコル レジストリではありません。 アプリケーションは、ホストされているエージェントとワークフローを選択し、サービスを構成し、必要なプロトコル エンドポイントを追加します。

ASP.NET Coreとの統合

共有ホスティング パッケージでは、.NET汎用ホストと依存関係の挿入が使用されます。 HTTP サーバーの場合は、ASP.NET Core アプリケーションを作成し、公開するエンドポイントのプロトコル固有のパッケージを追加します。 これらのパッケージは、依存関係注入から名前付き AIAgent インスタンスを解決し、ASP.NET Core のルート マッピングを追加します。

たとえば、OpenAI ホスティング パッケージは、応答エンドポイントを介して構成されたエージェントを公開できます。

dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

完全な構成については、 OpenAI と互換性のあるエンドポイントを 参照してください。

アプリケーションは、ミドルウェア パイプライン、認証、承認、要求検証、許可されたモデル オプション、および永続ストレージに対して引き続き責任を負います。 HTTP 以外のホストでは、ASP.NET Coreプロトコル エンドポイントを追加することなく、共有ホスティング サービスを使用できます。

サーバーにプロトコルを追加する

アプリケーションで必要なプロトコル統合を選択します。

プロトコル	Integration
OpenAI と互換性のあるエンドポイント	Chat Completions および Responses 互換の HTTP エンドポイント
A2A	エージェント間の検出、メッセージング、タスク エンドポイント
AG-UI	Web エージェント アプリケーションのイベント ストリーミング エンドポイント

ホストされているセッションを保持する

AgentSessionStore 永続化は、これを使用するホスティング統合ではオプトイン方式です。 ストアが構成されていない場合、これらの統合は要求ごとに新しいセッションを作成できますが、以前の要求からサーバー所有のセッション状態を回復することはできません。

Important

MAF には汎用の永続セッションストアは含まれません。 運用環境では、アプリケーションに適したストレージに基づく AgentSessionStore 実装を提供します。

永続化実装を依存関係の挿入 (DI) に登録し、ホステッド エージェントに渡してください。 開発中は、メモリ内ストアを条件付きで使用できます。

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

この例では、 MyAgentSessionStore は、アプリケーションによって提供される永続的な実装です。 開発ブランチは、信頼されたユーザーが 1 人のローカル環境を想定しており、分離を無効にする唯一のパスです。 運用ブランチでは、既定の分離動作が保持されます。 セキュリティで保護されたセッション継続の説明に従って分離キー プロバイダーを構成します。

InMemoryAgentSessionStore は、プロセスが終了したときにすべてのセッションを失い、アプリケーション インスタンス間で状態を共有しません。 セッションを保持するために、永続ストレージを使用して独自の AgentSessionStore を実装します。

AgentSessionStoreは、非同期の保存、取得、および削除操作を実装します。 所有元の AIAgent と、ホスティング統合またはアプリケーションが所有するルートによって選択された不透明な継続 ID を受け取り、各 get 操作で独立した AgentSession インスタンスを返す必要があります。 継続 ID をカスタム ストアの不透明なキーとして扱います。ID の解釈方法はプロトコル固有です。

永続的な実装には、次の構造があります。 各スタブを、選択したストレージ システムの操作に置き換えます。

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

agent.Idと不透明なsessionStoreIdの両方によるキー レコード。 GetSessionAsync は、すべての呼び出しで独立したセッション インスタンスを返す必要があります。は、シリアル化された状態を格納するときに、所有エージェントのセッション シリアル化 API を使用します。 永続化されたセッションには機密データを含めることができるため、適切なアクセス制御と暗号化で保護します。

AgentSessionStore は、メッセージ交換メッセージだけでなく、ホストされた要求によって選択された完全な AgentSession を保持します。 エージェント スタックに応じて、セッションには、サービスで管理される会話 ID、フレームワークで管理されたチャット履歴、メモリまたはコンテキスト プロバイダーの状態、キューに置かれたメッセージ、保留中の承認、および実行全体で存続する必要があるその他の状態を含めることができます。

履歴プロバイダーは、 会話メッセージを格納する場所を制御します。 履歴がセッション状態で保持されている場合、セッションを永続化すると、その履歴も保持されます。 外部履歴プロバイダーは、メッセージを個別に格納します。セッションは、参照または関連するプロバイダーの状態を保持できます。

セキュリティで保護されたセッションの継続

継続 ID は、再開するセッションを識別します。呼び出し元がそのセッションを所有していることを証明するものではありません。 クライアント提供の ID を受け入れる前に、認証されたユーザー、テナント、またはその他の承認境界によって永続化されたセッションのスコープを設定します。 IsolationKeyScopedAgentSessionStoreは、AgentIsolationKeyProviderから分離キーを取得し、それをプロトコル継続 ID と組み合わせて、結果のスコープ ID を基になるストアに渡します。 その結果、2 つの異なる分離キーの下で同じ継続 ID が 2 つの異なる保存されたセッションに解決され、呼び出し元は、その呼び出し元の分離キーで保存されたセッションのみを取得できます。

クレーム ベース認証を使用する ASP.NET Coreアプリケーションの場合は、プレリリース Microsoft.Agents.AI.Hosting.AspNetCore パッケージをインストールし、クレーム ベースの分離プロバイダーを登録し、セッション ストアで分離を有効にしたままにします。

dotnet add package Microsoft.Agents.AI.Hosting.AspNetCore --prerelease

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

既定では、 UseClaimsBasedAgentIsolation は ClaimTypes.NameIdentifier 要求を使用します。 ストアによって提供されるすべての呼び出し元で安定していて一意である場合にのみ、別の要求を構成します。 分離プロバイダーは要求を認証しません。ASP.NET Core認証と承認を個別に構成します。 既定の厳密な分離動作では、現在のプリンシパルが構成済みの要求を提供しない場合、セッション アクセスは失敗します。

HTTP 以外のホストまたは別のテナント モデルの場合は、カスタム AgentIsolationKeyProviderを登録します。 既定の WithInMemorySessionStore() および WithSessionStore(...) オーバーロードは、構成されたストアを IsolationKeyScopedAgentSessionStoreでラップします。

次のステップ

OpenAI と互換性のあるエンドポイントを追加する

より深く進む:

• A2A でエージェントをホストする
• AG-UI を使用して Web エージェント アプリケーションを構築する
• Foundry がホストするエージェント

Note

現在、Go ではセルフホスティング プロトコル ヘルパーを使用できません。

セルフホスティングを使用すると、独自の Web アプリケーション、コンテナー、サービス、またはランタイムで Agent Framework エージェントまたはワークフローを実行できます。 アプリケーションは、ルーティング、ID、承認、要求ポリシー、ストレージ、デプロイ、スケーリングを制御します。 サポートする必要があるクライアントに基づいて、1 つ以上のプロトコル統合をそのサーバーに追加します。

エージェント エンドポイントを既存のアプリケーション インフラストラクチャと統合する必要がある場合は、このオプションを使用します。 Microsoft Foundry に代わってエージェントを実行させる場合は、Foundry Hosted Agents を参照してください。 Azure Functionsトリガーまたは永続的な実行が必要な場合は、「Durable Extension」を参照してください。

これらのパッケージの設計により、開発者は最大限の柔軟性を得ることができます。 つまり、Responses API を使用してエージェントを公開するホストを構築し、他の目的でパラメーターを悪用する (つまり、 temperature を top_pにマップする) 場合は、これを行うことができます。 セッションを保存しない場合は、これを行うことができます。呼び出し元がエージェントの完全な実行を制御できるようにする場合は、それも可能です。 私たちは干渉せず、一般的なケース向けのヘルパーを提供し、それ以外はあなたに委ねることで、必要なホストをそのとおりに構築できるようにします。

Important

agent-framework-hosting、agent-framework-hosting-responses、agent-framework-hosting-telegram、agent-framework-a2a、agent-framework-hosting-a2a、およびagent-framework-hosting-mcpは、プレリリース Python パッケージです。 プレリリース バージョンを明示的にインストールし、運用環境のデプロイを更新する前にリリース ノートを確認してください。

pip install --pre agent-framework-hosting

ホスティング ヘルパーが提供するもの

汎用ホスティング パッケージは、アプリケーション所有サーバーの共有実行状態を提供します。

• AgentState は、エージェント ターゲットを SessionStore とペアにし、アプリケーションが新しいキーを選択したときにセッションを作成します。
• SessionStore は、アプリケーションが選択した ID によってセッションを格納、取得、および削除します。 既定のストアはプロセス ローカルであり、削除ポリシーはありません。
• WorkflowState はワークフロー ターゲットを解決します。 アプリケーションは、チェックポイント ストレージと、クライアント継続 ID からチェックポイントへのマッピングを所有します。

AgentState は、サーバーまたはプロトコル のレジストリではありません。 アプリケーションが承認されたセッション キーを選択し、ターゲットを解決して、実行後の状態を保存します。 1 つまたは複数のプロトコル エンドポイントに対して同じターゲットおよび共有アプリケーション インフラストラクチャを使用できます。

セッション ストレージをカスタマイズする

SessionStore は、 get、 set、および delete メソッドを備えた小規模な非同期ストレージ クラスです。 既定の実装では、セッションがプロセス メモリに保持されます。 Redis、データベース、BLOB ストレージ、または別のアプリケーション所有ストアに AgentSession オブジェクトを格納するために、それをサブクラス化してそれらのメソッドをオーバーライドし、インスタンスを AgentState(session_store=...)に渡します。

SessionStore と 履歴プロバイダーは、 エージェントの会話の個別の部分を保持します。 セッション ストアは、セッション メタデータやプロバイダーの状態など、セッション ID ごとに 1 つのセッション オブジェクトを保存します。 専用 HistoryProvider は、メッセージごとに 1 つのレコードとして、会話を個別に格納します。 この分離は永続的なホストに推奨されます。通常、個々のメッセージを追加する方が、ターンごとに増加するセッション オブジェクトを書き換えるよりも効率的であるためです。 履歴プロバイダーは、目的の履歴プロバイダー クラスを context_providers パラメーターに渡すことによって、エージェントごとに定義されます。

Note

既定の履歴プロバイダー: InMemoryHistoryProvider は例外です。完全な会話は AgentSession.stateに格納されます。 そのプロバイダーを使用すると、 SessionStore はセッション オブジェクト内の会話を保持します。 長い会話または実稼働ストレージの場合は、専用の履歴プロバイダーを使用して、セッション ストアが軽量のセッション状態に集中できるようにします。

独自のフレームワークまたはクライアント ライブラリを使用する

ホスティング パッケージは、Web フレームワークまたはクライアント ライブラリに関連付けられません。 サンプルでは FastAPI と aiogram を使用します。これは、ヘルパーが必要とするためではなく、簡潔な実行可能な例を提供するためです。

• HTTP エンドポイントの場合は、FastAPI、Starlette、Django、Flask、Azure Functions、その他のフレームワークなど、アプリケーション フレームワークのルーティング API と要求/応答 API を使用します。
• Telegram などのプロトコル クライアントの場合は、プロトコル更新プログラムを提供し、ヘルパーによって生成された操作を実行できる任意のクライアント ライブラリを使用します。

アプリケーションは、そのフレームワークとクライアント ライブラリを選択します。Agent Framework パッケージは、プロトコル データのみを変換し、オプションの実行状態を管理します。 ルートの登録、呼び出し元の認証、状態へのアクセスの承認、許可されたモデル オプションの選択、永続ストレージの提供は行いません。

サーバーにプロトコルを追加する

1 つ以上のプロトコル統合を選択します。

プロトコル	パッケージと統合
OpenAI 応答	agent-framework-hosting-responses
電報	agent-framework-hosting-telegram
A2A	agent-framework-a2a または agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

各プロトコル ページでは、そのセットアップについて説明します。 ただし、1 つ以上のプロトコルを有効にして呼び出し可能なターゲットを使用して 1 つのホストを構築できるように設計されています。エージェントまたはワークフローのいずれか。 1 つの Web フレームワークに制限されないため、必要なものを選択し、それらのプロトコルを使用してホストを簡単にセットアップできます。

セキュリティで保護されたセッションの継続

プロトコルによって提供されるすべての識別子を信頼できない入力として扱います。 ID を使用してセッション、チェックポイント、タスク、またはその他の状態を読み込む前に、次のようにします。

1. 呼び出し元を認証します。
2. 呼び出し元が参照先の状態にアクセスすることを承認します。
3. 認証済みのテナント、ユーザー、またはワークスペースごとに永続状態を分割します。
4. 実行またはストリームが完了した後にのみ、セッションとチェックポイントの状態を保持します。

このセルフホスティング パターンにより、アプリケーションは必要なプロトコル エンドポイントとポリシーのみを実装できます。サポートされているすべてのプロトコルの完全な API サーフェスを実装しようとはしません。

次のステップ

OpenAI 応答プロトコルを追加する

より深く進む:

• 電報
• A2A
• MCP
• Foundry がホストするエージェント