背景代理程式

背景代理程式可讓父 Agent 將獨立工作委派給具名子 Agent。每個工作都會各自在自己的子 Agent 工作階段中並行執行，而父 Agent 則會保留一個工作識別碼，可用來等候、擷取結果、繼續處理或釋放該工作。

這很重要

背景代理程式屬於實驗性功能。

背景代理與背景回應不同。背景回應代表應用程式會輪詢或繼續處理的某個提供者要求。背景代理任務會呼叫另一個 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 中新增相同的模型面向工具：

Tool	生命週期動作
`background_agents_start_task`	在命名代理上啟動一個非阻塞任務，並回傳其整數任務 ID。
`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`	移除終端機工作並釋放其子系工作階段。

典型的父-代理序列為：

在等待前先啟動每個獨立任務，讓任務同時執行。
等待第一個任務完成，取得該結果，並重複此流程，直到沒有任何任務正在執行。
當後續工作需要沿用既有的對話脈絡時，可延續已完成或失敗的任務。
擷取終端機工作的結果後，請清除這些工作，除非它們還會繼續執行。

任務狀態為 running、 completed、 failed或 lost。當工作進行中的工作控制代碼或子系工作階段無法使用時，例如在處理程序重新啟動或工作階段還原之後，該工作就會變成遺失狀態。可序列化的工作中繼資料可以保留在父系工作階段，但傳輸中工作與子系工作階段的控制代碼無法越過該邊界。

該服務提供者沒有取消功能。讓執行中的任務進入終端狀態再清除它們。

在各個回合重複使用同一個父系工作階段。每項工作都會有一個專屬的子系工作階段。繼續終端機工作會重複使用該子系工作階段；清除它會移除工作中繼資料，並釋放子系工作階段的控制代碼。

任務結果會以文字形式回傳給父系統。提供者不會透過父代理將子代理的結構化工具核准要求轉回，因此請將子代理設定為可在無需互動式核准的情況下完成委派工作，或在子代理主機內處理這些核准要求。

從主機釋放父系工作階段

備註

.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 讓模型在對話中移除一個終端任務及其子工作階段。它會拒絕執行任務，且無法取代主機端父工作階段的清理。

備註

主機端背景代理 session 釋出目前在 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 使用背景代理程式

如果您也想要 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 在 BackgroundAgentsProvider 上設定與 wait_timeout_seconds 相同的有界等待。 Python 執行框架預設會啟用工具自動核准中介軟體，因此每次執行時都要傳遞session。

備註

目前 Go 中沒有 Harness Agent 背景委派功能。

安全性考慮

只註冊你信任的兒童經紀人。父系元素可以將源自私有或不受信任內容的文字傳送給它們，而其結果會再加入父系的內容中。遭入侵的子系元素可能會外洩受委派的輸入，或傳回間接提示注入內容。

下一步

規劃工作並追蹤待辦事項

深入了解

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-03