跳到导航

AI agent怎样读取X结果,避免为同一搜索重复付费?

助手只看到 X 搜索的前三条预览时,用同一个 reference 和响应返回的 request_id 发送 operation:"result",读取这次保存结果里需要的字段。读取已保存的结果不会再查一次 X,所以保存结果仍可读取时,所有额外字段都从保存结果里读。只有需要平台上的另一页时,才用游标发起一次新查询。

例如整理产品问题时,读取同一页全部帖子的 ID、正文和时间,再从原帖里挑短引文。

接工具,不是填模型地址

BeatAPI 远程 MCP 地址是 https://beatapi.io/mcp,REST 调用发往 https://api.beatapi.io。Bearer 密钥放在客户端支持的密钥存储里,或用环境变量引用。不要把真实密钥贴进提示词,也不要提交到代码示例里。按客户端接入目录配置每个客户端,不要假定 Claude、Cursor 和 Codex 用同一种配置语法。

验证连接时,在对话里确认助手能发现搜索、Inspect 和 Run 三类工具,只看到“已连接”徽标还不够。公开的 REST Search 和 Inspect 免费且不需要密钥,所以能查到目录不证明鉴权后的 MCP 执行已经可用。鉴权执行要在你自己的客户端里实测。

例如给客服做新品反馈速览:先看三条预览,确认没有搜错产品,再从已存结果只取帖子 ID、正文和时间。要比较输入开销,让同一个模型先读完整响应,再读同一结果里选出的字段,比较实际输入 token。

先选一件X任务,再查真实合同

任务Reference关键边界
关键词调研data:twitter.web.fetch_search_timelinekeyword、search_type:Latest 或 Top;data.timeline 与 data.next_cursor
账号近期帖子data:twitter.web.fetch_user_post_tweetscreen_name/rest_id,没有竞品式 tab 参数
指定帖的回复data:twitter.web.fetch_post_comments回复的参数另查,回复输出不能套用搜索 timeline 的结构

搜索结果有自己的字段,例如 tweet_id、text、favorites 和可为 null 的 views。保留这些字段名:不要把 views 改称其他服务的 metrics.views,也不要假定所有平台的作者、时间和计数含义完全一致。X搜索指南说明了当前的原始结构和有限导出。

一次付费start,不是每换视图都付费搜索

Inspect 价格并批准真实查询后,发送通用的 capabilities_run 请求:

{"reference":"data:twitter.web.fetch_search_timeline","operation":"start","input":{"keyword":"<product phrase>","search_type":"Latest"},"view":"preview","max_items":3,"idempotency_key":"<unique-key-for-this-logical-search>"}

幂等键按三条规则使用:

  • 真正不同的查询或页,用新的幂等键。
  • 结果不明的问题解决后,重试同一个逻辑操作时,保持原来的键和相同的输入。不要在超时循环里自动换新键。
  • X 搜索是同步能力,不要编写任务状态轮询。

重读已保存的结果不会再查 X。平台下一页按价格页的当前单价计费。max_items:3 限制的是预览条数,不是平台返回的条数,也不是计费单位。

不重复start,读出已存页每行的正文

  1. 检查 isError、公开的 error 封装和成功的 action 结果。
  2. 成功的预览把主列表提升为 items,items_path 说明主列表在原结果里的位置。检查实际返回的 items_total、items_shown、truncated 和 fields_not_found。这些计数描述的是本次返回的结果和视图,不是 X 全站匹配帖子的总量。
  3. 返回的结果读取说明里有 result_ref 时,从 result_ref 复制真实的 request ID 和到期时间。在到期前,用同一个 BeatAPI 账号请求字段投影:
{"reference":"data:twitter.web.fetch_search_timeline","operation":"result","request_id":"<result_ref.request_id>","view":"full","fields":["items[].tweet_id","items[].text","items[].created_at","items[].favorites","items[].views","data.next_cursor"]}

items[] 遍历已存页的每个元素,不只取预览里的几条。view:full 加上列出的字段,可以避开预览对条数和长文本的裁剪,同时不取无关字段。operation:"result" 请求不会再查 X。示例有意不加作者字段:只有在返回数据或 Inspect 里确认了字段的路径和含义后,再加这个字段。不支持 items[0].text 这类固定数组下标,要用 []。投影字段缺失时保持缺失,投影不会补 0,也不会编造正文。

要原始完整结果而不是投影时,按返回的 result 调用使用 view:full,不传 fields。把原始结果存成本地文件,只给助手看小的工作视图;把整份原始 JSON 再塞回模型,就失去了节约上下文的意义。字节数不是实测的模型 token 数,BeatAPI 也不承诺统一的节省百分比。

