atai-task-verification-agent

用途

TVA Agent（Task Verification Agent）用于在流程（SOP）已知的前提下，检查一段录像是否按该流程执行。典型问题如：操作员是否安装了 O 型圈、是否拧紧了接头、是否贴了胶带。它为 SOP 的每个步骤返回一条判定，每条判定包含状态、时间范围和理由。

主要能力

输入一段 .mp4 录像和一份 .txt 格式的 SOP。
平台对视频采样帧、用 whisper 转写音频，并通过 newton-fusion 将两者与 SOP 融合，一次处理输出每步判定。
TVA V1 为零样本模式，蓝图固定使用 newton-fusion:1.0 和 whisper:large-v3，无需拟合分类器，也无需传递 artifacts map。
每次运行可携带自己的 SOP：.txt 通过 source.text -> prepare.in 路由，因此一个 bundle 可服务多份 SOP。

使用方式

Agents API 无版本前缀，文件 API 位于 /v0.5 下。主要端点：

POST {endpoint}/v0.5/files —— 上传视频，再上传 SOP
POST {endpoint}/agents/bundles —— 创建 bundle（注意是复数）
POST {endpoint}/agents/bundles/{bundle_id}/run —— 启动运行，返回 202
GET {endpoint}/agents/instances/{agent_id}/logs —— 日志流
GET {endpoint}/agents/instances/{agent_id}/results —— 输出引用
POST {endpoint}/agents/instances/{agent_id}/cancel —— 停止运行

注意：POST /agents/bundle（单数）返回 404，应使用复数 /agents/bundles。Agents API 已在生产部署（https://platform.u1.archetypeai.app）上线。

编写 SOP

每行一个步骤，保存为 .txt。PrepareSOPNode 会把各行累积为一条准备好的指令，因此换行即步骤边界，折行会静默变成两个步骤。示例：

Step 1: Install the rubber O-ring into the blue block-off cap, ensuring it is properly seated in the groove. Step 2: Thread the blue cap onto the black manifold by hand until snug, without cross-threading. Step 3: Using a wrench, tighten the blue cap to the specified torque.

该蓝图没有 prompt 值，系统消息位于 TaskVerificationPromptGeneratorNode 内部且不暴露，因此 SOP 措辞是影响模型的唯一途径。建议：使用显式 Step N: 前缀；写明颜色和材质；使用行为性描述而非数值（如“拧紧至规定扭矩”而非“12 Nm”）；每行只写一个动作。

上传输入

POST {endpoint}/v0.5/files（multipart/form-data，字段名 "file"），返回 {"is_valid": true, "file_id": "clip.mp4", "file_uid": "fil_…"}。视频与 SOP 各上传一次。声明的 Content-Type 会按 MIME 白名单校验（video/mp4 和 text/plain），而非按字节。运行负载中使用 file_id（basename），不要用 file_uid。

命名建议：视频与 SOP 共享同一 stem，并附加 UTC 时间戳和 4 位十六进制后缀以保证唯一性。因为组织共享一个扁平文件命名空间，file_id 即 basename，重名上传会替换排队运行将要读取的对象，导致运行中出现 S3 object not found。

适用场景

流程已存在，需要判断是否被遵循。
需要筛选哪些录像应交给人工观看。

限制与注意事项

验证的是对象“存在性”而非“执行过程”。实测 12 段含故意遗漏的 3 步装配视频：遗漏 O 型圈 6 次中 0 次检出，遗漏扳手 3 次中 3 次检出。模型可靠回答“这个东西是否出现在视频中”，若出现则假定动作已发生。reason 读起来像观察，但并非观察——修改 SOP 中一个形容词，该形容词会出现在模型对所见内容的描述中。不要将 reason 作为审计记录展示给用户，也不要将其置信度作为信号。重写 SOP 无法修复此问题（尝试了七种变体，均返回相同错误判定或无判定）。应为 PASSED 判定安排人工复核。
输出预算与推理块共享。f1-0 在回答前输出 thinking…</think>，推理会消耗 max_new_tokens。若在推理中耗尽，解析器无内容可解析，任务仍报告 job.completed 且无 ERROR，但 results: []。因此信任任何运行前先检查 /results 非空。实测 2026-08-20 在 2048、5760、8192、16384 四种预算下，12 次运行 36 条判定，预算不影响结果；决定正确性的是画面中缺失的内容。
results: [] 是真实可能的结果，需显式检测：/results 必须非空；invalid 不应在所有行上为 "true"；读取 /logs 中的 WARN。WARN 中 dropping N 较大表示答案已生成但被丢弃，应降低预算；较小或为 0 表示预算不是杠杆。
sink 格式需从蓝图文档读取。未注册连接器的 sink 会在图实例化时失败（约 7 分钟模型加载后），/results 为空。check_sink() 读取 connectors.sink.config.format 并给出警告而非拒绝。
不要将输出视为审计轨迹。PASSED 判定不是步骤发生的证据。

不适用场景

尚无流程，需要从视频中提取流程：使用 atai-manual-generation-agent（mga）。
对片段提出单个无状态问题：使用 atai-newton-fusion-model（/query）。
将传感器窗口分类为运行状态：使用 atai-operational-state-monitoring-agent。
在长录像中检测罕见事件：使用 atai-rare-event-detection-agent。

TVA 与 MGA 的区别：MGA 编写流程，TVA 依据流程检查。