后台代理

后台智能体允许父智能体将独立任务委托给已命名的子智能体。每个任务都在各自的子智能体会话中并发运行，父智能体则保留任务 ID，以便等待任务、检索结果、继续工作或释放任务。

重要

后台代理处于实验阶段。

后台代理不同于后台响应。后台响应表示一次提供程序请求，应用程序可以轮询或恢复该请求。后台代理任务会调用另一个 Agent Framework 代理，随后再将该代理的文本结果返回给父代理。

手动设置后台代理

每个子代理都必须具有一个非空且在不区分大小写的情况下唯一的名称。为子代理提供明确的指令，并且只提供其所承担职责所需的工具。

导入BackgroundAgentsProvider，并通过ChatClientAgentOptions.AIContextProviders将其添加到常规代理：

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],
    wait_timeout_seconds=30,
)

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

将 instructions= 传递给 BackgroundAgentsProvider 以替换其指令。在格式化后的子代理列表应显示的位置加入 {background_agents}。

wait_timeout_seconds 设置每次调用 background_agents_wait_for_first_completion 的等待时间。它必须是正整数，默认值为 300 秒。如果超时过期，该工具将正常返回并让任务保持运行状态，以便父级可以再次调用它。

注释

此页上介绍的打包后台代理提供程序目前在 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。当任务进程内任务句柄或子会话不可用（例如进程重启或会话还原后）时，任务将丢失。可序列化的任务元数据可以保留在父会话中，但进行中的工作和子会话句柄无法跨越该边界保留。

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

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

任务结果以文本的形式返回到父级。提供程序不会将子代理的结构化工具批准请求经由父代理转发回去，因此应将子代理配置为在无需交互式批准的情况下完成委派工作，或在子代理宿主内处理这些批准请求。

从主机释放父会话

注释

主机端后台代理会话版本目前在.NET中不可用。

当主机逐出或丢弃父会话时，请在 finally 块中释放提供程序的进程内任务句柄和子会话句柄：

session = parent_agent.create_session()
try:
    await parent_agent.run("Coordinate the research.", session=session)
finally:
    await background_provider.release_session(session)

release_session(session, *, cancel_running=True, timeout=30.0) 是主机端生命周期 API，而不是面向模型的工具。默认情况下，它会取消正在运行的子任务，并在释放父会话的所有运行时状态之前等待最多 30 秒的取消。设置为 cancel_running=False 在任务运行时拒绝发布，或设置为 timeout=None 无限期等待。

相比之下， background_agents_clear_completed_task 模型可以在会话期间删除一个终端任务及其子会话。它会拒绝正在运行的任务，也不能取代主机端父会话的销毁。

注释

主机端后台代理会话版本目前在 Go 中不可用。

手动添加自动等待机制

使用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 Agent 的默认规划、内存、审批和可观测性流程，请使用此设置。

设置 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 可使后台委托在不自动重新调用的情况下仍可使用。

将 background_agents 提供给 create_harness_agent。如果父智能体应自动等待，请将其与有界循环配对：

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],
    background_agents_wait_timeout_seconds=30,
    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 替换提供程序说明。 background_agents_wait_timeout_seconds 在 wait_timeout_seconds 上配置与 BackgroundAgentsProvider 相同的有界等待。 Python 工具套件默认启用工具自动审批中间件，因此每次运行时都应传递session。

注释

工具套件智能体的后台委托功能目前不适用于 Go。

安全注意事项

仅注册你信任的子智能体。父智能体可以向子智能体发送源自私有或不受信任上下文的文本，子智能体的结果会被添加回父智能体的上下文。遭到入侵的子智能体可能会泄露委托的输入，或返回间接提示注入内容。

后续步骤

规划工作和跟踪待办事项

深入了解

反馈

此页面是否有帮助？

Last updated on 2026-09-02