Agent开发 02|Agent Loop:任务如何持续执行?

Agent开发 02|Agent Loop:任务如何持续执行?

《Agent开发》系列 · 第 02 篇

假设用户向 AI 客服提出:

订单 1001 已经支付成功,但金币没有到账,帮我查一下原因。

AI 助手需要核实业务数据。它可能先查询订单状态,再查询金币发放记录,最后根据结果说明目前查到的原因。第二步应该做什么,往往取决于第一步的结果。

如果订单尚未支付,通常不需要继续排查金币发放故障;如果订单已支付,就需要进一步查看发放记录。查询失败时,也需要决定如何告知用户或是否继续尝试。

后端怎样把这些步骤组织起来?怎样让模型看到上一步的结果?如果模型一直查询、不肯结束,又该怎么办?

这篇文章从一次工具调用开始,逐步实现 Agent Loop(智能体执行循环)。示例使用 Python,默认无需 API Key 即可运行,不要求提前阅读其他文章。

一、为什么一次工具调用还不够?

1.1 先理解 Function Calling

开发者提前给 AI 助手后端配置可用工具及其说明。后端把用户问题和工具清单交给大模型,由模型选择工具、填写参数,再返回明确的调用请求。后端校验并执行请求,把结果交回模型。

这种让模型提出结构化工具调用请求的机制,就是 Function Calling。 "结构化"表示把工具名称、参数等信息放进约定字段,方便程序读取。

例如,查询订单支付状态时,模型可以提出如下请求。这里使用简化格式:

json 复制代码
{
  "name": "get_order_status",
  "arguments": {"order_id": "1001"}
}

后端执行查询,得到订单已支付的结果,再交给模型组织回答:

text 复制代码
用户问题 → 模型提出查询请求 → 后端查询订单 → 结果交回模型 → 模型回答

模型负责提出请求,后端负责执行,订单业务系统负责提供可信数据。模型生成了请求,不代表查询已经发生。

这里展示的是只查一次工具的简单流程。Function Calling 本身并不限于一次调用;工具结果交回后,模型仍可以继续提出请求。Agent Loop 讨论的正是后端怎样持续组织这些交互。OpenAI 工具调用流程说明

1.2 下一步依赖上一步的结果

对于"金币为什么没有到账",查询支付状态只是第一步。本例提供两个只读工具:

工具 能力
get_order_status 查询订单支付状态
get_grant_record 查询金币发放记录及记录中的错误信息

下一步可能随查询结果变化:

订单查询结果 下一步可能的行动
已支付 查询金币发放记录
尚未支付 说明当前支付状态,通常不继续查发放故障
订单不存在或无权访问 说明无法查询,不泄露订单信息
查询失败 按程序规则处理错误,必要时停止

后端需要把结果交给模型,再处理模型提出的新请求。如此反复,直到得到回答或触发停止条件,这就需要 Agent Loop。

规则明确时,也可以直接写 if/else 或预定义工作流,完成这些分支。本例用一个简单场景展示循环机制,并不意味着这种订单排查必须使用 Agent。

二、Agent Loop 与 Runtime:流程和执行程序有什么区别?

2.1 Agent Loop 描述任务怎样循环推进

先把订单排查过程连起来:

text 复制代码
模型请求查询订单
    ↓
后端查询并回传支付状态
    ↓
模型根据支付状态,继续请求查询金币发放记录
    ↓
后端执行并回传发放记录
    ↓
模型根据已有结果回答

这里重复发生的是"调用模型 → 执行工具 → 反馈结果 → 继续或结束"。这套让模型与工具反复交互、推进任务的执行流程,叫 Agent Loop(智能体执行循环)。

Agent Loop 关注的是流程怎样走:本轮得到什么结果,是否需要进入下一轮,什么时候结束。

2.2 Runtime 负责实现和管理这个流程

流程本身不会自动运行。后端必须有代码负责发送模型请求、找到工具实现、检查参数和权限、保存交互记录,以及处理超时和次数限制。

承担这些执行与管理职责的运行程序,就是 Agent Runtime(智能体运行时)。 它可以是后端里的若干函数或模块,不一定要独立部署成服务,也不要求使用特定框架。

两者的关系是:Runtime 实现并运行 Agent Loop;Agent Loop 是 Runtime 中的一部分执行逻辑。

概念 关注什么 订单案例中的例子
Agent Loop 流程怎样循环推进 查完支付状态,把结果交给模型,再决定是否查询发放记录
Runtime 哪些程序让流程实际运行,并管理执行 发送模型请求、调用查询函数、维护历史,并在达到预算时停止

本篇没有单独创建一个叫 Runtime 的类。模型调用、工具执行、交互记录维护和循环控制等代码,共同构成一个简化的 Runtime。

2.3 在一次查询中,把两者对应起来

下面每个 Runtime 步骤都是后端执行的工作;从调用模型到工具结果回传,再次调用模型的重复过程,就是 Agent Loop。方括号中的数字标记后端协调步骤,不表示模型调用轮数。

text 复制代码
用户:订单 1001 已支付,但金币没到账,帮我查一下原因

Runtime [1]
把用户问题和可用工具说明交给大模型
    ↓
大模型
提出 get_order_status(order_id="1001") 请求
    ↓
