背景代理允許父代理將獨立任務委派給命名的子代理。 每個任務都會各自在自己的子代理工作階段中並行執行，而父代理則會保留一個任務 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]
)
parent_agent = Agent(
client=client,
name="research-coordinator",
context_providers=[background_provider],
)
session = parent_agent.create_session()
切換 instructions= 到 BackgroundAgentsProvider 以取代其指示。 請標明 {background_agents} 格式化的子女代理人名單應該出現的位置。
備註
本頁所述的打包背景代理提供者目前無法在 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。 當任務進行中的任務控制代碼或子工作階段無法使用時，例如在處理序重新啟動或工作階段還原之後，該任務就會變成遺失狀態。 可序列化的任務中繼資料可以保留在父工作階段，但飛行中工作與子工作階段的句柄無法越過該邊界。
該服務提供者沒有取消功能。 讓執行中的任務進入終端狀態再清除它們。
在不同回合重複使用同一個父會議。 每個任務都會有一個專屬的子工作階段。 繼續終端機工作會重複使用該子工作階段；清除它會移除任務中繼資料，並釋放子工作階段的控制代碼。
任務結果會以文字形式回傳給父系統。 提供者不會透過父代理將子代理的結構化工具核准要求轉回，因此請將子代理設定為可在無需互動式核准的情況下完成委派工作，或在子代理主機內處理這些核准要求。
手動新增自動等待功能
以 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],
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。
備註
目前 Go 中沒有 Harness Agent 背景委派功能。
安全性考慮
只註冊你信任的兒童經紀人。 父層可以將源自私密或不受信任上下文的文字傳送給它們，而其結果會再加入父層的上下文中。 遭入侵的子代理可能會外洩受委派的輸入，或回傳間接提示注入內容。