自托管代理框架应用程序

通过自承载，可以在自己的 ASP.NET Core应用程序、容器、服务或运行时中运行 Agent Framework 代理或工作流。应用程序控制路由、标识、授权、请求策略、存储、部署和缩放。根据需要支持的客户端向主机添加协议集成。

如果需要将代理终结点与现有应用程序基础结构集成，请使用此选项。如果要Microsoft Foundry 为你运行代理，请参阅 Foundry 托管代理。有关持久执行或长时间运行的业务流程，请参阅 Durable Extension。

重要

.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 兼容的终结点	聊天补全和兼容响应的 HTTP 终结点
A2A	代理间发现、消息传递和任务终结点
AG-UI	Web 代理应用程序的事件流式处理终结点

保留托管会话

AgentSessionStore 对于使用持久化功能的托管集成，此功能需显式启用。如果没有配置的存储，这些集成可以为每个请求创建新会话，但无法从以前的请求恢复服务器拥有的会话状态。

重要

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 是由应用程序提供的持久性实现。开发分支假设本地环境中只有一位受信任用户，并且是唯一会禁用隔离的路径。生产分支保留默认隔离行为;根据安全会话延续中所述配置隔离密钥提供程序。

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 之前，先按已经过身份验证的用户、租户或其他授权边界来限定持久会话的范围。 IsolationKeyScopedAgentSessionStore 从 AgentIsolationKeyProvider 获取隔离键，将其与协议延续 ID 组合，并将生成的范围限定 ID 传递给底层存储。因此，两个不同的隔离键下的相同延续 ID 解析为两个不同的存储会话，调用方只能检索使用该调用方隔离密钥保存的会话。

对于使用基于声明的身份验证的 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 代理或工作流。应用程序控制路由、标识、授权、请求策略、存储、部署和缩放。根据需要支持的客户端向该服务器添加一个或多个协议集成。

这些包的设计允许开发人员获得最大的灵活性。这意味着，如果您想构建一个通过 Responses API 暴露智能体的主机，并滥用相关参数以实现其他目的（即把 temperature 映射到 top_p），您可以这样做。如果不想存储会话，可以执行此操作，如果想要允许调用方控制完整的代理运行，也可以执行此操作。我们不会干预；对于常见情况，我们提供辅助工具，其余部分则由你自己负责处理，这样你就能构建出完全符合自己需求的主机。

重要

agent-framework-hosting、、agent-framework-hosting-responsesagent-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 不是服务器或协议注册表。应用程序选择授权的会话密钥，解析目标，并保存运行后状态。它可以对一个或多个协议终结点使用相同的目标和共享应用程序基础结构。

自定义会话存储

SessionStore是具有get和setdelete方法的小型异步存储类。默认实现将会话保留在进程内存中。将其子类化，并重写这些方法，以便将 AgentSession 对象存储在 Redis、数据库、Blob 存储或其他由应用程序拥有的存储中，然后将该实例传递给 AgentState(session_store=...)。

SessionStore 和历史记录提供程序会持久保存智能体对话的不同部分。会话存储为每个会话 ID 保存一个会话对象，包括会话元数据和提供程序状态。专用的 HistoryProvider 会将对话单独存储，通常每条消息存为一条记录。对于持久化主机，建议采用这种分离方式，因为追加单条消息通常比在每轮交互后重写不断增大的会话对象更高效。通过将所需的历史记录提供程序类传递给 context_providers 参数，为每个代理定义历史记录提供程序。

注释

默认的历史记录提供程序：InMemoryHistoryProvider 是个例外：它将完整对话存储在 AgentSession.state 中。当使用该提供程序时，SessionStore 会将对话持久保存在会话对象中。对于较长的对话或生产环境存储，请使用专用的历史记录提供程序，以便会话存储能够专注于轻量级的会话状态。

自带框架或客户端库

托管包不绑定到 Web 框架或客户端库。这些示例使用 FastAPI aiogram ，因为它们提供了简洁的可运行示例，而不是因为帮助程序需要它们。

对于 HTTP 终结点，请使用应用程序框架的路由和请求/响应 API，例如 FastAPI、Starlette、Django、Flask、Azure Functions 或其他框架。
对于 Telegram 等协议客户端，请使用提供协议更新和执行帮助程序生成的操作的任何客户端库。

应用程序选择其框架和客户端库;代理框架包仅转换协议数据并管理可选的执行状态。他们不注册路由、对调用方进行身份验证、授权访问状态、选择允许的模型选项或提供持久存储。

将协议添加到服务器

选择一个或多个协议集成：

协议	打包和集成
OpenAI 响应	`agent-framework-hosting-responses`
电报	`agent-framework-hosting-telegram`
A2A	`agent-framework-a2a` 或 `agent-framework-hosting-a2a`
MCP	`agent-framework-hosting-mcp`

每个协议页描述其设置。但是，其设计目的是让你能够构建单个主机，并启用一种或多种协议以及一个可调用的目标，无论该目标是代理还是工作流。由于我们不会将你限制为一个 Web 框架，因此你可以选择所需的框架，并使用这些协议轻松设置主机。

安全会话继续

将每个协议提供的标识符视为不受信任的输入。在使用 ID 加载会话、检查点、任务或其他状态之前：

对调用方进行身份验证。
授权调用方访问引用的状态。
按已通过身份验证的租户、用户或工作区划分持久化状态。
仅在运行或流式处理完成后，才持久化会话和检查点状态。

此自承载模式允许应用程序仅实现所需的协议终结点和策略;它不会尝试实现每个受支持的协议的完整 API 图面。

后续步骤

添加 OpenAI 响应协议

更深入：

反馈

此页面是否有帮助？

上次更新时间为 2026-10-22

自托管代理框架应用程序

托管助手提供的内容

与 ASP.NET Core集成

将协议添加到服务器

保留托管会话

安全会话继续

后续步骤

托管助手提供的内容

自定义会话存储

自带框架或客户端库

将协议添加到服务器

安全会话继续

后续步骤

反馈

其他资源