Runtime [2]
校验并执行订单查询,把"已支付"的结果交回大模型
    ↓
大模型
根据支付结果,提出 get_grant_record(order_id="1001") 请求
    ↓
Runtime [3]
校验并执行发放记录查询,把"发放失败"的结果交回大模型
    ↓
大模型
根据已有结果生成回答,不再请求工具
    ↓
Runtime [4]
检查响应并返回回答,结束本次交互

模型根据当前信息提出下一步行动。Runtime 负责执行协调、校验和限制,业务系统负责最终的数据访问与业务约束。

上面这条示例路径包含三轮模型调用、两次工具执行。本文把"一轮"定义为一次模型调用及其响应处理;最后生成回答也算一轮。Mock 会按这条路径执行,真实模型的轮数和工具选择可能不同。

2.4 Agent Loop 是不是一个 while 循环?

最简单的实现可以写成循环:

python 复制代码
# 伪代码,用于说明流程,并非实际 SDK 接口。
while not stopped:
    response = call_model(history)
    if response.has_tool_calls:
        execute_tools(response)
        append_tool_results(history)
    else:
        return response.final_answer

但循环语句不会自动解决超时、重复调用、权限和状态丢失等问题。实际系统需要给循环加上控制规则。

复杂任务也可以用状态机、工作流引擎或事件驱动实现相同机制。理解 Agent Loop,重点是理解每一步如何推进和停止。

三、先明确本篇 Demo 的范围

示例有两种运行模式,两者共用工具执行逻辑和循环:

模式 模型部分 业务部分
Mock 用固定规则模拟模型响应 内存中的订单和发放记录
--live 调用真实模型 API 同样使用内存中的业务数据

Mock 用来观察程序的数据流,不代表真实模型的理解和决策能力。

准备的数据如下:

订单 支付状态 金币发放记录 访问条件
1001 已支付 失败,错误码 GRANT_TIMEOUT 当前用户可访问
1002 未支付 无记录 当前用户可访问
1003 已支付 成功 当前用户可访问
2002 已支付 本例未配置 属于其他用户,不允许访问

GRANT_TIMEOUT 是教学自定义的业务错误码,表示发放记录中保存的超时错误。它不表示本次查询接口超时,也不是 Google Play Billing 官方错误码。查到这条记录能解释系统记录的失败状态,但还不能证明所有底层根因。

两个工具都只读。示例不会补发金币、退款或修改余额,也没有实现任务持久化、审批和中断恢复。

四、工具与权限:每轮执行仍然需要检查

4.1 模型看到工具说明,后端保留执行代码

工具说明包含名称、用途和参数要求,称为 Tool Schema。两个工具都接收 order_id。后端通过注册表找到真正的实现:

python 复制代码
HANDLERS = {
    "get_order_status": get_order_status,
    "get_grant_record": get_grant_record,
}

本例的 execute_tool() 会依次检查工具是否注册、参数是否为有效 JSON、字段是否正确,以及订单号是否符合格式,再调用对应函数。

每轮都经过这条路径。前一轮调用成功,不意味着后一轮可以省略检查。

4.2 当前身份由后端提供

python 复制代码
ACTOR = {"user_id": "user-a", "tenant_id": "tenant-a"}

这表示当前用户 A 属于租户 A。"租户"可以理解为使用同一套平台的不同企业或组织,它们的数据需要隔离。

教学程序固定注入这个身份;真实服务应从可信认证信息获取。模型填写订单号,不能通过修改参数决定以谁的身份查询。

两个查询函数都会调用 accessible_order() 检查订单所属用户和租户。金币发放记录工具还会再次检查订单是否已支付:

python 复制代码
if order["payment_status"] != "PAID":
    return {"ok": False, "code": "PAYMENT_NOT_CONFIRMED"}

提示词要求模型"先查支付,再查发放记录",这是行动顺序上的引导。工具内部的检查则独立保证:未支付的订单不能通过这个工具查询发放记录。

本例并未强制验证模型此前一定调用过支付查询。如果实际业务要求严格顺序,还需要由 Runtime 记录执行状态并校验前置步骤。

五、拆开核心代码:循环怎样推进?

完整代码放在文末附录,可直接复制保存为 agent_loop.py。配套项目中的文件位置是 demo/02-agent-loop/agent_loop.py(相对于文章所在目录)。先把前面的概念对应到代码:

示例代码 承担的工作
live_model() / mock_model() 获取模型响应
execute_tool() 及其调用的工具函数 校验请求、检查业务权限并执行工具
history 及其维护代码 保存本次交互内容
次数、时间和响应检查 控制执行边界
agent_loop() 中的循环 串起上述能力,实现 Agent Loop

这些代码共同构成一个简化的 Runtime。Runtime 是对这部分程序职责的称呼,不要求代码中一定存在同名的类。agent_loop() 同时包含循环逻辑和一些执行控制,因此两者也不是按函数名严格划分的。

下面逐段看这套流程怎样运行。

5.1 用 history 保存本次交互

python 复制代码
history = [{"role": "user", "content": question}]

history 是一个列表,用来保存用户问题、模型输出和工具结果。

循环第二次调用模型时,需要把第一轮的查询结果一起提供给模型。否则,模型仅看到原始问题,无法知道订单已经查过,也无法依据"已支付"继续选择工具。

