Jiajun的技术笔记

从问答走向动作闭环

普通聊天程序的核心流程是将用户问题发给模型，再展示模型生成的文本。若任务要求读取外部系统中的真实信息，仅靠语言模型本身并不能完成。例如，用户希望查询订单进度时，程序需要先取得订单状态，再根据订单信息查询物流服务，最后把结果组织成答复。

Agent 的关键变化是增加了动作与结果的反馈路径。模型在当前上下文中决定下一步，如果需要外部能力，就提出结构化工具调用；应用程序校验调用参数并执行工具，再把结果交回模型。模型可以继续分析新结果、提出下一次调用，或者给用户最终答复。任务结束条件由系统明确控制，而不是无限循环地继续调用。

一个最小工具调用循环

可以将最小循环拆成几步：接收目标、整理必要上下文、向模型提供可用工具定义、获取模型的答复或调用请求、由执行器运行工具，再把执行结果写回任务状态。每轮都要检查是否已完成、是否需要补充信息，以及是否已经达到调用次数或运行时间上限。

模型提出调用不等于工具已经执行。工具执行器应解析参数并验证格式，确认调用的工具在允许范围内，再调用实际系统接口。执行结果应以明确的数据结构返回模型，便于区分成功结果、可恢复错误和不可执行请求。这样的边界让模型负责提出动作，应用程序负责权限与副作用控制。

在订单示例中，用户先提出查询请求，模型可能判断需要订单查询工具；程序返回订单状态和物流标识后，模型再判断是否需要查询物流。若用户没有提供可识别的订单号，系统可以要求补充信息，而不是猜测一个值。每一步都依赖真实工具返回，最终答复也应区分已查到的事实和仍未知的部分。

Agent 的主要组成

文章将 Agent 拆分为若干职责。模型根据当前信息提出下一步动作；Prompt 描述角色、工作规则和输出约束；工具定义可调用能力，执行器负责校验并实际执行。上下文管理器组织本轮需要提供给模型的信息，避免无关历史无限累积。记忆系统保存可能在后续任务中有用的信息，并按需检索。

此外，Agent 还需要任务状态与调度器跟踪进度、暂停恢复和结束条件。观测与评估负责记录执行轨迹，帮助判断任务是否成功以及结果是否可信。这些组件起初不一定要拆成独立服务，可以先实现为一个程序内的函数和数据结构；当系统变复杂时，再按职责演进。

上下文与记忆要分开考虑

上下文是某一轮模型调用能够看到的信息集合，通常包括用户目标、近期对话、工具说明、任务状态和相关记忆。随着任务变长，原样追加所有历史会带来成本和噪声。上下文管理需要选择当前决策所需的信息，保留关键事实、最近结果和待办状态，并对冗长内容进行压缩或摘要。

记忆则关注跨轮次、跨任务的信息存取。文章举例说明可以保存用户明确设置的语言偏好，再在以后需要时检索。记忆不应成为不加选择的对话归档：要区分短期任务数据和长期偏好，记录信息来源和更新时间，并提供用户可理解的修改或清除方式。检索出的信息也需要进入当前上下文并接受相关性判断。

对涉及订单等业务对象的任务，优先从可靠业务系统读取当前事实，避免把旧对话中的状态当作最新结果。上下文中的“上次查到订单正在运输”可能已过时，若用户再次询问，应重新查询或明确标注信息时间。这样可以降低记忆造成事实漂移的风险。

工具执行中的验证和边界

工具是 Agent 与外部系统交互的接口。每项工具定义应描述用途、参数和返回结构，帮助模型选择适当能力。程序收到调用后仍需做参数校验、身份授权和操作范围检查。对有副作用的操作，例如写入、删除或提交交易，通常还要增加确认、幂等键或审计记录，避免模型输出错误导致不可逆结果。

错误也应分层处理。参数格式错误可以要求模型修正；业务系统暂时不可用可以按有限策略重试；权限不足则应停止调用并说明限制。工具输出应尽量结构化并控制大小，避免返回大量无关文本占满上下文。执行器还可以记录工具名称、参数摘要、时间和结果状态，供开发调试和后续评估。

工具调用数量和任务持续时间需要设上限。系统可根据任务类型决定最大轮数、超时和预算；循环达到边界时，应该暂停、汇总已完成内容或询问用户，而不是继续消耗资源。明确停止条件可以让长任务更稳定，也方便用户理解系统当前进度。

长任务的状态与恢复

长任务可能跨越多个工具调用，甚至需要暂停等待外部条件。任务状态应记录目标、已完成步骤、已有证据、待处理事项、最近错误和下一步计划。调度器据此决定继续、等待、重试或结束。将状态显式保存，比只依赖越来越长的模型对话更容易恢复和诊断。

恢复任务时，需要判断上次工具调用是否已经产生副作用。若结果未知，简单重试可能重复创建资源或重复提交操作；可通过幂等标识、状态查询或人工确认处理不确定结果。任务状态中的每项完成记录也应有来源和时间，便于区分模型推断与工具确认事实。

如何评估 Agent 是否完成任务

Agent 能够调用工具并不意味着任务正确结束。观测与评估需要检查结果是否引用了工具返回的信息、是否满足用户目标、有没有超出授权范围，以及是否遵守调用次数和时限。保存执行轨迹可以帮助开发者复现失败步骤，找出是模型选择错误、参数校验不足、工具响应异常，还是上下文管理丢失了关键数据。

一个实用的开发顺序是先实现单一工具和短任务，再逐步增加多步调用、上下文裁剪和记忆。每种新增能力都应设计成功与失败样例：缺少参数、工具返回空结果、工具超时、用户中途修改目标，以及任务达到预算边界。通过这些案例检查系统是否能停在安全且可解释的状态。

从小程序逐步扩展

《如何写一个 Agent》把复杂系统拆成模型、Prompt、工具、执行器、上下文、记忆、任务状态和观测等职责。开发者可以从一个有明确数据源的单一任务开始，先实现受控的工具调用循环，确保参数验证和结束条件可靠，再评估是否需要长期记忆或任务调度。组件可以随着需求增长逐步分离，而不必在最初就搭建庞大框架。

Jiajun 的技术笔记还收录 TiDB 源码阅读、Go 与 Kubernetes 实践、基础设施维护和开发工具等内容。近期 Agent 文章提供了从简单问答扩展到多步行动系统的概念地图，适合配合具体代码和任务逐步实践。构建真实应用时，权限、数据正确性、上下文长度和副作用边界都需要由程序显式管理。