自我裝載的代理程式框架應用程式

Note

適用於 .NET 的自我託管通訊協定輔助程式即將推出。 主機模式會讓你的應用程式擁有伺服器、狀態和協定整合。

Note

Go 目前尚無可用的自我託管通訊協定輔助程式。

自行託管可讓你在自己的網頁應用程式、容器、服務或執行環境中執行 Agent Framework 代理程式或工作流程。 你的應用程式控制路由、身份、授權、請求政策、儲存、部署與擴展。 根據你需要支援的客戶端，為該伺服器加入一個或多個協定整合。

當你需要將代理端點整合到現有的應用程式基礎架構時，請使用此選項。 如果你想讓 Microsoft Foundry 幫你執行代理程式，請參見 Foundry 託管代理程式。 如果你需要 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 將代理目標與 A SessionStore 配對，當應用程式選擇新金鑰時建立會話。
  • SessionStore 透過應用程式選擇的 ID 儲存、檢索及刪除會話。 它的預設商店是 process-local，沒有驅逐政策。
  • WorkflowState 解決工作流程目標。 你的應用程式擁有檢查點的儲存空間，以及從客戶端延續 ID 到檢查點的任何映射。

AgentState 不是伺服器或協定登錄檔。 你的應用程式會選擇授權的會話金鑰，解析目標，並儲存執行後的狀態。 它可以使用相同的目標及共享的應用程式基礎設施來管理一個或多個協定端點。

自訂會話儲存

SessionStore 是一個小型非同步儲存類別，包含 get、 set和 delete 方法。 預設實作會將工作階段儲存在行程記憶體中。 建立其子類別並覆寫這些方法，將 AgentSession 物件儲存在 Redis、資料庫、Blob 儲存體或其他應用程式自有的儲存區中，然後將該執行個體傳遞給 AgentState(session_store=...)。

SessionStore 和 歷史提供者 會分別保存代理對話的不同部分。 工作階段存放區會為每個工作階段 ID 儲存一個工作階段物件，其中包含工作階段中繼資料和提供者狀態。 專用的 HistoryProvider 會將對話分開儲存，通常每則訊息各為一筆記錄。 建議持久型主機採用這種分離方式，因為在每次回合後附加個別訊息，通常比每次都重寫持續擴大的工作階段物件更有效率。 系統會為每個代理程式定義一個歷程提供者，方法是將所需的歷程提供者類別傳遞給 context_providers 參數。

Note

預設的歷史提供者： InMemoryHistoryProvider 是例外：它將完整對話儲存在 AgentSession.state。 使用該提供者時，SessionStore 會將對話持久保存於工作階段物件中。 對於較長的對話或生產儲存，請使用專用的歷史服務提供者，讓會話儲存能持續專注於輕量級會話狀態。

帶上你自己的框架或客戶端函式庫

主機套件不綁定於網頁框架或用戶端函式庫。 範例使用 FastAPI 和 aiogram，是因為它們能提供簡潔且可執行的範例，而不是因為輔助函式需要它們。

  • 對於 HTTP 端點，請使用你應用框架的路由與請求/回應 API，例如 FastAPI、Starlette、Django、Flask、Azure Functions 或其他框架。
  • 對於像 Telegram 這類協定用戶端，請使用任何能提供協定更新並執行輔助器產生操作的用戶端函式庫。

應用程式選擇其框架與用戶端函式庫;Agent Framework 套件僅轉換協定資料並管理可選執行狀態。 它們不會註冊路由、驗證呼叫者、授權狀態存取、選擇允許的模型選項，也不會提供持久的儲存。

將協定加入你的伺服器

選擇一個或多個協定整合：

Protocol 套件與整合
OpenAI 回應 agent-framework-hosting-responses
電報 agent-framework-hosting-telegram
A2A agent-framework-a2a 或 agent-framework-hosting-a2a
MCP agent-framework-hosting-mcp

每個協定頁面都會描述其設定。 不過，它們的設計可讓你建立單一主機，啟用一種或多種協定，並指定可呼叫的目標，即代理程式或工作流程。 由於我們不限制你只能使用單一網路框架，你可以選擇想要的，並輕鬆地用這些協定設定主機。

安全會話繼續

將每個協定提供的識別碼視為不受信任的輸入。 在使用 ID 載入會話、檢查點、任務或其他狀態之前：

  1. 驗證來電者身份。
  2. 授權呼叫者存取該參考州。
  3. 依已驗證的租戶、使用者或工作區將持久性狀態分區。
  4. 僅在執行或串流完成後，才持久化工作階段和檢查點狀態。

這種自我主機模式讓你的應用程式只實作它所需的協定端點和政策;它並不嘗試實作所有支援協定的完整 API 表面。

下一步

新增 OpenAI 回應協定

深入探討：

  • Last updated on