订单 1001 的历史会逐步变成:

text 复制代码
第一轮调用前
用户问题

第二轮调用前
用户问题
模型请求查订单
订单查询结果:已支付

第三轮调用前
用户问题
模型请求查订单
订单查询结果:已支付
模型请求查金币发放记录
发放查询结果:失败,GRANT_TIMEOUT

history 只在内存中维护。程序退出后,本例不会自动恢复这些内容。

5.2 每轮调用模型,并识别工具请求

python 复制代码
for step in range(1, MAX_STEPS + 1):
    response = model_call(history)
    output = response.get("output", [])
    calls = [
        item for item in output
        if item.get("type") == "function_call"
    ]
    history.extend(output)

这是核心片段,省略了完整程序中的时间和响应状态检查。

model_call 可以指向 mock_model 或 live_model。循环不需要关心响应来自本地模拟还是真实服务,只需要处理约定的数据结构。

function_call 表示模型提出了工具请求。history.extend(output) 保留本轮模型输出,后续再追加工具结果。

5.3 校验并执行工具,再回填结果

python 复制代码
for call in calls:
    result = execute_tool(call, ACTOR)
    history.append({
        "type": "function_call_output",
        "call_id": call["call_id"],
        "output": json.dumps(result, ensure_ascii=False),
    })

function_call_output 表示后端返回的工具结果。call_id 是工具请求的标识,回传相同标识,就能将结果关联到原请求。

执行完这一轮的工具后,代码到达 for step 循环体末尾,自然进入下一轮,再次执行 model_call(history)。完整实现不需要额外写 continue。

关键变化就在这里:工具执行后,后端允许模型继续提出新请求。真实模式每轮使用 tool_choice="auto",让模型选择工具或回答,而没有在第一次工具执行后就禁止后续调用。

5.4 没有工具请求时,返回当前回答

python 复制代码
if not calls:
    answer = extract_text(output)
    if not answer:
        return {
            "status": "EMPTY_RESPONSE",
            "answer": "模型没有返回可展示的内容。"
        }
    return {"status": "COMPLETED", "answer": answer}

extract_text() 提取文本回答,也处理模型拒绝回答的内容。

本例的 COMPLETED 只表示本次交互已经结束,不代表用户问题已经解决。 它可能是一份排查结论,也可能是"请提供订单编号"或拒绝回答。

如果产品需要区分成功、等待用户、拒绝和无法处理,应设计更明确的状态。本例没有实现这些状态之间的持久化和恢复。

5.5 为什么同时限制轮数和工具调用次数?

python 复制代码
MAX_STEPS = 6
MAX_TOOL_CALLS = 8
MAX_SECONDS = 60

轮数统计模型调用,工具次数统计交给 execute_tool() 处理的请求,包括因未知工具、参数错误或无权限而被拒绝的请求;它不等于业务查询成功次数。两者含义不同。模型生成最终回答会消耗一轮,但不执行工具;通用运行时也可能收到一轮多个工具请求。

真实模式关闭了并行工具调用,便于观察单条查询链。循环仍保留多个请求的防御性处理,逐项执行和回填。六轮、八次和六十秒都是教学程序自行设定的限制。

六、运行示例:观察三轮模型调用

建议使用 Python 3.10 或以上。将文末附录的完整代码保存为 agent_loop.py,在该文件所在目录打开终端,即可执行下面的命令,无需下载其他项目文件。

如果已经取得配套项目,也可以从包含 agent系列文章 文件夹的目录进入示例目录:

bash 复制代码
cd "agent系列文章/demo/02-agent-loop"

下文命令以 macOS 或 Linux 终端为例。Windows 用户可根据安装方式使用 python 或 py 替代 python3。

6.1 先运行 Mock,无需 API Key

bash 复制代码
python3 agent_loop.py '订单 1001 已支付,但金币没到账,帮我查一下原因'

本地运行结果:

text 复制代码
[Agent Loop] 第 1 轮
[工具请求] get_order_status {"order_id": "1001"}
[工具结果] {"ok": true, "order_id": "1001", "payment_status": "PAID"}

[Agent Loop] 第 2 轮
[工具请求] get_grant_record {"order_id": "1001"}
[工具结果] {"ok": true, "order_id": "1001", "grant_status": "FAILED", "error_code": "GRANT_TIMEOUT"}

[Agent Loop] 第 3 轮
[任务状态] COMPLETED
[最终结果] 订单 1001 已支付,但金币发放失败,错误码为 GRANT_TIMEOUT。目前没有证据表明金币已到账。

再尝试不同输入:

输入 Mock 的执行路径
订单 1002 为什么没到账 查支付状态,然后说明未支付;两轮模型调用、一次工具执行
订单 1003 为什么没到账 查支付,再查发放记录,说明记录成功但余额问题仍需核对
订单 2002 为什么没到账 工具拒绝访问,模型说明无法继续排查
订单 9999 为什么没到账 返回未找到可访问的订单
帮我查订单 询问订单编号,不执行工具

Mock 按问题中的单个数字提取编号,并按固定规则选择路径。它不具备真实模型的语言理解能力,也不适合用来评估工具选择质量。

6.2 使用真实模型

在虚拟环境中安装 SDK:

bash 复制代码
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install openai

