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

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

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

Important

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

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

Microsoft.Agents.AI.Hosting.OpenAIやMicrosoft.Agents.AI.Hosting.A2A.AspNetCoreなどのプロトコル統合パッケージは、既にMicrosoft.Agents.AI.Hostingを参照しています。ホストがプロトコル統合パッケージを使用していない場合にのみ、直接インストールします。

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

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 実装を提供します。

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

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 と互換性のあるエンドポイントを追加する

より深く進む:

Go では、プロトコル固有の統合によるセルフホスティングがサポートされています。

A2A: a2aprovider.NewExecutor と、公式の A2A Go サーバーハンドラーを使用してエージェントを適応させます。
AG-UI: aguiprovider.NewJSONHTTPHandler でエージェントを提供します。
MCP: agenttool.Newを使用してエージェントを関数ツールとしてラップし、mcptool.AddToolに登録します。

このページの Python ホスティングアダプターは Go API ではありません。 Go は現在、対応するガイドで説明されている OpenAI 応答または Telegram ホスティングヘルパーを提供していません。

Go プロトコルハンドラーでは、他の SDK で示されている共有セッションストアの抽象化は提供されません。必要に応じて agent.Session 明示的に保持し、ホストで呼び出し元の所有権を適用し、 agent.HistoryProviderを使用して会話履歴を個別に構成します。

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

これらのパッケージの設計により、開発者は最大限の柔軟性を得ることができます。つまり、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 を使用してセッション、チェックポイント、タスク、またはその他の状態を読み込む前に、次のようにします。

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

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

次のステップ

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

より深く進む:

フィードバック

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

最終更新: 2026-10-22

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

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

ASP.NET Coreとの統合

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

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

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

次のステップ

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

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

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

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

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

次のステップ

フィードバック

その他のリソース

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

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

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

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

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