TRYZ / HANDBOOK · 2026

从零构建一个
可靠的 Agent

这不是一篇框架入门,而是一份工程路线图。我们会从一个 30 行的循环开始,逐步加上工具契约、上下文管理、编排、评估与安全边界,直到它可以被信任地放进生产环境。

阅读约 55 分钟 13 CHAPTERS PYTHON / 伪代码 持续更新

00如何使用这本手册

你不需要先选定一个框架。只需要一个能调用模型的 API key、一台能运行 Python 的电脑,以及一个愿意被拆解的真实任务。

STEP 01 先让它跑起来

用一个模型、一个工具和一条停止条件,完成最小可用的闭环。

STEP 02 再让它变可靠

补齐契约、错误处理与上下文策略,让失败可以被解释。

STEP 03 最后证明它变好了

用固定数据集与轨迹指标,把「感觉不错」换成可比较的数字。

手册按 认知 → 工具 → 记忆 → 编排 → 评估 → 上线 六个阶段组织。每一节都可以独立阅读,但建议至少完整走一遍第一章:后面的所有设计,都建立在同一个循环之上。

如果一段代码不能在一次对话里被讲清楚,它大概率也不该成为你系统的第一版。

ef21b9d16acc2d5c272be7f1e26b27de72233788

00.1123

1

01什么是 Agent

一个常见的误解,是把「会调用 API 的聊天机器人」直接叫做 Agent。真正的区别不在于回复有多长,而在于系统是否拥有在运行时做决定的能力:调用哪个工具、传什么参数、看到结果后是否继续,以及什么时候停下来。

模型 + 工具 + 状态 + 循环 Agent

模型负责判断,工具负责把判断变成外部世界的动作,状态让下一步知道上一步发生了什么,而循环提供了「观察—再决策」的机会。少任何一项,系统都会退化成一次性的文本生成。

维度聊天机器人Agent
交互一问一答围绕目标多步推进
决策由用户指定下一步由模型在运行时选择动作
失败答错,重新提问需要重试、回滚或升级处理
观测看单条回复看整条决策轨迹与工具结果
一个够用的判断标准

如果任务既不需要外部信息,也不需要执行动作,更不需要跨步骤保留状态,那就不要做 Agent。一次结构化的模型调用,通常更便宜、更快,也更容易测试。

02最小闭环

先把工程复杂度放在一边。一个最小 Agent 只需要三样东西:一组消息、一组工具定义,以及一个「模型返回工具调用就执行、否则结束」的循环。下面这段伪代码不是某个 SDK 的用法,而是所有 Agent 框架最终都会收敛到的形状。

python / minimal_loop.py
# 消息、工具与预算,构成最小可运行状态
messages = [{"role": "user", "content": task}]
steps = 0

while not finished and steps < MAX_STEPS:
    reply = model.chat(messages, tools=TOOLS)
    messages.append(reply)  # 先保存 assistant 的 tool_calls

    if not reply.tool_calls:
        finished = True
        break

    for call in reply.tool_calls:
        try:
            result = run_tool(call.name, call.args)
        except ToolError as exc:
            result = f"tool failed: {exc}"

        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": result,
        })
    steps += 1
01 / INPUT接收目标

把用户意图与可用工具放进上下文。

02 / DECIDE模型决策

生成回答,或给出结构化的工具调用。

03 / ACT执行工具

校验参数、执行副作用、捕获错误。

04 / OBSERVE回填并收敛

把结果写回上下文,直到触发停止条件。

四个必须写下来的约束

  1. 步数预算

    例如 MAX_STEPS = 6。超过预算就停止并返回当前最佳结果,而不是继续消耗 token。

  2. 停止条件

    模型给出最终回答、达到预算、命中人工审批,或连续两次没有产生新信息。

  3. 工具超时

    每次调用设置独立的 timeout,避免一个卡死的下游拖垮整条轨迹。

  4. 完整轨迹

    记录每一步的输入、工具名、参数、结果与耗时。没有轨迹,后面的评估与调试都无从谈起。

不要用「最大轮数」代替停止条件

轮数只是保险丝。真正的停止条件应该描述业务上的完成状态,例如「已拿到订单状态并给出处理建议」。否则系统只会在预算耗尽时随机停下。

03工具即契约

模型不会读你的源码。它只看到工具的名字、描述和参数 schema。因此,工具定义不是给编译器看的,而是写给一个聪明但没有上下文的同事的操作手册。

json / tools/search_docs.json
{
  "name": "search_docs",
  "description": "在官方文档中检索。仅在需要外部事实时调用;不要用它查询用户私有数据。",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "2-8 个关键词,保留产品名与版本号"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 8
      }
    },
    "required": ["query"],
    "additionalProperties": false
  }
}
契约部分要写清楚什么常见错误
name动词 + 对象,全局唯一search、do_it 这类模糊命名
description何时用、何时不要用、返回什么只写「搜索文档」
schema类型、枚举、范围、必填项全部 optional,参数无约束
结果稳定结构,明确错误字段成功返回 JSON、失败抛裸异常
副作用是否写数据、是否可重试把写操作包装成可自动重试
  • 窄而专:一个工具只做一件事,参数不超过 5 个;需要组合时让模型分两步调用。
  • 可验证:所有参数在执行前做 schema 校验,拒绝未知字段,而不是「尽力猜测」。
  • 有边界:为读操作设置超时与条数上限,为写操作设置权限检查与人工确认。
  • 可解释:错误信息要告诉模型下一步能做什么,例如「订单号不存在,请先调用 get_order」。