Windows PowerShell 可使用 .\.venv\Scripts\Activate.ps1 激活虚拟环境;激活后使用 python -m pip install openai 安装依赖。通过环境变量提供 OPENAI_API_KEY 和 OPENAI_MODEL,模型需要支持 Responses API 和函数工具调用。密钥不要写进代码或仓库。

bash 复制代码
python3 agent_loop.py --live '订单 1001 已支付,但金币没到账,帮我查一下原因'

真实模式会产生模型调用费用,业务数据仍来自本地内存。模型可能采用不同的路径,应同时检查请求记录和回答。

程序为模型请求设置 20 秒超时,关闭 SDK 自动重试。缺少依赖、环境变量或调用失败时,会由外层异常处理打印错误并退出。

本文已验证本地 Mock 及循环控制路径;真实模型 API 未实际调用,以上 Live 命令不代表已经验证真实服务的输出。

七、循环什么时候停止,什么时候只是继续反馈错误?

7.1 当前代码已经实现的行为

情况 当前行为
模型返回可展示文本,无工具请求 返回 COMPLETED,结束本次交互
模型询问编号或拒绝回答 同样返回 COMPLETED,没有持久化等待状态
模型响应未正常完成 返回 MODEL_INCOMPLETE
响应没有工具请求,也没有可展示文本 返回 EMPTY_RESPONSE
工具调用标识缺失或本轮重复 返回 INVALID_TOOL_CALL
下一批请求将超出工具次数预算 返回 TOOL_BUDGET_EXCEEDED,不执行这一批
用完最大轮数,模型仍请求工具 最后一轮工具执行后,返回 MAX_STEPS_EXCEEDED
轮次开始时发现总时间已超限 返回 TIMEOUT
未知工具、参数错误或无权限 返回工具错误给模型,循环仍可能继续
模型或工具函数抛出未处理异常 外层捕获,打印异常并以非零退出码退出

本例还需要区分任务状态与命令行退出码:只有抛出异常时,脚本才以非零退出码退出;TIMEOUT、MAX_STEPS_EXCEEDED 等返回状态会被打印,但进程仍正常退出。若接入 CI 或任务调度器,应根据返回状态显式设置退出码,不能只凭进程退出码判断任务是否成功。

无权限不意味着循环函数立刻停止。本例是工具拒绝访问,再把错误交回模型,由模型解释结果;如果模型继续请求,仍会受到后续校验和预算限制。

达到最后一轮时,若模型还请求工具,程序会执行符合预算的请求,但没有下一轮用于总结结果。这是本例的边界。产品中可以为最终说明预留轮次,或在停止时返回已经确认的部分结果。

7.2 时间限制有什么边界?

MAX_SECONDS 只在每轮开始时检查,不能强制打断正在阻塞的模型请求或工具执行。

例如,某轮开始时还未超时,但模型返回时已经超过总时限,当前代码仍可能执行本轮工具,或直接返回回答。它不是严格的六十秒截止机制。

更完整的实现应计算任务剩余时间,将其用于每次调用的超时设置,并在发出新操作前再次检查。需要中断正在进行的调用时,还要依赖相应的取消机制。涉及写入操作时,取消或超时之后仍需核对业务结果。

7.3 等待用户或审批,属于后续扩展

如果缺少订单号,本例只是返回询问并结束。用户下一次运行脚本,会创建一个新任务。

真正支持等待和恢复,需要保存任务进度,等用户补充信息或审批事件到来后再继续。不能让一个循环长期占用资源等待人工响应。

八、常见问题:循环能运行,不代表任务一定正确

8.1 模型不断重复查询同一订单

最大轮数和工具预算能给执行设置上限,还可以结合重复检测和只读缓存减少无效查询。但订单状态可能变化,不能简单禁止所有重复查询。

判断时需要考虑两次查询之间是否经过合理等待、是否获得新信息,以及任务是否确实需要再次确认。

8.2 工具执行失败

真实查询接口超时时,工具层应返回明确错误,不能伪装成成功。程序决定是否允许有限重试,模型根据失败信息解释当前限制。

本例尚未将真实网络工具异常转换为统一的工具错误;未处理异常会直接退出。要练习重试,应先区分临时故障与无权限等不可通过重试解决的问题。

8.3 工具结果正确,回答却错误

订单工具返回已支付,模型仍可能回答未支付。排查时应依次核对:工具返回了什么、结果是否正确关联并进入下一轮输入、模型最终说了什么。

工具执行成功只能证明取得了结果,不能证明模型正确使用了结果。后续可通过评测样本检查回答是否与业务数据一致。

8.4 模型声称"金币已补发"

本例没有补发工具,因此这样的回答没有执行证据。

即使未来增加了写工具,也应以可信业务系统中的操作结果为准。需要区分"模型结束回答""排查得到结论"和"实际业务操作成功"。

8.5 模型一次提出多个工具请求

Runtime 需要分别关联请求与结果,并检查依赖关系。存在先后依赖的操作不能仅因模型同时提出请求就并行执行。

本例逐项处理,金币记录查询还会检查真实支付状态。对于严格要求先完成某一步才能进行下一步的流程,应进一步在 Runtime 中保存和验证前置条件。

九、Agent 架构:任务可以怎样组织?

