分类：AI编程
当 AI Agent 调用问题追踪系统、数据库或第三方 API 时，返回一个空数组 [] 看似简洁，却可能隐藏多种完全不同的现实：查询成功但没有匹配项、连接器无法读取数据、分页只读到一半、服务限流或请求超时。Dev.to 上一篇关于连接器设计的文章提出，工具接口不应把这些状态压缩成同一个空结果，而应把“部分失败”和“不确定”明确暴露出来，让 Agent 能够判断接下来该停止、重试还是继续读取。
空数组会掩盖不同的业务含义
素材指出，一个返回空数组的连接器可能对应多种结果。对 Agent 来说，“没有匹配的 issue”是有价值的信息；“我无法读取这些 issue”则意味着应当停止或重试。如果两者都变成 []，Agent 只能猜测。
这种猜测在自动化流程中会带来风险。模型可能把读取失败误解为没有匹配结果，也可能把不完整的数据当成完整列表进行汇总。文章建议，连接器结果应该被视为一份“小报告”，而不是单纯的数据载荷。
用元数据描述结果边界
文章给出的示例结果包含多个字段：
status：例如partial，用于说明结果状态；records：实际读取到的记录；source：记录来自哪个连接器、对应什么查询；fetched_at：抓取时间，例如2026-11-13T10:30:00Z；continuation：后续读取所需的游标，例如next-page-token；warnings：例如“后续页面尚未读取”。
文章强调，字段名称只是示意，真正重要的是接口契约：结果要说明自己包含什么内容、来自哪里、何时获取，以及是否完整。对于小型连接器，少量明确状态可能已经足够，但这些状态必须与记录本身分开。错误信息不应被塞进一条看起来正常的记录里，否则 Agent 可能把错误文本当成源数据进行总结。
分页、重试和写操作需要明确状态
在分页场景中，文章建议只有在当前页面被接受之后，才保存 continuation cursor。如果第三页失败，连接器应返回已经读取到的记录，并说明读取在何处停止。下一次运行可以从该位置继续，而不是把不完整列表呈现为完整结果。
这也与重试机制相关。重复读取同一页时，不应在工作集中静默产生重复记录。对于会改变远端状态的操作，如果服务支持幂等键，应使用 idempotency key，并记录操作是否被确认。写操作后的超时需要特别处理：客户端没有收到响应，并不意味着服务器没有接受变更；此时“写是否成功”处于不确定状态。
文章进一步提出，连接器应告诉 Agent 每种状态允许执行什么动作。相比让模型从自然语言描述中推断数据是否完整，直接给出事实更安全。连接器通常知道是否已经读到响应末尾，Agent 应该直接接收这个事实。
让不确定性成为接口的一部分
在测试层面，素材建议覆盖几类典型情况：一次成功的空查询、分页过程中令牌过期、触发限流、遇到格式错误数据，以及一次可能在服务器已接受后超时的写操作。这些用例可以检验接口是否保留了“没有发生任何事”和“不知道发生了什么”之间的差别。
对 AI 应用来说，连接器可靠性不只是拿到可用数据，也包括把不确定性展示得足够清楚，使下一步动作可以被有意识地选择。随着 Agent 越来越多地调用外部工具，工具返回值不再只是数据结果，更是 Agent 判断是否继续、是否重试、是否提示用户的依据。如何向 Agent 说明一个结果并不完整，正在成为工具设计必须回答的问题。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/kong-shu-zu-bu-shi-wei-yi-da-an-ai-agent-de-wai-bu-gong-ju
