后台代理

后台代理允许父代理将独立任务委托给命名子代理。每个任务在其自己的子代理会话中并发运行，而父级保留可用于等待、检索结果、继续工作或释放任务的任务 ID。

Important

后台代理是实验性的。

后台代理不同于后台响应。后台响应表示应用程序轮询或恢复的一个提供程序请求。后台代理任务调用另一个 Agent Framework 代理，稍后会将代理的文本结果馈送回父级。

手动设置后台代理

每个子代理必须具有不区分大小写的唯一名称。为子代理提供重点说明，并仅提供其委派角色所需的工具。

通过以下方法ChatClientAgentOptions.AIContextProviders导入BackgroundAgentsProvider并将其添加到常规代理：

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var backgroundProvider = new BackgroundAgentsProvider(
    [webSearchAgent, codeAnalysisAgent]);

AIAgent parentAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    Name = "research-coordinator",
    AIContextProviders = [backgroundProvider],
});

AgentSession session = await parentAgent.CreateSessionAsync();

BackgroundAgentsProviderOptions 自定义提供程序说明和代理列表格式。

from agent_framework import Agent, BackgroundAgentsProvider

background_provider = BackgroundAgentsProvider(
    [web_search_agent, code_analysis_agent]
)

parent_agent = Agent(
    client=client,
    name="research-coordinator",
    context_providers=[background_provider],
)
session = parent_agent.create_session()

BackgroundAgentsProvider传递给instructions=替换其指令。包括 {background_agents} 应显示格式化的子代理列表的位置。

注释

此页上介绍的打包后台代理提供程序目前在 Go 中不可用。

任务生命周期

提供程序在.NET和Python中添加相同的面向模型的工具：

工具	生命周期操作
`background_agents_start_task`	在命名代理上启动非阻止任务，并返回其整数任务 ID。
`background_agents_wait_for_first_completion`	等到提供集中的第一个任务达到终端状态。
`background_agents_get_task_results`	返回已完成的文本、失败消息或当前状态。
`background_agents_get_all_tasks`	列出 ID、状态、代理名称和说明。
`background_agents_continue_task`	在任务完成或失败后，在现有子会话中运行后续输入。
`background_agents_clear_completed_task`	删除终端任务并释放其子会话。

典型的父代理序列为：

在等待之前启动每个独立任务，以便任务并发运行。
等待第一次完成，检索该结果，然后重复，直到没有任务正在运行。
当后续工作需要其现有对话上下文时，请继续完成或失败的任务。
在检索其结果后清除终端任务，除非它们将继续执行。

任务状态为running、completed或failedlost。当任务进程内任务句柄或子会话不可用（例如进程重启或会话还原后）时，任务将丢失。可序列化的任务元数据可以保留在父会话中，但正在进行的工作和子会话句柄不能在该边界中生存。

提供程序中没有取消工具。在清除任务之前，让正在运行的任务到达终端状态。

跨轮次重复使用同一个父会话。每个任务都会收到一个专用的子会话。继续执行终端任务将重复使用该子会话;清除它会删除任务元数据并释放子会话句柄。

任务结果以文本的形式返回到父级。提供程序不会通过父级代理代理子级的结构化工具审批请求，因此配置子代理以在未经交互式审批的情况下完成委派工作，或在子代理主机内处理其审批。

手动添加自动等待

使用 LoopAgent. 包装手动组合的父级。 BackgroundTaskCompletionLoopEvaluator 仅在任务保持 Running 处于状态时继续：

AIAgent loopingParent = new LoopAgent(
    parentAgent,
    new BackgroundTaskCompletionLoopEvaluator(),
    new LoopAgentOptions { MaxIterations = 10 });

计算器停止完成、失败和丢失的任务。

添加到 AgentLoopMiddleware 常规父级，并将后台任务谓词与其下一消息帮助程序配对：

from agent_framework import (
    Agent,
    AgentLoopMiddleware,
    background_tasks_running,
    background_tasks_running_message,
)

parent_agent = Agent(
    client=client,
    context_providers=[background_provider],
    middleware=[
        AgentLoopMiddleware(
            background_tasks_running(),
            next_message=background_tasks_running_message,
            max_iterations=10,
        )
    ],
)

谓词仅在持久化任务状态仍报告正在运行的任务时继续。

自动后台任务循环集成目前在 Go 中不可用。

将后台代理与 Harness 代理配合使用

如果还希望 Harness 代理的默认规划、内存、审批和可观测性管道，请使用此设置。

设置 HarnessAgentOptions.BackgroundAgents。添加完成计算器，当父级应继续运行，直到委托的工作不再运行：

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var options = new HarnessAgentOptions
{
    Name = "research-coordinator",
    BackgroundAgents = [webSearchAgent, codeAnalysisAgent],
    LoopEvaluators = [new BackgroundTaskCompletionLoopEvaluator()],
    LoopAgentOptions = new LoopAgentOptions { MaxIterations = 10 },
};

HarnessAgent parentAgent = chatClient.AsHarnessAgent(options);
// Equivalent construction: new HarnessAgent(chatClient, options)
AgentSession session = await parentAgent.CreateSessionAsync();

用于 HarnessAgentOptions.BackgroundAgentsProviderOptions 自定义提供程序说明和代理列表格式。省略 LoopEvaluators 使后台委派在不使用自动吊销的情况下可用。

create_harness_agent提供给 background_agents . 当父级应自动等待时，将其与绑定循环配对：

from agent_framework import (
    background_tasks_running,
    background_tasks_running_message,
    create_harness_agent,
)

parent_agent = create_harness_agent(
    client=client,
    name="research-coordinator",
    background_agents=[web_search_agent, code_analysis_agent],
    loop_should_continue=background_tasks_running(),
    loop_next_message=background_tasks_running_message,
    loop_max_iterations=10,
)
session = parent_agent.create_session()

用于 background_agents_instructions 替换提供程序说明。默认情况下，Python工具支持自动审批中间件，因此每次运行都会传递session。

注释

Harness 代理后台委派目前在 Go 中不可用。

安全注意事项

仅注册你信任的子代理。父级可以向其发送派生自私有或不受信任的上下文的文本，其结果将添加回父上下文。泄露的子级可能会外泄委托的输入或返回间接的提示注入内容。

后续步骤

规划工作和跟踪待办事项

深入了解

反馈

此页面是否有帮助？

Last updated on 2026-08-13