BackgroundAgentsProvider 的核心作用是让一个 父 Agent 将任务委派给其他 Agent,并允许这些任务在后台并发执行。
比如,用户要求评估向量数据库是否适合企业内部知识库。父 Agent 可以把产品价值分析交给产品研究 Agent,把技术风险分析交给风险分析 Agent。两个任务同时运行,全部结束后再由父 Agent 汇总结果。
如果只是单次调用一个专家 Agent,用普通工具调用就够;但一旦涉及后台任务编排和并发委派,BackgroundAgentsProvider 更适合需要后台任务管理的 多 Agent 场景。
用户请求
↓
父 Agent
├── 产品分析 → ProductResearchAgent
└── 风险分析 → RiskAnalysisAgent
↓
父 Agent 汇总
↓
最终回答
创建 IChatClient
先创建父 Agent 和后台 Agent 共用的 IChatClient。下面示例直接使用 Azure AI Projects 的响应客户端。
#pragma warning disable MAAI001, OPENAI001
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
string endpoint =
Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
?? throw new InvalidOperationException(
"FOUNDRY_PROJECT_ENDPOINT is not set.");
string model =
Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
?? "gpt-5.4";
var projectClient = new AIProjectClient(
new Uri(endpoint),
new DefaultAzureCredential());
IChatClient chatClient = projectClient
.GetProjectOpenAIClient()
.GetResponsesClient()
.AsIChatClient(model);
创建后台 Agent
后台 Agent 本身仍然是普通的 AIAgent,既不需要继承特殊类型,也不需要知道自己会在后台运行。
下面创建一个负责分析产品价值的 Agent。
AIAgent productAgent = chatClient.AsAIAgent(
new ChatClientAgentOptions
{
Name = "ProductResearchAgent",
Description =
"负责分析产品价值、适用场景和用户收益。",
ChatOptions = new ChatOptions
{
Instructions =
"""
你是产品研究专家。
分析产品解决的问题、适用场景、用户收益
和不适用的场景。
返回简洁、有结构的中文结论。
"""
}
});
再创建一个负责分析技术风险的 Agent。
AIAgent riskAgent = chatClient.AsAIAgent(
new ChatClientAgentOptions
{
Name = "RiskAnalysisAgent",
Description =
"负责分析技术、安全、成本和运行风险。",
ChatOptions = new ChatOptions
{
Instructions =
"""
你是技术风险分析专家。
分析技术风险、安全风险、成本风险、
运行风险以及对应的缓解措施。
返回简洁、有结构的中文结论。
"""
}
});
后台 Agent 的 Name 必须非空,并且不区分大小写时不能重复,因为父 Agent 会根据名称选择任务执行者。
本例主要演示后台任务委派,没有接入搜索或知识库。实际研究场景还需要为子 Agent 配置相应的数据来源和工具。
创建 BackgroundAgentsProvider
将两个后台 Agent 注册到 BackgroundAgentsProvider。
var backgroundAgentsProvider =
new BackgroundAgentsProvider(
[
productAgent,
riskAgent
],
new BackgroundAgentsProviderOptions
{
WaitTimeout = TimeSpan.FromMinutes(2)
});
WaitTimeout 限制的是每次调用等待工具的等待时长,不是后台任务本身的执行超时。等待超时不会取消任务,后台 Agent 仍会继续运行。
通常不需要自定义 Provider 的内部指令,因为默认指令已经会告诉父 Agent 如何启动、等待、获取和清理后台任务。
创建父 Agent
父 Agent 通过 ChatClientAgentOptions.AIContextProviders 接入 BackgroundAgentsProvider。
AIAgent coordinatorAgent = chatClient.AsAIAgent(
new ChatClientAgentOptions
{
Name = "ResearchCoordinator",
Description =
"负责拆解、委派和汇总研究任务。",
ChatOptions = new ChatOptions
{
Instructions =
"""
你是研究协调者。
收到研究问题后,将产品价值分析交给
ProductResearchAgent,将风险分析交给
RiskAnalysisAgent。
先启动全部后台任务,使它们并发运行,
然后等待并获取结果。
最后综合两个后台 Agent 的结果,
给出完整结论,并清理已完成任务。
"""
},
AIContextProviders =
[
backgroundAgentsProvider
]
});
真正将后台任务能力接入父 Agent 的配置是:
AIContextProviders =
[
backgroundAgentsProvider
]
BackgroundAgentsProvider 会把可用后台 Agent 的名称、描述和任务管理工具动态提供给父 Agent。
运行父 Agent
后台任务归属于父 Agent 的 AgentSession,因此需要显式创建并保留父 Session。
AgentSession session =
await coordinatorAgent.CreateSessionAsync();
try
{
AgentResponse response =
await coordinatorAgent.RunAsync(
"""
请评估在企业内部知识库中采用向量数据库
的产品价值和技术风险,并给出是否建议采用
的结论。
""",
session);
Console.WriteLine(response.Text);
}
finally
{
await backgroundAgentsProvider.ReleaseSessionAsync(session);
}
按照提示词设计的流程,父 Agent 收到请求后,先启动产品分析任务和风险分析任务。两个任务分别使用独立的 AgentSession,可以并发执行。父 Agent 按提示词完成等待和结果获取后,会综合两个后台 Agent 的文本结果,并通过 RunAsync 返回回答。
这个流程由提示词引导,并不是注册 Provider 之后就能自动保证。如果父 Agent 提前结束当前轮次,finally 中的释放操作会请求取消仍在运行的任务。程序层面要检查任务完成情况时,可以结合 LoopAgent 和 BackgroundTaskCompletionLoopEvaluator,并处理循环次数上限等退出条件。
会话结束时需要调用:
await backgroundAgentsProvider.ReleaseSessionAsync(session);
这会请求取消仍未完成的任务,并释放 Provider 为该 Session 保存的运行时资源。
工作原理
BackgroundAgentsProvider 是一个 AIContextProvider。它会在父 Agent 调用模型之前,将后台 Agent 清单和任务管理工具加入 AIContext。
父模型可以通过这些工具启动任务、等待任务完成、获取结果、继续任务和清理任务:
background_agents_start_task
background_agents_wait_for_first_completion
background_agents_get_task_results
background_agents_get_all_tasks
background_agents_continue_task
background_agents_clear_completed_task
其中,background_agents_wait_for_first_completion 会等到指定任务中的任意一个结束后返回,其他任务继续运行。任务结束可能是成功完成,也可能是执行失败,因此父 Agent 需要检查结果,再继续等待尚未结束的任务。
当父 Agent 启动后台任务时,Provider 会为任务创建独立的子 AgentSession,然后在当前应用进程中异步执行后台 Agent。
backgroundAgent.RunAsync(input, childSession);
父 Agent 不需要等待第一个任务完成,就可以继续启动第二个任务,因此多个后台 Agent 可以并发运行。
父 Agent
│
├── 启动 ProductResearchAgent
│ └── 独立 AgentSession
│
├── 启动 RiskAnalysisAgent
│ └── 独立 AgentSession
│
├── 等待后台任务完成
├── 获取后台任务结果
└── 汇总最终回答
这里的“后台”仍然是当前 .NET 应用进程中的异步任务,并不是消息队列或持久化作业系统。应用退出后,正在运行的任务无法继续。
从使用方式上,可以将它和 AIAgent.AsAIFunction() 理解为两种不同的 Agent 调用模式。
| 方式 |
调用模式 |
AIAgent.AsAIFunction() |
将子 Agent 暴露为工具,在工具调用完成时返回结果 |
BackgroundAgentsProvider |
启动后台任务后先返回任务 ID,再通过工具等待、获取结果或继续任务 |
AsAIFunction() 的执行可以是异步的,是否并发调用还取决于工具调用配置,因此不能简单将两者区分为“同步调用”和“并发调用”。
如果需求只是调用一个专家 Agent 并立即等待结果,使用 AsAIFunction() 更简单。如果需要并行研究、后台任务状态管理,或者继续某个已经完成的任务,则更适合使用 BackgroundAgentsProvider。
源代码地址
https://github.com/bingbing-gui/dotnet-agent-playbook/tree/master/src/ai-agent/Agent-Framework/68-BackgroundAgentsProvider