代理迴圈

代理迴圈會重複呼叫代理，直到滿足完備條件。 它用於反覆優化、完成待辦事項、等待背景任務，或評估答案是否符合明確標準。

一定要綁定自主迴圈。 完備條件可能失敗，模型可能停滯，評估器則可能是機率的。

Important

代理迴圈是實驗性的。

手動設定循環

當你想要循環而不使用其他 Harness Agent 預設時，可以使用直接合成 API。

匯入迴圈類型，並用 LoopAgent包裹任何 AIAgent 。 其預設最多呼叫次數為 10 次代理：

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

AIAgent baseAgent = chatClient.AsAIAgent();
AIAgent agent = new LoopAgent(
    baseAgent,
    new CompletionMarkerLoopEvaluator("DONE"),
    new LoopAgentOptions { MaxIterations = 5 });

匯入 AgentLoopMiddleware 後加入一般 Agent的 . 預設最大執行次數為 10 次：

from agent_framework import Agent, AgentLoopMiddleware


def needs_more_work(*, last_result, **kwargs):
    return "DONE" not in last_result.text


agent = Agent(
    client=client,
    middleware=[
        AgentLoopMiddleware(
            needs_more_work,
            max_iterations=5,
        )
    ],
)

謂詞可以是同步或非同步的。 返回 True 以繼續、 False 停止，或 (continue, feedback) 將回饋傳給下一個迭代。

Note

本頁描述的封裝迴圈功能目前在 Go 中無法使用。

選擇完備條件

LoopAgent 接受一個評估器或一個有序集合：

評估員	繼續
CompletionMarkerLoopEvaluator	最新的回應沒有包含設定好的標記。
TodoCompletionLoopEvaluator	已解決 TodoProvider 的任務仍會有未完成的項目，這些項目可選擇於特定代理人模式中。
BackgroundTaskCompletionLoopEvaluator	已解決 BackgroundAgentsProvider 的任務仍然存在。
AIJudgeLoopEvaluator	另一位法官客戶表示，原始請求尚未完全回應。
DelegateLoopEvaluator	你的回撥回電。LoopEvaluation.Continue(...)

當多個評估器被設定時，它們會依序執行。 第一個要求再進行一次迭代的評估者會提供回饋;只有當所有評估者都拒絕繼續時，這個循環才會停止。

使用AI法官

法官會收到原始請求及最新的代理人回覆。 若發現缺口，其分析即為下一次迭代的反饋：

var evaluator = new AIJudgeLoopEvaluator(
    judgeClient,
    new AIJudgeLoopEvaluatorOptions
    {
        Criteria =
        [
            "Answer every part of the request.",
            "Support conclusions with evidence.",
        ],
    });

AIAgent loopAgent = new LoopAgent(
    agent,
    evaluator,
    new LoopAgentOptions { MaxIterations = 4 });

只使用你信任的裁判端點，並保留原始請求和產生的回應。

控制上下文與輸出

預設情況下，會 LoopAgent 重複使用一次會議，並將獲勝評審最新的回饋作為下一次輸入。 FreshContextPerIteration = true 而是從原始請求加上彙整的回饋日誌重建每次流程，並重置或還原會話。

非串流播放預設會回傳彙整的逐字稿。 設定 NonStreamingReturnsLastResponseOnly = true 只回傳最終回應。 串流每次迭代都會發出任何可見的回饋訊息。

謂詞接收關鍵字參數包括 iteration、 last_result、 messages、 feedbackoriginal_messagessessionagentprogress和 。 這些輔助工具 todos_remaining() 提供 background_tasks_running() 內建的待辦事項和背景任務條件。 將它們與todos_remaining_messagebackground_tasks_running_message或配對，以產生下一個目標輸入。

使用AI法官

AgentLoopMiddleware.with_judge 形成一個由法官主導的循環。 裁判迴圈預設為五次迭代：

from agent_framework import Agent, AgentLoopMiddleware

loop = AgentLoopMiddleware.with_judge(
    judge_client,
    criteria=[
        "Answer every part of the request.",
        "Support conclusions with evidence.",
    ],
    max_iterations=4,
)