9.1 从执行循环,到任务组织

前面已经讲清楚:Runtime 负责调用模型、执行工具和回传结果,Agent Loop 让这些步骤能够反复推进。前面讨论的重复查询、步骤依赖等问题,也提醒我们:有了循环,还需要决定任务怎样组织。

例如:

  • 执行步骤由开发者提前规定,还是让模型根据结果决定?
  • 遇到复杂任务,是直接开始行动,还是先制定计划?
  • 一个 Agent 完成全部工作,还是多个 Agent 分工?

这些关于任务如何拆分、决策和协作的安排,属于 Agent 架构设计的一部分。

同样是排查"订单已支付,但金币未到账",可以提前固定"查订单 → 查发放记录 → 输出结论",也可以让模型根据每次查询结果选择下一步。两种方式可能完成相同任务,但执行的灵活程度和控制方式不同。

9.2 常见的任务组织方式

开发 Agent 系统时,经常会遇到下面几种方式:

方式 怎样组织任务 订单排查中的例子
Workflow(工作流) 开发者预先规定主要步骤和分支,程序按规则推进 先查支付状态,已支付才进入发放记录查询
ReAct(推理与行动交替) 模型结合已有信息选择行动,再根据执行结果继续判断 查到已支付后,模型决定继续查发放记录
Planner-Executor(规划与执行分离) 先制定计划,再执行步骤,必要时调整计划 先规划需要核查哪些信息,再逐项查询
Multi-Agent(多智能体协作) 多个 Agent 分工,并通过协调机制完成任务 订单 Agent 与发放排查 Agent 分别处理各自任务,再汇总结果

这些方式关注的层面有所不同:Workflow、ReAct、Planner-Executor 主要涉及控制流程与决策安排,Multi-Agent 主要涉及参与者如何分工。因此,它们不是互斥的类别,可以组合使用。例如,固定工作流中的某个排查步骤,可以交给采用 ReAct 方式的 Agent 完成。表中的多 Agent 分工只是说明组织方式,本篇的简单查询并不需要引入多个 Agent。

本篇先理解与工具调用循环直接相关的 ReAct,其他方式的适用边界和选型将在后续文章展开。

9.3 ReAct:根据观察结果决定下一步

ReAct 将 Reasoning(推理)与 Acting(行动)结合起来:根据当前信息判断下一步行动,执行后获得新的观察,再据此继续判断。这种推理与行动交替的思路来自 ReAct 论文。

沿着订单案例,可以这样理解:

text 复制代码
需要排查金币未到账
    ↓
判断:先确认订单是否已经支付
行动:请求查询订单
观察:订单已支付
    ↓
判断:继续检查金币发放环节
行动:请求查询发放记录
观察:记录显示发放失败,错误码为 GRANT_TIMEOUT
    ↓
根据已取得的证据,向用户说明查询结论

这里的"判断"用于解释决策依据,不代表需要展示模型完整的内部推理过程。

与提前固定全部步骤相比,ReAct 允许模型根据新信息调整后续行动。但灵活性也意味着模型可能选错工具、重复查询或过早回答,因此仍然需要 Runtime 检查权限、限制预算,并验证结果。

本篇 Mock 的路线由程序规则写死,只模拟了这样的交互过程,不能据此认为它具备模型推理能力。

9.4 ReAct、Agent Loop 与 Runtime 分别负责什么?

这三个概念可以放在同一次订单查询中理解:

概念 关注点 对应本例
ReAct 如何结合观察结果推理并选择行动 看到订单已支付后,决定继续查询发放记录
Agent Loop 模型与工具怎样反复交互、推进任务 调用模型 → 执行工具 → 回传结果 → 再次调用模型
Runtime 哪些程序实现并管理这套执行过程 模型调用、工具执行、历史维护、权限检查和预算控制

ReAct 可以通过 Agent Loop 来执行,Runtime 则负责实现和管理这个循环。 Agent Loop 也可以用于推进预先制定的计划,因此不能把 Agent Loop 与 ReAct 当成同一个概念。

十、Harness:Agent 运行还需要怎样的配套环境?

前面介绍了任务可以怎样组织。但无论采用 ReAct,还是先规划再执行,模型都需要知道有哪些工具可用,执行过程也需要受到权限、预算和停止规则的约束。

围绕 Agent 配置的工具、上下文、执行规则和反馈机制,常被统称为 Agent Harness。它让模型能够在一个具备能力和约束的环境中完成任务。

10.1 本篇示例中,哪些部分体现了 Harness?

Harness 并不是一个必须额外安装的框架。本例中已经能找到它的一些组成部分:

示例中的配置或代码 提供什么能力或约束
TOOLS 与工具实现 告诉模型有哪些能力可用,并提供实际执行方式
INSTRUCTIONS 约定先核实支付状态、根据工具结果回答等行为要求
history 与结果回填 把用户问题和已取得的信息交给模型,支持下一步判断
工具校验与业务权限检查 限制允许执行的请求和允许访问的数据
轮数、工具次数和时间检查 给任务执行设置边界,限制持续消耗

这些部分共同体现了一个简化 Harness 的部分能力。提示词用于引导模型,权限和预算等必须由程序落实的约束,仍然要在执行路径上检查。

10.2 它与 Agent Loop、Runtime 怎样联系?

