Note
.NET用のセルフホスティング プロトコル ヘルパーは近日公開予定です。 ホスティング モデルでは、アプリケーションがサーバー、状態、プロトコルの統合を所有できるようになります。
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 を使用してセッション、チェックポイント、タスク、またはその他の状態を読み込む前に、次のようにします。
- 呼び出し元を認証します。
- 呼び出し元が参照先の状態にアクセスすることを承認します。
- 認証済みのテナント、ユーザー、またはワークスペースごとに永続状態を分割します。
- 実行またはストリームが完了した後にのみ、セッションとチェックポイントの状態を保持します。
このセルフホスティング パターンにより、アプリケーションは必要なプロトコル エンドポイントとポリシーのみを実装できます。サポートされているすべてのプロトコルの完全な API サーフェスを実装しようとはしません。
次のステップ
より深く進む: