代理循环将重新调用代理，直到满足完成条件。 使用它进行迭代优化、待办事项完成、等待后台任务，或评估答案是否符合显式条件。
始终绑定自治循环。 完成条件可能会失败，模型可能会停止，计算器可以是概率性的。
Important
代理循环是实验性的。
手动设置循环
如果想要在没有其他 Harness 代理默认值的情况下循环，请使用直接合成 API。
导入循环类型，并使用 .AIAgentLoopAgent. 其默认最大值为 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) 将反馈传递给下一次迭代。
注释
此页上介绍的打包循环功能目前在 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、、、messages、sessionoriginal_messages、agent和progressfeedback。 last_result 帮助程序 todos_remaining() 并提供 background_tasks_running() 内置的待办事项和后台任务条件。 将它们与下一个输入配对 todos_remaining_message 或 background_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 代理配合使用
如果还希望其预配置历史记录、规划、内存、审批和可观测性管道，请使用 Harness 代理设置。
设置 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 代理在外部 ToolApprovalAgent应用循环，允许等待的审批请求转义循环。
在呼叫之间重复使用相同的 AgentSession 内容以继续对话。 循环迭代默认共享该会话。 使用 FreshContextPerIteration = true、 LoopAgent 重置或还原支持调用方提供的会话状态。 当序列化会话仅包含远程会话标识符时，服务拥有的对话存储可以保留历史记录。
create_harness_agent提供给 loop_should_continue ;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 代理将循环置于其审批中间件之外，从而允许等待的审批请求转义循环。 启用工具自动审批时，创建并传递 AgentSession 每个 Harness 代理运行。
在呼叫之间重复使用相同的 AgentSession 内容以继续对话。 循环迭代默认共享该会话。 使用 fresh_context=True中间件，中间件会将附加的会话还原到迭代之间的预循环快照。 当序列化会话仅包含远程会话标识符时，服务拥有的对话存储可以保留历史记录。
注释
Harness 代理循环目前在 Go 中不可用，因此其审批和会话行为不适用。