可以从三个关注点理解同一个系统:

概念 关注的问题
Agent Loop 模型与工具之间的执行流程怎样循环推进?
Runtime 程序怎样实际运行和管理这套流程?
Harness 围绕 Agent 配置了哪些能力、信息和约束?

这不是三个必须分开实现的组件。Runtime 与 Harness 的边界并不统一,实际系统中的职责常有重叠。例如,工具校验既是 Runtime 执行请求时的工作,也是 Harness 提供的控制能力。

设计时应明确每项能力由哪部分代码承担,无需为了对应术语而额外拆出一套程序。

十一、从 Demo 到可靠运行:还需要补齐什么?

本例已经具备基础的运行环境和控制规则,但距离可靠处理真实任务,还有一些缺口。下面从具体故障场景看需要补齐什么。

11.1 重启之后,怎样知道已经执行到哪一步?

需要记录任务当前状态,包括已经查询到的信息、待执行步骤以及是否等待用户,这些属于 State(状态)。

为了从特定位置恢复,还需要保存足够的恢复信息,例如消息历史、工具结果和执行位置。这类恢复检查点称为 Checkpoint。

Checkpoint 不保证外部操作只执行一次。未来涉及退款或补发时,需要业务系统识别重复操作,让同一笔操作重复提交也不会重复产生效果,这涉及幂等性。

11.2 用户说回答不对,怎样找到出错的位置?

需要记录某次任务经历了哪些模型调用和工具执行、各自耗时多少、哪里出错。这些能力属于 Observability(可观测性)。

把同一次任务中的调用关联起来,就能形成可追踪的执行链路,通常称为 Trace。记录内容时也要处理敏感数据和访问权限。

11.3 历史越来越长,怎样控制模型输入?

本例不断向 history 追加内容,长任务会增加输入长度和调用费用。

需要选择当前任务所需的信息,在压缩历史时保留关键事实,以及工具请求和结果之间的关系。这属于 Context Engineering(上下文工程)。

模型通常以 Token 为单位处理和计量文本,可以先把 Token 理解为文本被拆分后的处理单位。长度和费用预算都需要考虑输入与输出。

11.4 怎样控制成本与执行权限?

除了轮数和工具次数,还需要统计模型用量、单任务费用,把重试也计入预算。

每次工具执行都应检查当前身份、目标资源、业务条件和必要的审批。允许 Agent 动态选择下一步,不等于允许它动态扩大业务权限。

十二、面试与自查

12.1 什么是 Agent Loop?

Agent Loop 是模型与工具反复交互、推进任务的执行流程。Runtime 把工具结果加入后续模型输入,让任务根据新信息继续推进,并在完成交互或触发限制时停止。

12.2 为什么查询订单 1001 是三轮而不是两轮?

本篇按模型调用计轮数。第一轮请求查支付,第二轮根据支付结果请求查发放记录,第三轮根据结果生成回答。工具实际执行了两次。

12.3 Function Calling 与 Agent Loop 有什么区别?

Function Calling 提供模型表达工具请求的方式,Agent Loop 组织多轮模型与工具交互。循环利用工具结果继续推进,直到满足停止条件。

12.4 COMPLETED 是否意味着问题已解决?

不意味着。本例询问用户补充信息、拒绝回答或生成结论,都可能返回这个状态。它只表示本次交互结束,任务是否成功需要独立验证。

12.5 怎样防止无限执行?

限制模型轮数、工具次数、总时限和费用;按具体业务识别无效重复;为外部调用设置超时,并在停止后不再发起新操作。严格截止时间还需要检查剩余时间和支持取消。

12.6 执行到一半崩溃怎么办?

本例无法恢复。更完整的系统需要持久化状态和检查点,并核对已经发生的外部操作;涉及写入时,结合业务幂等和结果查询避免重复执行。

12.7 Agent Loop 与 Runtime 有什么区别?

Agent Loop 描述"调用模型、执行工具、反馈结果、继续或结束"的循环流程。Runtime 是负责实现并管理这套流程的运行程序,还承担模型调用、工具调度、交互记录维护和执行限制等职责。

在本例中,agent_loop() 内的循环实现 Agent Loop;它与模型调用函数、工具执行函数等代码共同构成简化的 Runtime。一个描述流程,一个描述承载流程的程序及其职责。

十三、把整个过程串起来

回到"订单 1001 已支付,但金币未到账"的问题。本例先核实支付状态,再查询发放记录,最终根据已有证据生成回答。

模型负责依据当前输入提出行动或回答。Agent Loop 描述模型与工具如何通过反馈循环推进任务,Runtime 则是实现并管理这套流程的运行程序,负责组织调用、检查请求、回填结果和控制执行。后续行动可以建立在前面取得的信息之上。

理解 Agent Loop,需要同时看清两条线:任务如何通过反馈继续推进,以及程序如何限制和结束执行。 下面的完整代码可以用于观察这两条线。

参考资料


附录:完整代码

以下是完整的单文件程序,与配套项目中的 demo/02-agent-loop/agent_loop.py 一致。默认运行 Mock;--live 使用真实模型 API,配置方法见第六节。

python 复制代码
"""Agent Loop 教学示例。默认 Mock,--live 调用真实模型。"""
import argparse
import json
import os
import re
import time

MAX_STEPS = 6
MAX_TOOL_CALLS = 8
MAX_SECONDS = 60
ACTOR = {"user_id": "user-a", "tenant_id": "tenant-a"}

ORDERS = {
    "1001": {"user_id": "user-a", "tenant_id": "tenant-a", "payment_status": "PAID"},
    "1002": {"user_id": "user-a", "tenant_id": "tenant-a", "payment_status": "UNPAID"},
    "1003": {"user_id": "user-a", "tenant_id": "tenant-a", "payment_status": "PAID"},
    "2002": {"user_id": "user-b", "tenant_id": "tenant-a", "payment_status": "PAID"},
}
GRANT_RECORDS = {
    "1001": {"grant_status": "FAILED", "error_code": "GRANT_TIMEOUT"},
    "1003": {"grant_status": "SUCCESS", "error_code": None},
}


def function_tool(name, description):
    return {
        "type": "function", "name": name, "description": description,
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string", "description": "订单编号"}},
            "required": ["order_id"], "additionalProperties": False,
        },
    }


TOOLS = [
    function_tool("get_order_status", "查询订单支付状态;订单号不明确时先询问用户。"),
    function_tool("get_grant_record", "查询订单的金币发放记录和失败原因。"),
]
INSTRUCTIONS = (
    "你是订单排查助手。用户询问金币未到账时先查询支付状态;"
    "只有支付状态为 PAID 才查询金币发放记录。"
    "只能根据工具结果回答,不能编造状态。"
    "订单编号不明确时询问用户。工具失败时说明无法查询。"
    "你没有退款或补发工具,不得声称已经执行这些操作。用中文简洁回答。"
)


def accessible_order(order_id, actor):
    order = ORDERS.get(order_id)
    if not order or order["user_id"] != actor["user_id"]:
        return None
    if order["tenant_id"] != actor["tenant_id"]:
        return None
    return order


def get_order_status(order_id, actor):
    order = accessible_order(order_id, actor)
    if order is None:
        return {"ok": False, "code": "NOT_FOUND_OR_FORBIDDEN"}
    return {"ok": True, "order_id": order_id,
            "payment_status": order["payment_status"]}


def get_grant_record(order_id, actor):
    order = accessible_order(order_id, actor)
    if order is None:
        return {"ok": False, "code": "NOT_FOUND_OR_FORBIDDEN"}
    if order["payment_status"] != "PAID":
        return {"ok": False, "code": "PAYMENT_NOT_CONFIRMED"}
    record = GRANT_RECORDS.get(order_id)
    if record is None:
        return {"ok": True, "order_id": order_id, "grant_status": "NO_RECORD"}
    return {"ok": True, "order_id": order_id, **record}


HANDLERS = {
    "get_order_status": get_order_status,
    "get_grant_record": get_grant_record,
}


def execute_tool(call, actor):
    handler = HANDLERS.get(call.get("name"))
    if handler is None:
        return {"ok": False, "code": "UNKNOWN_TOOL"}
    try:
        arguments = json.loads(call["arguments"])
    except (KeyError, TypeError, ValueError):
        return {"ok": False, "code": "INVALID_JSON"}
    if not isinstance(arguments, dict) or set(arguments) != {"order_id"}:
        return {"ok": False, "code": "INVALID_ARGUMENTS"}
    order_id = arguments["order_id"]
    if not isinstance(order_id, str) or not re.fullmatch(r"[0-9]{1,20}", order_id):
        return {"ok": False, "code": "INVALID_ORDER_ID"}
    return handler(order_id, actor)


def message_response(text):
    return {"status": "completed", "output": [{
        "type": "message", "role": "assistant",
        "content": [{"type": "output_text", "text": text}],
    }]}


def tool_response(name, order_id, call_id):
    return {"status": "completed", "output": [{
        "type": "function_call", "name": name,
        "arguments": json.dumps({"order_id": order_id}), "call_id": call_id,
    }]}


def mock_model(history):
    """模拟决策,用于验证循环机制,不代表真实模型推理能力。"""
    question = history[0]["content"]
    ids = re.findall(r"(?<![0-9])[0-9]+(?![0-9])", question)
    if len(ids) != 1:
        return message_response("请提供一个明确的订单编号。")
    order_id = ids[0]
    outputs = [x for x in history if x.get("type") == "function_call_output"]
    if not outputs:
        return tool_response("get_order_status", order_id, "call-order")
    order_result = json.loads(outputs[0]["output"])
    if not order_result.get("ok"):
        return message_response("未找到可访问的订单,无法继续排查。")
    if order_result["payment_status"] != "PAID":
        return message_response(f"订单 {order_id} 尚未确认支付,暂不排查金币发放失败。")
    if len(outputs) == 1:
        return tool_response("get_grant_record", order_id, "call-grant")
    grant_result = json.loads(outputs[1]["output"])
    if not grant_result.get("ok"):
        return message_response("订单已支付,但暂时无法查询金币发放记录。")
    status = grant_result["grant_status"]
    if status == "FAILED":
        return message_response(
            f"订单 {order_id} 已支付,但金币发放失败,"
            f"错误码为 {grant_result.get('error_code')}。目前没有证据表明金币已到账。"
        )
    if status == "SUCCESS":
        return message_response(
            f"订单 {order_id} 已支付,金币发放记录显示成功。"
            "如余额仍未变化,需要进一步核对。"
        )
    return message_response(f"订单 {order_id} 已支付,但没有查到金币发放记录。")


