为什么数据 API 默认应该是 sync-only

1. LLM 生成工具调用：{"name": "get_user", "args": {"id": "123"}}
2. 运行时执行函数
3. 运行时将结果返回 LLM
4. LLM 带着结果继续推理

# Sync 在 Agent 工具中的样子（SandBase 数据 API 路由）
import os
import requests

SANDBASE_API_KEY = os.environ["SANDBASE_API_KEY"]

def get_douyin_user(sec_user_id: str) -> dict:
    resp = requests.post(
        "https://api.sandbase.ai/v1/api/douyin/app-v3/user-profile",
        headers={"Authorization": f"Bearer {SANDBASE_API_KEY}"},
        json={"sec_user_id": sec_user_id},
        timeout=30,
    )
    body = resp.json()
    outputs = body.get("outputs") or []
    if body.get("status") != "completed" or not outputs:
        raise RuntimeError(f"SandBase call did not complete: {body.get('status')} {body.get('error')}")
    return outputs[0].get("data") or {}
    # 完事。LLM 立刻拿到结果。

# 假想的 async 设计长这样（仅作对比，不是 SandBase 路由）
def get_douyin_user(sec_user_id: str) -> dict:
    task = api.post("/hypothetical-async/user-profile", json={"sec_user_id": sec_user_id})
    task_id = task.json()["task_id"]

    # 现在怎么办？LLM 在等着。
    # 方案 A：循环轮询（阻塞、浪费）
    for _ in range(30):
        result = api.get(f"/tasks/{task_id}")
        if result.json()["status"] == "complete":
            return result.json()["data"]
        time.sleep(1)
    raise TimeoutError("任务 30 秒未完成")

    # 方案 B：把 task_id 返回给 LLM（令人困惑）
    # LLM：「我拿到了一个 task_id，但我需要实际数据……」
    # 现在需要另一次工具调用来检查状态

curl -s -X POST https://api.sandbase.ai/v1/api/douyin/app-v3/user-profile \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sec_user_id": "MS4wLjABAAAA8U_l6rBzmy7bcy6xOJel4v0RzoR_wfAubGPeJimN__4"}'

{
  "status": "completed",
  "model": "douyin/app-v3/user-profile",
  "outputs": [{
    "data": {
      "status_code": 0,
      "user": {
        "nickname": "人民日报",
        "unique_id": "rmrbxmt",
        "enterprise_verify_reason": "人民日报官方账号",
        "follower_count": 203210829,
        "aweme_count": 12276
      }
    }
  }]
}

请求                 → 服务端获取数据 → 响应
POST /v1/api/<model>                 → JSON 信封或错误

# Async：你需要一个任务管理器（假想）
class TaskManager:
    def __init__(self):
        self.pending = {}  # task_id -> 元数据
        self.results = {}  # task_id -> 结果

    async def submit(self, operation, params):
        task = await api.post(operation, params)
        self.pending[task.id] = {"submitted": time.time(), "params": params}
        return task.id

    async def check(self, task_id):
        if task_id in self.results:
            return self.results[task_id]
        result = await api.get(f"/tasks/{task_id}")
        if result.status == "complete":
            del self.pending[task_id]
            self.results[task_id] = result.data
            return result.data
        return None

    async def cleanup_stale(self):
        # 永远没完成的任务……
        for tid, meta in self.pending.items():
            if time.time() - meta["submitted"] > 300:
                # 重试？放弃？记日志？三者都做？
                pass

# Sync：调一下，拿结果
# api = httpx.AsyncClient(base_url="https://api.sandbase.ai",
#                         headers={"Authorization": f"Bearer {SANDBASE_API_KEY}"},
#                         timeout=30)
result = await api.post("/v1/api/douyin/app-v3/user-profile", json={"sec_user_id": sec_uid})
# 完事。无状态。无清理。无过期任务。

try:
    result = await api.post("/v1/api/douyin/app-v3/user-profile", json={"sec_user_id": sec_uid})
    result.raise_for_status()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 429:
        await asyncio.sleep(1)
        result = await api.post("/v1/api/douyin/app-v3/user-profile", json={"sec_user_id": sec_uid})  # 重试
        result.raise_for_status()
    else:
        raise  # 意外错误，冒泡
body = result.json()
outputs = body.get("outputs") or []
if body.get("status") != "completed" or not outputs:
    raise RuntimeError(f"SandBase call did not complete: {body.get('status')} {body.get('error')}")
user = (outputs[0].get("data") or {}).get("user")
if user is None:
    user = {"error": "user_not_found"}  # Agent 优雅处理

{"status_code": 2, "status_msg": null, "user": null}

# 假想：提交成功，但任务 10 秒后失败
task = await api.post("/hypothetical-async/user-profile", json={"sec_user_id": sec_uid})
# 暂时没错误……任务「处理中」

# 稍后检查时：
result = await api.get(f"/tasks/{task.id}")
# result.status 可能是："failed"、"timeout"、"partial"、"expired"
# 这是哪个 sec_user_id 的？需要追踪。
# 能重试吗？也许。但原始上下文已经丢了。

10:00:01.234 → 请求: POST /v1/api/douyin/app-v3/user-profile {"sec_user_id": "MS4w..."}
10:00:03.001 → 响应: 200 OK, 1.77s
10:00:03.002 → LLM 收到结果，继续推理

10:00:01.234 → 提交: POST /hypothetical-async/user-profile
10:00:01.456 → 拿到 task_id: task_xyz
10:00:05.000 → 轮询: GET /tasks/task_xyz → "processing"
10:00:10.000 → 轮询: GET /tasks/task_xyz → "processing"
10:00:15.000 → 轮询: GET /tasks/task_xyz → "failed"
10:00:15.001 → 为什么失败？查看任务详情……
10:00:15.200 → GET /tasks/task_xyz/details → "upstream_timeout"
10:00:15.201 → 重试？再提交一个新任务……

# Agent 的内部推理导致这个序列：
user = await get_user(user_id)
videos = await get_user_videos(user_id, count=10)
engagement = calculate_engagement_rate(videos)
decision = f"该创作者互动率 {engagement}%，{'高于' if engagement > threshold else '低于'}阈值"

# 提交所有任务
user_task = await submit_task("get_user", user_id)
video_task = await submit_task("get_videos", user_id)

# 等两个都完成（其中一个失败怎么办？）
user = await wait_for_task(user_task, timeout=10)
videos = await wait_for_task(video_task, timeout=10)

# video_task 失败了，user 数据还用不用？
# user_task 成功但 video_task 超时，要不要重试？
# 分支逻辑爆炸

# Sync API + 并发客户端
async def get_profiles(sec_user_ids: list[str]) -> list[dict]:
    tasks = [
        api.post("/v1/api/douyin/app-v3/user-profile", json={"sec_user_id": s})
        for s in sec_user_ids
    ]
    results = await asyncio.gather(*tasks)
    return [r.json() for r in results]
    # 挂钟时间 ≈ 最慢的单次调用，而不是总和

文本生成视频、图片生成通常要跑几十秒甚至更久
（粗略估计，因模型而异，不是 SandBase 的测量）。
很难放进一次 HTTP 请求里。

「导出这个视频的所有 10,000 条评论」
需要大量分页请求。

「计算该账号 90 天互动趋势」
需要获取 90 天数据 + 计算。