AI Agent / 系统课时
核心功能实现
核心功能实现
本节实现一个可直接运行的最小 Agent:模型适配器决定下一步动作,工具注册表执行受控查询,编排器把工具结果作为 observation 回填并继续循环。示例不依赖第三方 SDK,先验证 Agent 控制流本身,再替换为真实大模型。
学习目标
- 实现
tool与final两类动作驱动的 Agent 循环 - 用工具注册表隔离模型决策与业务函数执行
- 验证步数上限、未知工具和最终答案的停止行为
把 Agent 循环压缩成四个动作
一次运行只做四件事:读取当前上下文;让模型产生下一步动作;若是工具动作则执行并追加观察结果;若是结束动作则先核对所需证据再返回。只要编排器拥有循环控制权,就能统一加入步数上限、审计和错误处理,而不是把这些逻辑散落在各个工具里。

工具注册表是关键安全边界。模型可以“请求”调用 get_order_status,但宿主根据注册表、动作参数和账户归属决定能否执行;没有注册的名称不会被动态导入,也不会被当成任意函数执行。
实现可运行的最小版本
把下面代码保存为 support_agent.py。模型替身读取状态并提出下一步。宿主从问题提取演示格式的订单号,检查只读工具和账户权限,并根据实际证据渲染回答。示例使用固定测试数据。
import re
from dataclasses import dataclass
ORDERS = {
"2026-1001": ("demo-account", "仓库处理中"),
"2026-1002": ("other-account", "已发货"),
}
RULE = "支付后通常 1–2 个工作日进入发货流程。"
@dataclass(frozen=True)
class Result:
status: str
answer: str = ""
audit: tuple = ()
def demo_model(evidence):
if "rule" not in evidence:
return "search_kb"
if "order" not in evidence:
return "get_order_status"
return "finish"
def run(question, account, choose=demo_model, max_steps=4):
ids = set(re.findall(r"(?<![0-9-])[0-9]{4}-[0-9]{4}(?![0-9-])", question))
if len(ids) != 1:
return Result("clarify")
order_id = ids.pop()
evidence = {}
audit = []
def result(status, answer=""):
return Result(status, answer, tuple(audit))
for _ in range(max_steps):
action = choose(dict(evidence))
if action == "finish":
if not {"rule", "order"} <= evidence.keys():
return result("incomplete")
return result("ok", f"订单 {order_id} 当前状态为{evidence['order']}。{evidence['rule']}")
if action == "search_kb":
evidence["rule"] = RULE
audit.append((action, "ok"))
elif action == "get_order_status":
order = ORDERS.get(order_id)
if order is None or order[0] != account:
audit.append((action, "not_available"))
return result("not_available")
evidence["order"] = order[1]
audit.append((action, "ok"))
else:
audit.append(("unregistered", "denied"))
return result("tool_denied")
return result("step_limit")
if __name__ == "__main__":
print(run("订单 2026-1001 为什么还没发货?", "demo-account").answer)运行 python support_agent.py 会输出“订单 2026-1001 当前状态为仓库处理中。支付后通常 1–2 个工作日进入发货流程。”该规则是一般流程说明。具体订单状态来自查询结果,示例没有根据一般规则推测发货日。未知订单和越权订单使用同一个 not_available,避免借接口判断其他账户的订单是否存在。
核对工具和停止边界
这里仅允许调用两个只读动作,账户和订单号来自已经解析的输入。选择器提出未知动作时立即返回 tool_denied。如果选择器过早要求结束,系统返回 incomplete。四步上限计算每次决策,也包括最后一次结束动作。审计只记录工具类别和结果状态,便于排查,不保存订单详情。
替换真实模型时保留这些边界
接入真实 LLM 时,不要重写整个 Agent。模型适配器可把结构化调用转换为本节的工具名称或结束动作。接到模型建议的参数时应重新校验,并将认证身份和允许访问的业务对象由宿主注入。工具实现、注册表、步数上限和审计逻辑仍留在编排器侧。
如果后续加入退款、改地址等写工具,应把“能否调用”与“如何执行”再拆开:模型提出写操作意图,系统先生成待审批请求,只有人工或策略引擎批准后才真正执行。这样核心 Agent 从最小版本扩展到生产版本时,新增的是能力,不是放宽控制边界。