X/Twitter AI Agent API 指南：搜索、趋势、Tweet 详情与用户资料

第一个值得做的测试，不是让 LLM 总结 X，而是确认一次搜索返回后，Tweet ID、作者、时间戳和原始链接是否仍然存在。字段一旦丢失，Agent 拿到的就是一段文字，不是证据。

X/Twitter 适合寻找线索，但信息流快速、噪音多。真正重要的设计决定是把发现、核验和执行分开。SandBase 用多个可检查的 Twitter 路由把这条边界具体化，而不是把所有能力塞进一个不透明的“社交搜索”工具。

本文用 SandBase 的 Twitter API 展示一个保守的实现方式：按关键词搜索、读取地区趋势、查询单条 Tweet，再按需补充作者资料。所有示例都通过统一的 POST /v1/run，并将 X 数据层与模型推理层分开。

先说结论

搜索和趋势是发现信号；Tweet 详情和用户资料用于补充上下文。

在交给模型总结前，先保留 ID、时间戳、作者、正文和规范 URL。

Top 结果和互动数是元数据，不是事实证明。

发帖能力应放在人工审批边界之后。

先看结论

用 twitter/web/search-timeline 按关键词发现帖子。
用 twitter/web/trending 获取指定国家或地区的趋势候选。
用 twitter/web/tweet-detail 在发现后查看单条帖子。
只有当作者背景会影响判断时，才调用 twitter/web/user-profile。
先把结果筛成结构化证据，再交给 LLM；不要让模型把“Trending”直接当作事实。
自动研究 Agent 不应默认拥有发帖工具，读取和发布是两种不同的风险边界。

API 覆盖哪些工作

SandBase 的公开 Twitter 目录目前包含搜索、趋势、Tweet 详情、用户资料、媒体、回复、粉丝、关注、评论和转推用户列表等路径。参数和返回字段以实时模型页为准。

图 1：目录把权限边界明确列出来：搜索、趋势、Tweet 详情、用户资料和发帖是独立模型。

四个只读操作足够组成一个最小工具集：

工作	SandBase 模型	常见输入
搜索	`twitter/web/search-timeline`	`keyword`，可选 `search_type`、`cursor`
趋势	`twitter/web/trending`	`country`
Tweet 详情	`twitter/web/tweet-detail`	模型页所示的 Tweet URL 或 ID
用户资料	`twitter/web/user-profile`	模型页所示的用户名或资料标识

把实际测试过的 model slug 固定下来。路由名是集成契约，但不代表上游每个字段永远不变。

直接调用 API

所有操作使用同一个 endpoint 和 Bearer 鉴权：

curl -X POST https://api.sandbase.ai/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -d '{
    "model": "twitter/web/search-timeline",
    "keyword": "AI agent",
    "search_type": "Top"
  }'

返回结果包含结构化 timeline。至少保留 Tweet ID、作者 handle、发布时间、互动字段和原文。不要默认把完整响应全部塞进 prompt，只选择当前研究任务需要的字段。

搜索时间线模型页明确记录了必填的 keyword，以及可选的 search_type 和 cursor。

图 2：模型页是搜索调用的运行契约。

趋势接口支持国家输入。趋势只是发现信号，并不证明它与 AI 相关，也不证明它是自然传播。应先经过自己的主题分类，再消耗模型 token。

图 3：当前模型契约按国家限定趋势范围。

两阶段 Agent 循环

更可靠的做法是先用确定性的 collector，再交给 LLM 研究：

import os
import requests

API = "https://api.sandbase.ai/v1/run"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
    "Content-Type": "application/json",
}

def run(model: str, **inputs) -> dict:
    response = requests.post(
        API, headers=HEADERS, json={"model": model, **inputs}, timeout=30
    )
    response.raise_for_status()
    return response.json()

timeline = run(
    "twitter/web/search-timeline",
    keyword="MCP agent",
    search_type="Top",
)

collector 应该把每条记录归一化成类似下面的证据对象：

{
  "tweet_id": "...",
  "author": "@handle",
  "created_at": "...",
  "text": "...",
  "url": "https://x.com/handle/status/...",
  "source": "sandbase-twitter-search",
  "retrieved_at": "..."
}

只有这一步之后，LLM 才回答“哪些帖子描述了一个新模型发布？”它可以分类、总结并提出后续来源，但不能凭空补充发布日期，也不能把推广帖当成产品证据。

搜索、趋势和详情不是同一件事

搜索适合已知词汇：公司名、模型名、API 功能或协议。趋势适合广泛发现和地区语境。Tweet 详情适合在已经拿到 ID 或 URL 后做核验。用户资料帮助判断账号是官方发布者、维护者、研究者还是高频评论者。

不要把这些操作压成一个“社媒搜索”工具。工具分开后，Agent 的计划更清晰，也能为不同操作设置不同缓存和审批规则。

必须保留的护栏

把互动量当元数据

点赞、转发、浏览和收藏只是 API 返回的活动字段，不证明正确性、产品可用性或真实需求。将它们保存为字段，并在自己的流程中另设“证据强度”。

读写权限分开

目录还展示了 user-post-tweet 能力，但研究 Agent 不应拥有它。如果未来要做人工批准的发布流程，应使用独立审批、可审阅草稿和单独的凭证边界。

缓存必须带时间

缓存键可以是 (model, input, route_version)，同时保存 retrieved_at。X 内容变化很快，时间戳能让审核者区分当前观察和历史快照。超时可以有界重试，但格式错误和鉴权错误不能无限重试。

同时引用原帖与主来源

X 帖子可以是线索，不一定是最终权威。模型发布要追到厂商 release note 或文档；API 能力要核对 SandBase 实时模型页和供应商文档，再进入 Blog。

SandBase 处在什么位置

当研究 Agent 同时需要社媒发现、模型、搜索、媒体或其他真实世界 API 时，SandBase 可以统一这些入口。X collector 仍然是结构化 API 调用，LLM 仍然是推理层，最终结果可以成为简报、工单或 Blog 研究笔记。分层后，失败更容易定位，密钥也能留在服务端。

可以从 Twitter 搜索时间线 API 开始，只有在流程需要时再加入趋势和 Tweet 详情。更大的社媒数据架构可参考面向 AI Agent 的社媒数据 API 指南。

常见问题

Agent 能自动向 X 发帖吗？

目录里有发帖能力，但本文故意不使用。发帖是外部副作用，需要人工批准、可审阅草稿和独立凭证，不应成为默认研究工具。

不是。它只是线索。仍要检查相关性、重复度、主来源、搜索意图，以及 SandBase 是否有真实且准确的贡献。

要把每条 Tweet 都交给 LLM 吗？

不需要。先筛选和归一化，只传递相关字段可以降低成本、减少 prompt injection 暴露，也更容易审计证据链。