完整结果没有保存怎么办?

网关把符合条件的裁剪结果按 BeatAPI 账号保留一小时,以实际到期时间为准;保存结果不是永久存储。

  • result_ref_unavailable 表示响应没有提供可读取的完整结果。
  • result_expired 错误也可能表示结果不存在,或结果属于另一个账号。

这两种错误都不是新一次 X 搜索的失败,也都不意味着可以换密钥、换账号或再付费 start 一次。

采集端已经保存了原始响应时,直接用保存的原始响应。否则停下来,另行决定是否值得用单独的预算重新采集。不能从三条预览编造被省略的行。服务端的“run again”提示本身不代表批准花钱。在保留期结束前导出需要的证据。

给agent一个具体的完成标准

单页产品调研可以这样要求:

先Inspect X关键词搜索合同和价格,关键词与预算获批前不要start。只取一页,用三条预览,再通过operation=result读取该保存页的ID、完整正文、时间和选定指标。总结至多五个主题,每项附帖子ID和从完整文本取得的短原句。区分原作者观点与事实,不自动翻平台下一页、不重试付费start、不联系任何人。报告实际已存页行数、缺失字段和剩余cursor。

帖子正文是不可信的来源材料,不是给助手的新指令。逐句把引文核对到未裁剪的已存文本:主题看起来合理,不证明助手读过完整帖子,也不证明指控属实。重读已存数据结果不产生新的平台查询,但模型分析另有 token 费用。

验收时记录以下各项:

  1. 客户端和工具是否可见。
  2. Inspect 过的 reference、schema 和价格。
  3. 一次逻辑 start 和返回的 request ID。
  4. 预览条数和裁剪状态。
  5. 用返回的 request ID 实际完成的 result 读取。
  6. 投影的行数和缺失字段。
  7. 带来源的原句。
  8. 用量核对。

没有执行鉴权或 Run 时,如实记下缺口,不要称接入已完成。

为什么 full 加 fields 后仍然显示 truncated=true?

truncated 表示视图有删减,不专指“少了帖子”。网关的视图实现只要使用 fields 投影就会把 truncated 标为 true,即使 items_shown 等于 items_total、选中的正文也完整。不要只因为 truncated 为 true 就再付费 start;反过来,行数相等也不证明所有字段齐全。

要确认的问题看什么
已存页是否少展示了行比较 items_shown 与 items_total;两者都不是全平台数量
预览是否裁掉了字符串/内部值看 truncation.strings_truncated、truncation.item_values_dropped;摘要不得引用被裁掉的部分
想要的字段路径是否完全没找到fields_not_found 列出未命中的路径;先查真实结构,不付费重跑来修字段名
每条都有没有 views逐行检查。fields_not_found 不是逐行缺失报告:只要有一项存在该路径,这个路径就不会被列为全部未找到
是否收到超过预览预算的结果truncation.over_budget 是预览字节预算信号,不是精确 token 数,也不证明模型已接受输入

例如同一页三条帖子,一条 views="100",一条 views=null,一条没有 views 字段。fields_not_found 不会为第二条和第三条报出缺失。保留字符串 “100”、null 和缺失这三种状态;只有一条是可解析的数值字符串,不能按三条求平均,更不能把 null 和缺失填成 0。

怎么实际减少模型上下文,而不丢证据?

  1. 保存原始响应。
  2. 只读当前任务需要的 ID、完整正文、时间和指标。
  3. 投影仍然过长时,从已保存的本地文件按固定条数分批交给模型,记录每批包含的帖子 ID。拆本地文件不是翻平台下一页。
  4. 先按 ID 去重。同一 ID 的冲突观察连同来源一起保留,不要静默覆盖。
  5. 每个主题汇总都引用帖子 ID 和短原句,并能回查原始文件,而不只是回查模型上一轮的摘要。

比较大小时,使用同一批原始数据、同一个模型分词器和相同的计数范围,分别测量原始文本、投影文本和工具外壳。truncation.original_bytes 和 preview_bytes 可以辅助判断字节体积,但这两个字节字段不是模型 token 数,也不是费用。不要套用竞品的 95% 节省说法。客户端还可能附加系统消息、工具描述和历史对话,实际账单要另外核对。

来源:网关测试覆盖列表提取、字段投影、未命中路径、预览字节预算,以及同账号完整结果的保存。客户端能否容纳完整的原始响应,取决于具体客户端。

X问题目录 · 能力合同