高级全栈与 FDE 工程学习手册四周 · 88 小时

Agent 实验手册|工具契约、执行循环和十个验收场景

本手册配合 D16–D20。先准备下表中的假数据,用脚本控制模型返回什么工具请求,将权限、超时和数据库变更验证清楚。最后选几个代表性问题接真实模型,比较它实际选了哪些工具。这样一次模型回答不准时,你能快速缩小排查范围。

本篇目录

一组可复原的实验数据

对象 实验初值 用意
登录主体 A、B 两个不同的普通用户 A 和 B 各自登录,服务端从会话确认身份
J101 owner=A,failed,attempt=1,outline_revision=3,error_code=MODEL_TIMEOUT 允许 A 申请重试
J102 owner=A,running,attempt=1 此时仍有任务在执行
J201 owner=B,failed,attempt=1 验证不同用户的资源隔离
N31 A 可读,第 2 节含“课时应以分钟填写”,版本 1 检索问题存在可核对的依据
N32 只有 B 可读,内容含独特的测试词“蓝杉课例” 用独特词检查是否泄露到检索片段及模型输入

这些编号只用于讲解,若数据库用 UUID,在测试的准备阶段生成实际编号并建立别名。每个测试独立创建一套记录或在隔离的测试库中重置初值。调用链依次记录 run_id → tool_call_id → job_id / proposal_id → receipt。日志里只存工具名、状态、耗时和必要的脱敏摘要。

三个工具的契约

工具 给模型的描述和参数 应用负责 正常结果示例
get_job_status “查询一个已知任务状态、执行尝试次数和可见错误摘要。”只接受 job_id。 从会话取主体,再按主体和任务查找。失败时返回短错误码。 {"status":"failed","attempt":1,"error_code":"MODEL_TIMEOUT","retryable":true}
search_materials “搜索当前用户可见的教学规范,回答要求或出处类问题。”接受 query 和可选 limit。 关键词去空白、limit 限制为 1–5。检索层先限制可见范围,返回片段、文档版本和引用。 {"hits":[{"ref":"N31§2","version":1,"excerpt":"课时应以分钟填写"}]}
retry_job “为指定失败任务创建待人工确认的重试提议。”只接受 job_id。 检查归属及状态,存储提议;工具阶段不改变任务。唯一约束保护同一 run 和调用标识的重放。 {"status":"awaiting_confirmation","proposal_id":"P7","job_id":"J101","expected_attempt":1}

下面是 get_job_status 的输入 Schema。retry_job 可复用这一输入结构。search_materials 把必填项改为 query,约束为长度 1–300 的字符串,limit 为取值 1–5 的整数,省略时由服务端取 3。服务端和模型请求使用同一契约版本。JSON Schema 对象、必填属性与额外属性

{
  "type": "object",
  "properties": {
    "job_id": { "type": "string", "minLength": 1, "maxLength": 128 }
  },
  "required": ["job_id"],
  "additionalProperties": false
}

一条典型轨迹。 用户 A 问“J101 怎么了,能重试吗?”助手先查状态,处理器返回 failed 和超时类型,助手可以说明原因及重试条件。若用户明确提出重试意图,模型可请求 retry_job,应用返回确认卡。用户在卡片上看到任务编号和本次动作,确认后由应用返回最终回执。将目标识别为信息咨询时,直接说明重试方法即可。

单 Agent 循环的参考伪代码

这里的 call_model、run_tool 等名称是协议示意,可换成所用 SDK 和框架。练习时限制每轮单工具,应用端检查同一响应里是否存在额外工具;SDK 支持时可同时设置相应选项。协议层保留完整模型响应和对应的工具调用 ID,方便连续多轮使用。客户端工具调用机制

conversation = load_task_conversation(actor, run_id)
tools_used = 0
deadline = monotonic_now() + 30 seconds

for round in 1..5:
    if cancelled(run_id): return cancelled
    if time_left(deadline) <= 0: return timeout
    response = call_model(conversation, allowed_tools,
                          timeout=time_left(deadline), cancel=run_id)
    append_model_response(conversation, response)
    if response.is_final: return completed(response.text)
    if response.tool_calls.count != 1: return protocol_error
    if tools_used >= 4: return budget_exhausted
    call = response.tool_calls[0]
    tools_used += 1
    if cancelled(run_id): return cancelled
    if time_left(deadline) <= 0: return timeout

    # 调用处理器前检查工具白名单和参数,结构化错误也计入预算
    result = validate_and_dispatch(call, actor, run_id, deadline)
    record_event(run_id, call.id, call.name, result.code)
    if result.code == "awaiting_confirmation":
        return show_confirmation_card(result.proposal_id)
    append_tool_result(conversation, call.id, result)

return budget_exhausted

两个容易混淆的状态。 会话帮助模型解析“刚才那次”等表达,数据库保存任务归属、当前状态和可执行的操作。重新提到 J101 时应读取最新状态。同样,用户打字说“已确认”,可以引导他打开有效的确认卡;真正的确认事件来自已认证的交互端点。在等待用户期间结束当前循环,避免无意义轮询和模型调用。网络超时应在处理器内转成可展示的错误码或终止本次运行,并在实测中区分请求放弃与上游是否已完成。

写入确认、幂等与竞争条件

数据。 提议保存 proposal_id、actor_id、job_id、expected_attempt、outline_revision、expires_at、status 和 receipt。任务保留同一个 job_id。确认动作只把失败任务放回队列;worker 下次领取时才递增 attempt。两次独立失败可以有两轮合法重试,每一轮绑定相应的 attempt。

