用户给 Agent 一个任务：“查一下这项技术的主要方案，整理成飞书文档，发给我。”
几分钟后，聊天窗口里出现了链接，最后一句是“文档已创建，可以查看”。如果把这个项目写进简历，接下来有个问题很值得准备：你凭什么判断它完成了？
链接能打开，正文可能只写进去一半；正文完整，引用可能对应错了；服务账号能读，接收者可能没有权限。每一步都返回过成功，用户仍然可能拿不到想要的东西。
做 Agent 项目时，我会先把“完成”拆开。模型结束回复、工具执行结束、用户目标满足，分别需要证据。把这三件事讲清，工具调用、异常恢复和评测才有共同的落点。
一个文档链接，背后有几次独立操作
先顺着这个研究助手走一遍。模型决定查什么，搜索工具返回候选，网页工具取回正文。模型整理材料，然后请求文档工具，把标题和内容交过去。
文档工具通常还要继续做几件事：创建文档对象，把内容转换成平台接受的块，分批追加正文，再给指定接收者配置访问权限。最后，它才能拼出一个链接，交回 Agent。
这条链路里，前一步成功不会自动保证后一步成功。 创建接口拿到了文档 ID，只能说明一个文档对象已经存在。后面的正文写入和权限设置，仍然各有自己的结果。
例如，正文被拆成几批，第一批写入成功，第二批报错。此时远端可能留下半篇文章。若错误处理中只剩一句“文档创建失败”，恢复程序连该接着写哪份文档都不知道；若只根据最早拿到的 ID 报成功，又会把半成品交给用户。
面试里说“我接了搜索和飞书 API”，还没有解释这段交付过程。能补上哪些操作可能部分成功、每一步留下什么状态，项目就开始有了可检查的细节。
success 字段，究竟在替谁作保证
很多工具接口会返回 success、data、error。这套结构很方便，但需要问一句：谁设置了 success，它检查过什么？
有的执行器在函数没有抛异常时，就把 success 设为 true。它证明函数顺利返回。至于返回值里有没有业务错误、是否只受理了异步任务、数据是否满足当前目标，还需要继续判断。
可以把成功分成三个层次。调用层检查工具名和参数是否合法，执行层检查服务有没有按接口契约处理，任务层检查得到的结果能否兑现用户要求。
放回文档例子：参数中的标题和正文通过校验，属于调用层；创建和追加接口返回符合契约的结果，属于执行层；正文齐全、引用对应、接收者能访问，才进入任务验收。
工具输出里的数字也要看来源。比如 blocks_created，如果它只是转换后准备发送的块数，便不能拿来证明远端已经保存了相同数量。这个字段记录的是本地计划，不包含独立读取的证据。
因此我会把返回结构改得更明确：保留文档 ID、每个批次的状态、权限处理结果，以及后续验收结果。一个总 success 可以留给上层使用，但它的计算规则必须清楚，不能在几个不同层次之间漂移。