工具失败,是设计的一部分

在真实系统里,超时、限流和下游 500 是常态。与其追求「不失败」,不如设计一条可预测的恢复路径:区分可重试与不可重试错误,限制重试次数,并让模型看到结构化的失败原因。

python / retry.py
def call_with_retry(tool, args, attempts=3):
    for i in range(attempts):
        try:
            return tool.run(args, timeout=8)
        except RetryableError:
            time.sleep(2 ** i)  # 1s, 2s, 4s
    raise ToolUnavailable(tool.name)
写操作不要盲目重试

退款、发邮件、创建工单都可能被执行两次。要么为工具提供幂等键,要么在重试前先查询状态。自动重试只应覆盖明确可重试的读操作与幂等写操作。

04上下文工程

Agent 的「记忆」首先是一个预算问题。上下文窗口不是硬盘,放进去的每一个 token 都在增加成本、延迟与干扰。好的记忆策略不是记住一切,而是让当前这一步需要的信息出现在正确的位置。

层级放什么生命周期实现方式
工作记忆当前目标、最近几步、工具结果单次任务消息数组 + 截断策略
会话状态已确认事实、决策、待办多轮对话结构化 checkpoint
长期知识文档、历史案例、用户偏好跨会话检索 + 重排

在上下文逼近上限之前,主动写一个 checkpoint,比事后粗暴截断更可靠。它应该像交接班记录:下一位同事只需要读这一页,就能继续工作。

json / checkpoint.json
{
  "goal": "确认年费会员是否符合退款条件",
  "facts": [
    "订单 #A1024,购买于 2026-03-02",
    "权益尚未使用"
  ],
  "decisions": [
    "依据 7 天无理由条款,进入人工审核"
  ],
  "open_questions": ["支付渠道是否影响退回路径?"],
  "next_action": "get_payment_channel"
}
  • 先测量,再优化

    记录每步的输入 token 数。大多数「上下文太长」的问题,其实来自重复的工具结果和冗长的系统提示。

  • 让检索结果可丢弃

    给每条检索内容标注来源与时间;过期或低相关的内容应被移出上下文,而不是一直累积。

  • 压缩保留决策

    摘要不是把对话写短,而是保留事实、决定、未解决问题与下一步。删掉寒暄,别删掉理由。

检索不是越多越好

先保证召回,再做重排与去重。把 20 段低相关内容塞进上下文,通常不如 4 段高相关内容加一句来源说明。相关性比数量更能决定答案质量。

05工作流与多 Agent

Agent 不是编排的默认答案。当步骤稳定、输入输出明确时,一条确定性工作流往往更便宜、更可控,也更容易做回归测试。先把问题画成流程图,再决定哪一段真的需要模型自由决策。

01 / ROUTE分类意图

规则或小模型判断请求类型,缩小处理范围。

02 / RETRIEVE取回事实

按既定数据源检索,避免模型凭空补全。

03 / GENERATE生成结果

在受限上下文内完成回答或动作草稿。

04 / VERIFY校验放行

规则检查、引用核对,必要时进入人工审核。

场景推荐结构原因
步骤固定、合规要求高确定性工作流可审计、可回放、成本稳定
路径依赖中间结果单 Agent + 工具保留决策灵活性,状态集中
子任务可并行且上下文隔离多 Agent / 子图减少相互污染,缩短关键路径
需要多角色对抗审查生成者 + 评审者用不同提示词制造独立视角

什么时候才值得拆成多 Agent

  • 任务可以真正并行:子任务之间没有顺序依赖,合并结果的成本低于串行执行。
  • 上下文必须隔离:不同子任务的数据不应互相可见,或放在一起会显著降低判断质量。
  • 角色需要独立:生成与审查使用不同目标、不同工具权限,避免「自己批自己」。
  • 你有能力观测:能按子 Agent 维度记录耗时、token、失败率与交接内容,否则调试会失控。
多 Agent 不是能力证明

每增加一个 Agent,就多一份上下文交接、权限边界与失败路径。没有明确的并行收益或隔离需求时,单 Agent 加清晰的工具,通常是更好的第一版。

06评估体系

提示词改动最危险的地方,是它看起来总是「更好了」。评估的作用,是把这种叙事拉回到可比较的事实:同一批输入,同样的判定标准,改动前后到底差在哪里。