def live_model(history):
    from openai import OpenAI
    with OpenAI(timeout=20.0, max_retries=0) as client:
        response = client.responses.create(
            model=os.environ["OPENAI_MODEL"], instructions=INSTRUCTIONS,
            input=history, tools=TOOLS, tool_choice="auto",
            parallel_tool_calls=False, store=False,
        )
        return response.model_dump()


def extract_text(output):
    texts = []
    for item in output:
        if item.get("type") != "message":
            continue
        for part in item.get("content", []):
            if part.get("type") == "output_text":
                texts.append(part["text"])
            elif part.get("type") == "refusal":
                texts.append(part["refusal"])
    return "\n".join(texts)


def agent_loop(question, model_call):
    history = [{"role": "user", "content": question}]
    started_at = time.monotonic()
    total_tool_calls = 0
    for step in range(1, MAX_STEPS + 1):
        if time.monotonic() - started_at >= MAX_SECONDS:
            return {"status": "TIMEOUT", "answer": "任务超过执行时间限制。"}
        print(f"\n[Agent Loop] 第 {step} 轮")
        response = model_call(history)
        if response.get("status") != "completed":
            return {"status": "MODEL_INCOMPLETE", "answer": "模型响应未正常完成。"}
        output = response.get("output", [])
        calls = [item for item in output if item.get("type") == "function_call"]
        history.extend(output)
        if not calls:
            answer = extract_text(output)
            if not answer:
                return {"status": "EMPTY_RESPONSE", "answer": "模型没有返回可展示的内容。"}
            return {"status": "COMPLETED", "answer": answer}
        call_ids = [call.get("call_id") for call in calls]
        if (any(not isinstance(cid, str) or not cid for cid in call_ids)
                or len(set(call_ids)) != len(call_ids)):
            return {"status": "INVALID_TOOL_CALL", "answer": "工具调用标识无效。"}
        if total_tool_calls + len(calls) > MAX_TOOL_CALLS:
            return {"status": "TOOL_BUDGET_EXCEEDED", "answer": "工具调用次数超过限制。"}
        for call in calls:
            print("[工具请求]", call.get("name"), call.get("arguments"))
            result = execute_tool(call, ACTOR)
            print("[工具结果]", json.dumps(result, ensure_ascii=False))
            history.append({
                "type": "function_call_output", "call_id": call["call_id"],
                "output": json.dumps(result, ensure_ascii=False),
            })
            total_tool_calls += 1
    return {"status": "MAX_STEPS_EXCEEDED", "answer": "Agent 达到最大执行轮数。"}


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("question", nargs="?", default="订单 1001 已支付,但金币没到账,帮我查一下原因。")
    parser.add_argument("--live", action="store_true", help="使用真实模型 API")
    args = parser.parse_args()
    model_call = live_model if args.live else mock_model
    try:
        result = agent_loop(args.question, model_call)
        print("\n[任务状态]", result["status"])
        print("[最终结果]", result["answer"])
    except Exception as error:
        print("[运行异常]", type(error).__name__, str(error))
        raise SystemExit(1)


if __name__ == "__main__":
    main()

运行示例后,先把订单号换成 1002,观察为什么查询支付状态后就结束;再在本地练习副本中,让 Mock 每轮都提出查询请求,观察最大轮数怎样让程序停止。对照日志找到"取得新信息"和"触发限制"发生的位置,就能更具体地理解循环的推进与控制。

当任务变得复杂,哪些步骤应该预先固定,哪些可以交给模型决定?如果需要先制定计划,再分别执行,又该怎样组织?

下一篇:Agent开发 03|架构选型:不同模式怎么选?

我们将继续比较 Workflow、ReAct 与 Planner-Executor 的适用场景和工程取舍,并讨论如何在同一个系统中组合使用。

相关推荐
J船长1 小时前
Agent开发 01|Function Calling:AI 如何调用工具?
agent
SA-D4 小时前
Agent 如何防御 Prompt 注入:从输入信任边界到工具执行授权
agent·提示词注入·prompt注入
J船长13 小时前
Agent开发 00|从 ChatGPT 到生产级 AI Agent
agent
Csvn14 小时前
如果明天供应商涨价 3 倍?三层解耦,换模型只改一行配置(C05)
人工智能·aigc·agent
七夜zippoe17 小时前
Agent 告警设计:分级告警、智能降噪与值班排班
开发语言·ai·agent·告警·智能降噪·值班排班
prince_zxill1 天前
把 17 个散文件装进一个文件夹:拆解 claude-plugins-official 的插件打包术(47,413 Star 实测)
python·github·agent·mcp·claude code
程序员张富华1 天前
一次发布拦住12个破坏性变更:我们给Agent工作流加了Schema门禁
人工智能·agent
ZhengEnCi1 天前
Claude 的记忆是怎么设计的:四层记忆栈,和一场叫「做梦」的离线整理
aigc·agent·ai编程
Csvn2 天前
换供应商要改一遍代码?把模型接入收进一层网关(C04)
人工智能·aigc·agent