social-app/docs/plans/2026-03-11-agent-multimodal-smoke-runbook.md

Agent Multimodal Smoke Runbook

Goal: 固化 agent 三条主链路（runs/events/history）的真实冒烟标准与输入基线。

1. 覆盖范围

1. POST /api/v1/agent/runs - 接收多模态消息（文本+图片）
2. GET /api/v1/agent/runs/{thread_id}/events - SSE 事件流，事件名符合 AG-UI 标准（RUN_STARTED、STEP_STARTED、TOOL_CALL_*、RUN_FINISHED/RUN_ERROR）
3. GET /api/v1/agent/runs/{thread_id}/history - 返回 STATE_SNAPSHOT，含 attachments metadata
4. sessions/messages 落库完整：message_count、tokens、cost、latency、title、metadata
5. tool result 存储：大 payload 写 storage，metadata 记录 storage_bucket/storage_path
6. storage bucket 来源：必须来自环境变量 SOCIAL_STORAGE__BUCKET

2. 固定测试输入

• 图片夹具：backend/tests/fixtures/images/calendar_text_cn.png
• 多模态消息：
  • 文本："识别图片中的日历内容并调用 calendar.write 创建日程"
  • 图片：{"type":"binary","data":"<base64>","mimeType":"image/png"}

3. 账号与凭据

• 冒烟账号：dagronl@126.com / 123456
• 通过环境变量注入：AGENT_LIVE_EMAIL、AGENT_LIVE_PASSWORD

4. 执行命令

AGENT_LIVE_INTEGRATION=1 \
AGENT_LIVE_EMAIL="dagronl@126.com" \
AGENT_LIVE_PASSWORD="123456" \
uv run pytest tests/integration/v1/agent/test_sse_flow_live.py::test_agent_runs_events_history_live_with_image_input -q -s

5. 结果记录模板

• thread_id / run_id
• runs 状态码与响应
• events 事件序列
• history 是否含 attachments[].bucket/path/mimeType
• sessions 字段：message_count / total_tokens / total_cost / status / title
• messages 字段：role / content / metadata / tokens / cost / latency
• tool_result 是否写 storage

6. 安全注意

• 禁止将密码/token 写入 git 跟踪文件

7. 已修复问题清单

问题	修复内容
bucket 写入失败回退	改为直接报错，禁止回退到硬编码 bucket
user.resolve 工具	新增按 email/name 解析 user_id
calendar.write 邀请参数	增加 invite 参数透传
inbox_repository 缺失	修复 calendar runtime 依赖
runtime 模型名拼接	修复无效 model name
多模态透传	runtime 透传 binary.data，不过滤为 <omitted>
sessions.title 生成	首条用户消息持久化时自动生成
assistant latency 入库	messages.latency_ms 列写入
intent/execution 阶段消息落库	新增 text.* 和 tool.result 事件
DIRECT_RESPONSE 早返回	intent 判定后直接返回，不进入 report 阶段

8. 待修复问题（用户新增）

1. 意图/执行阶段 tokens/cost 入库 - 目前仅 report 阶段入库
2. 连续会话记忆测试 - 验证 session 是否从数据库读取历史上下文
3. 工具调用测试 - calendar 读/写/删/分享 + 用户查找 + 时间感知
4. session 失败排查 - 找出最新失败原因并修复