指标定义为什么重要
任务成功率满足全部验收条件的样本占比最终效果,但需要足够细的判定
工具正确率调用工具、参数与顺序均正确的比例定位问题在决策还是执行
平均步数完成任务的模型轮次均值反映效率与循环质量
P95 延迟95% 请求的端到端耗时上限用户体验由尾部决定
单任务成本token + 工具调用 + 基础设施成本决定方案能否规模化
json / evals/case-014.json
{
  "id": "refund-policy-014",
  "input": "我昨天买的年费会员能退吗?",
  "must_call": ["get_order", "get_refund_policy"],
  "must_include": ["7 天内", "未使用"],
  "must_not_include": ["随时可退"],
  "max_steps": 5
}
  1. 从真实请求开始

    先收集 30–50 条线上或灰度请求,覆盖常见路径、边界条件和已知失败。不要用模型自己生成的题目当唯一测试集。

  2. 把「通过」写具体

    必须调用哪些工具、必须包含哪些事实、绝不能出现什么。可自动判定的条件优先,主观质量再交给人工或评审模型。

  3. 建立基线再改

    记录当前版本的通过率、步数、延迟与成本。没有基线,任何对比都只是感觉。

  4. 把评估放进 CI

    每次提示词、模型或工具变更都跑同一套用例。通过率下降超过阈值就阻止发布,而不是上线后再回滚。

离线评估与在线抽检缺一不可

固定数据集能防止回归,但无法覆盖真实世界的分布漂移。上线后保留小比例人工抽检与失败样本回收,定期把它们补进评估集。

07可观测性

当 Agent 答错时,你需要的不是「再试一次」,而是能回答三个问题:它看到了什么、它决定了什么、它为什么停下。可观测性不是日志的副产品,而是 Agent 系统的一等功能。

json / trace.jsonl
{
  "trace_id": "tr_8f2a",
  "step": 3,
  "action": "tool.search_docs",
  "input_digest": "sha256:9c1e…",
  "latency_ms": 412,
  "tokens": { "in": 1840, "out": 96 },
  "status": "ok",
  "stop_reason": "answer_ready"
}

至少记录这四类信号

  • 决策轨迹:每一步的模型输出、工具名、参数摘要与观察结果,能按 trace_id 串起来。
  • 性能与成本:每步延迟、token 用量、工具耗时,以及按任务聚合的 P50 / P95。
  • 失败分类:区分模型判断错误、工具错误、参数校验失败、超时与人工中断,而不是统一的 error。
  • 版本信息:模型名、提示词版本、工具版本、代码版本。没有版本号,回放无法复现。
轨迹里也可能有敏感数据

用户输入、工具结果与模型输出都可能包含个人信息。对日志做字段级脱敏与访问控制,设置保留期限;不要把完整 prompt 与密钥一起写进普通日志。

08安全边界

上线前的最后一个问题不是「它能不能做」,而是「它做错时,最坏会发生什么」。Agent 拥有工具权限,也就拥有了把错误放大的能力。安全边界必须写在系统里,而不是写在提示词里。

风险典型表现控制手段
提示词注入网页或文档中的指令改变 Agent 行为隔离不可信内容,工具结果只作为数据
工具滥用越权读取、批量删除、重复扣款最小权限、参数白名单、写操作审批
数据外泄把私有上下文发往外部地址出站域名白名单、敏感字段过滤
失控循环反复调用昂贵工具,成本飙升步数 / 金额 / 时长三重预算与熔断
  1. 最小权限

    每个工具只拿完成当前任务所需的最小权限;读与写分离,生产与测试隔离。

  2. 不可信内容隔离

    把检索到的网页、邮件、文件标记为数据,不让其中的「指令」进入系统提示的权限层级。

  3. 高风险动作人工确认

    退款、删除、对外发送等操作必须经过显式审批,并记录批准人与原始参数。

  4. 预算与熔断

    为单任务设置步数、金额与时长上限。触发上限时安全停止,返回可解释的状态,而不是继续重试。

提示词不是权限系统

「请不要删除数据」无法阻止一个拥有删除权限的模型。真正的边界由代码、权限与审批流构成;提示词只能帮助模型做出更好的判断。

1699999

11789

10延伸阅读

以下资料分别覆盖工具调用、编排、可观测性与安全。建议带着具体问题去读,而不是从头到尾收藏。

99术语表

下面这些词会反复出现在设计评审与故障复盘里。先把定义对齐,再讨论方案。

Agent Loop

模型决策、执行工具、观察结果并再次决策的循环。循环必须有明确的停止条件与预算。

Tool Contract

工具对模型暴露的完整接口:名称、用途、参数 schema、返回结构、错误语义与副作用说明。

Context Window

模型单次调用能看到的 token 上限。它同时是容量约束、成本约束与注意力约束。

Checkpoint

在上下文压缩或任务交接时写下的结构化状态,包含目标、事实、决策、未解决问题与下一步。

Trace

一次任务从开始到结束的完整决策轨迹,按步骤记录模型输出、工具调用、观察结果与耗时。

Eval Set

用于回归评估的固定输入集合,附带可判定的通过条件、期望工具调用与性能预算。

Grounding

让回答建立在可核查的外部事实上,通常通过检索、引用与一致性校验实现。

Guardrail

独立于模型的输入输出检查与权限控制,用于拦截越权、敏感数据与高风险动作。

Human-in-the-loop

在高风险或低置信度节点引入人工确认,让自动化在边界处停下来。