agent = Agent(
    client=client,
    middleware=[loop],
)

當需要更多工作時，法官的理由會回饋給代理人。 只使用你信任的裁判端點，並保留原始請求和產生的回應。

控制上下文、進度與輸出

對於進階迴圈，直接構造 AgentLoopMiddleware ：

• record_feedback 每次工作迭代後建立簡潔的進度條目。
• progress 會讓累積的條目暴露回撥。
• inject_progress=True 為下一階段的輸入增加進度。
• fresh_context=True 從原始任務與進度日誌重新啟動，並將連接的會話還原到迴圈前快照。
• return_final_only=True 僅回傳非串流運行的最後回應。

僅在完備謂詞保證終止時通過 max_iterations=None 。

本頁所述的完成條件與裁判整合目前在 Go 中無法取得。

使用 Harness Agent 的迴圈

當你同時想要預先設定的歷史、規劃、記憶體、核准和可觀察性管線時，請使用 Harness Agent 設定。

設定 HarnessAgentOptions.LoopEvaluators。 該綁帶作為其最外層的代理裝飾器：LoopAgent

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

var options = new HarnessAgentOptions
{
    LoopEvaluators =
    [
        new CompletionMarkerLoopEvaluator("DONE"),
    ],
    LoopAgentOptions = new LoopAgentOptions
    {
        MaxIterations = 5,
    },
};

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

空彈或 nullLoopEvaluators 收集物則是單發離開背帶。

批准與會話行為

LoopAgent 當迭代回傳待處理的工具核准請求時，會在評估完備條件前停止。 它會將請求回傳給呼叫者，而不是將請求隱藏在另一個自主迭代後面。 呼叫者透過正常 工具核准 流程提供批准回應後，客服人員即可繼續。

LoopAgent 它本身不會增加審核處理。 Harness Agent 將迴圈套用到外部 ToolApprovalAgent，允許待處理的核准請求逃離迴圈。

在通話中重複使用該 AgentSession 內容以繼續對話。 迴圈迭代預設共享該會話。 在支援時，透過 FreshContextPerIteration = trueLoopAgent ，可重置或還原呼叫者提供的會話狀態。 當序列化會話僅包含遠端對話識別碼時，服務擁有的對話儲存可以保留歷史紀錄。

供應 loop_should_continue 至 create_harness_agent; loop_max_iterations 預設為10：

from agent_framework import create_harness_agent


def needs_more_work(*, last_result, **kwargs):
    return "DONE" not in last_result.text


agent = create_harness_agent(
    client=client,
    loop_should_continue=needs_more_work,
    loop_max_iterations=5,
)
session = agent.create_session()

loop_next_message 自訂下一個輸入。 沒有 loop_should_continue時，工廠不會新增迴圈，也會忽略其他迴圈參數。

批准與會話行為

AgentLoopMiddleware 當迭代回傳待處理的工具批准請求時，會在評估其延續謂詞前停止。 它會將請求回傳給呼叫者，而不是將請求隱藏在另一個自主迭代後面。 呼叫者透過正常 工具核准 流程提供批准回應後，客服人員即可繼續。

AgentLoopMiddleware不會自己加。ToolApprovalMiddleware Harness Agent 會將迴圈置於其核准中介軟體之外，讓待處理的核准請求能逃離迴圈。 在工具自動核准啟用時，每次執行 Harness Agent 時建立並傳遞一個 AgentSession 。

在通話中重複使用該 AgentSession 內容以繼續對話。 迴圈迭代預設共享該會話。 中 fresh_context=True介軟體會在迭代間還原所連接的會話至迴圈前快照。 當序列化會話僅包含遠端對話識別碼時，服務擁有的對話儲存可以保留歷史紀錄。

Note

Harness Agent 迴圈目前在 Go 中無法使用，因此其核准和會話行為不適用。

下一步

將工作委派給背景代理人

深入了解

• 規劃與事項
• 工具核准
• 特工哈尼斯