背景代理允許父代理將獨立任務委派給命名的子代理。 每個任務會同時在其子代理會話中執行，而父任務則保留一個任務 ID，可用來等待、檢索結果、繼續工作或釋放任務。
Important
背景代理人是實驗性質。
背景代理與 背景回應不同。 背景回應代表應用程式輪詢或恢復的一個提供者請求。 背景代理任務會呼叫另一個代理框架代理，之後將該代理的文字結果回饋給父代理。
手動設定背景代理
每個子代理必須有一個非空且大小寫不區分的唯一名稱。 給予兒童代理人專注的指示，並只提供他們被委派角色所需的工具。
透過以下方式匯入 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} 格式化的子女代理人名單應該出現的位置。
Note
本頁所述的打包背景代理提供者目前無法在 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。 當任務在其進行中的任務句柄或子工作階段無法使用時，例如程序重新啟動或會話還原後，任務就會遺失。 可序列化的任務中繼資料可以保留在父工作階段，但飛行中工作與子工作階段的句柄無法越過該邊界。
該服務提供者沒有取消功能。 讓執行中的任務進入終端狀態再清除它們。
在不同回合重複使用同一個父會議。 每個任務都會有一個專門的子工作階段。 繼續終端任務會重複使用該子工作階段;清除後會移除任務中繼資料並釋放子會話的 handle。
任務結果會以文字形式回傳給父系統。 提供者不會透過父代理將子節點的結構化工具核准請求回傳，因此設定子代理執行委派工作而無需互動核准，或在子代理主機內處理其核准。
手動新增自動等待
將手動組合的父節點包裹為 LoopAgent。
BackgroundTaskCompletionLoopEvaluator 只有當任務仍處於狀態時 Running ，才會持續：
AIAgent loopingParent = new LoopAgent(
parentAgent,
new BackgroundTaskCompletionLoopEvaluator(),
new LoopAgentOptions { MaxIterations = 10 });
評估員會暫停處理已完成、失敗或遺失的任務。
將 Back-task 謂詞與其下一訊息輔助器相加 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。
Note
目前 Go 中沒有 Harness Agent 背景委派功能。
安全性考慮
只註冊你信任的兒童經紀人。 父方可以傳送來自私密或不受信任上下文的文字，結果會被加回父方的上下文。 被入侵的子節點可以外洩委派的輸入或回傳間接的提示注入內容。