自架允許你在自己的 ASP.NET Core 應用程式、容器、服務或執行環境中執行 Agent Framework 代理程式或工作流程。 你的應用程式控制路由、身份、授權、請求政策、儲存、部署與擴展。 根據你需要支援的客戶端，為主機加入協定整合。
當你需要將代理端點整合到現有的應用程式基礎架構時，請使用此選項。 如果你想讓 Microsoft Foundry 幫你執行代理程式，請參見 Foundry 託管代理程式。 如果你需要 Azure Functions 觸發器或持久執行，請參見 Durable Extension。
Important
.NET 主機套件是預發布的。 明確安裝預發布版本，並在更新生產部署前先查看發佈說明。
dotnet add package Microsoft.Agents.AI.Hosting --prerelease
主機協助者提供的服務
該Microsoft.Agents.AI.Hosting套件整合代理程式與工作流程與 .NET 通用主機：
-
AddAIAgent註冊一個帶有依賴注入的命名AIAgent。 -
AddWorkflow註冊一個命名的工作流程。AddAsAIAgentChain 讓工作流程透過標準代理介面對協定整合開放。 -
IHostedAgentBuilder配置與該代理相關聯的主機服務。 -
AgentSessionStore可選擇性地載入並儲存AgentSession實例，並由應用程式或協定提供的延續 ID 儲存。
主機套件不是 HTTP 伺服器或協定登錄檔。 你的應用程式會選擇託管代理和工作流程，設定它們的服務，並加入所需的協定端點。
持續存在託管會話
會話持續性是選擇加入的。 若沒有設定 AgentSessionStore，協定整合可以為每個請求建立新的會話，但無法從先前請求恢復伺服器擁有的會話狀態。
對於開發或單程序應用程式，請配置內建的記憶體儲存：
builder.AddAIAgent("weather-agent", (_, _) => agent)
.WithInMemorySessionStore(withIsolation: false);
只有當一個受信任的使用者或程序擁有會話命名空間時，才適合設定 withIsolation 為 false 。
InMemoryAgentSessionStore 當程序退出時會失去所有會話，且不會在應用程式實例間共享狀態。
對於耐用或分散式主機，請實作 AgentSessionStore 並註冊為 WithSessionStore。 儲存實作非同步的儲存、取得與刪除操作。 它會接收擁有 AIAgent 權和不透明的會話儲存 ID，並且必須從每個 get 操作中回傳獨立 AgentSession 的實例。
AgentSessionStore 而 歷史提供者 則有不同的用途。 會話儲存會持續存在由 AgentSession 託管請求所選定的訊號。 歷史紀錄提供者會控制對話訊息的存放位置。 當歷史記錄以會話狀態保存時，持續執行會話也會持續保留該歷史;外部歷史服務提供者會分別儲存訊息。
與 ASP.NET Core 整合
共享主機套件使用 .NET 通用主機與相依注入。 對於 HTTP 伺服器，建立一個 ASP.NET Core 應用程式，並為你想暴露的端點加入協定專屬的套件。 這些套件會解析依賴注入中的命名AIAgent實例，並加入 ASP.NET Core 路由映射。
您的應用程式仍負責其中介軟體管線、認證、授權、請求驗證、允許的模型選項及耐用儲存。 非 HTTP 主機可以使用共享主機服務，而無需新增 ASP.NET Core 協定端點。
將協定加入你的伺服器
選擇應用程式所需的協定整合：
| Protocol | Integration |
|---|---|
| OpenAI 相容端點 | 聊天完成與回應相容的 HTTP 端點 |
| A2A | 代理對代理的發現、訊息傳遞與任務端點 |
| AG-UI | 網路代理應用程式的事件串流端點 |
每個協定都定義了自己的延續識別碼與端點行為。 將認證、授權、會話所有權及持久儲存權保留在共用的應用程式基礎設施中，而非為每個端點重新實作。
安全會話繼續
續接 ID 用來指示要繼續的會話;這並不證明來電者擁有該會話的版權。 範圍會由已認證的使用者、租戶或其他授權邊界持續執行會話，然後才接受客戶端提供的 ID。
對於使用基於權利要求認證的 ASP.NET Core 應用程式，安裝預發布Microsoft.Agents.AI.Hosting.AspNetCore套件、註冊基於權利要求的隔離提供者，並在會話儲存中保持隔離啟用：
builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();
builder.AddAIAgent("weather-agent", (_, _) => agent)
.WithInMemorySessionStore();
預設情況下，會UseClaimsBasedAgentIsolation使用該理賠。ClaimTypes.NameIdentifier 只有當理賠在所有來電者之間穩定且唯一時，才可設定另一個理賠。 隔離提供者不會驗證請求;請分別設定 ASP.NET Core 的認證與授權。 預設嚴格隔離行為下，當目前主體未提供設定的聲明時，會話存取失敗。
對於非 HTTP 主機或其他租戶模型，請註冊一個自訂 AgentIsolationKeyProvider的 。 預設 WithInMemorySessionStore() 值和 WithSessionStore(...) 超載會將配置好的儲存包在 IsolationKeyScopedAgentSessionStore中。
下一步
深入探討：
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將代理目標與 ASessionStore配對，當應用程式選擇新金鑰時建立會話。 -
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 載入會話、檢查點、任務或其他狀態之前：
- 驗證來電者身份。
- 授權呼叫者存取該參考州。
- 依已驗證的租戶、使用者或工作區將持久性狀態分區。
- 僅在執行或串流完成後，才持久化工作階段和檢查點狀態。
這種自我主機模式讓你的應用程式只實作它所需的協定端點和政策;它並不嘗試實作所有支援協定的完整 API 表面。
下一步
深入探討：