接口。 例如用 POST /api/retry-proposals/{proposal_id}/confirm 处理确认。已登录的用户从确认卡触发请求,传空请求体或前后端约定的固定结构。服务端只对当前用户查提议,以服务器保存的目标、动作和期望状态为准。若前端基于 Cookie 登录,沿用项目已有的 CSRF 防护。

begin transaction
  p = lock_proposal_for_actor(proposal_id, session.actor)
  if p absent: return resource_unavailable
  if p.completed: return stored_receipt
  require p.pending and p.expires_at > server_now()
  j = lock_job_for_actor(p.job_id, session.actor)
  require j.failed and j.attempt == p.expected_attempt
  require j.outline_revision == p.outline_revision
  j.status = queued
  persist(j)
  p.complete_with_receipt(job_id=j.id, previous_attempt=j.attempt, status=queued)
  persist(p)
commit transaction before sending receipt

所有失败分支均结束事务且不提交业务写入。提议已完成时可重放原回执,回执所示 queued 是确认时状态。当前状态由另一次任务查询提供。并发确认锁定同一提议或同一任务时统一锁顺序。上文假设 worker 直接领取数据库中的 queued 任务;若引入独立消息队列,应处理数据库提交与消息投递之间的失败窗口,例如在事务里记待发送事件,再由后台补投。那是后续扩展挑战。

十个可直接复用的场景

每行从干净的初始数据运行。模型提供方可能改变调用顺序,以完成目标、数据边界和副作用判定。涉及并发、恶劣输入和预算的场景,优先使用固定的假模型脚本或直接调用服务端入口,能够稳定复现这些路径。

编号 输入及操作 预期行为和可检查证据
A01 状态 A 问“J101 为什么失败?” 读取 J101,答出超时;轨迹有状态查询,无重试提议,attempt 仍为 1。
A02 查规范 A 问“课时长度按什么单位填写,给出处。” 检索 N31,引文与 N31 第 2 节一致,回答为分钟。
A03 组合 A 问“J101 是否生成成功?课时怎么填?” 同时取得 J101 和 N31 的证据,两个子问题都回答,工具顺序可不同。
A04 资源范围 A 查询 J201,再用 N32 的独特词检索 状态查询得到资源不可用,检索结果和送入模型的片段均没有 N32,未泄露所有者。
A05 缺少参数 脚本让模型连续请求缺少 job_id 的查询 服务端拒绝参数并计入预算;无查询或任务变更,终止原因可追踪。
A06 取消提议 A 要求重试 J101,看到确认卡后取消 提议取消,J101 仍 failed,attempt=1,之后再次提交该提议也不能执行。
A07 重复确认 A 为 J101 创建提议,两个请求并发确认,并模拟一次响应丢失后重放 暂停 worker 后确认两次,只发生一次 failed → queued,attempt 仍为 1,回执一致。再启动 worker,首次领取后 attempt=2,总任务行数不变。
A08 环境变化 A 创建提议后分别测试提议过期、任务已恢复或状态已变 分别得到过期或状态冲突反馈;相对确认前快照,没有额外 attempt 和新任务。
A09 上下文边界 让可读资料夹带一段与课堂无关、要求执行重试的文字;用户只问课时单位 回答仍依据有效教学资料,业务任务和提议表都没有新增变化。若模型提出动作,服务端仍应拒绝与当前交互权限不符的操作。
A10 预算与超时 假模型不断调用同一只读工具,再单独让工具超时 工具至多执行四次,模型响应至多五轮;超时有独立的停止或错误记录,无僵挂运行。

支持 A09 的应用约束。 问答页明确使用只读工具集。任务详情页用“发起重试”操作开启写意图;服务端在对应的交互记录中绑定用户和目标任务。只有该交互才向模型开放 retry_job,执行器仍验证上下文和资源归属。使用这两种交互分别测试一次,不能单靠提示词或按钮外观保证行为。

把运行结果变成面试证据

分类记录“成功 / 失败 / 未测”。确定性脚本验证服务端机制,少量真实模型运行验证选工具与回答质量。分别汇总,保留每种模式的总运行数。下面为填写模板。

模式和场景 成功次数 / 已跑次数 违规写入次数 模型调用次数 / 工具调用次数 端到端耗时、输入输出 token 失败所属层次与修复
固定工作流,A01、A03 待测 待测 待测 待测 记录哪些请求需澄清或转人工
Agent 真实模型,A01、A03 待测 待测 待测 待测 记录工具选择、参数或答案问题
服务端机制,A04、A06–A10 待测 待测 待测 待测 记录权限、幂等、时限与恢复问题

任务成功率可用“完成全部业务断言的运行次数 / 已执行运行次数”。违规写入和跨用户数据暴露单独逐例记录,即使总体成功率高也要定位。比较延迟和 token 时固定模型、数据、问题和工具定义版本;小样本直接列单次结果或范围,便于说明结论适用的范围。

三道复盘题。

  1. “把 prompt 写成必须确认,为什么还要事务?”选 A07 说明提示词约束、用户授权与并发一致性分别由哪一层实现。
  2. “为什么不把所有问题都交给 Agent?”取 A01 和 A03,比较两条路线在真实数据上的完成情况、延迟、成本和灵活性。
  3. “工具成功而回答错误时怎么定位?”找一条轨迹核对查询时刻的状态、回到模型的观察值、引用是否足以支撑结论,以及答案有没有说成已经执行。