analyze-data

数据分析

使用 DataVoyager Agent（托管在 Cloud Run 上，通过 asta-gateway 访问）运行多 Agent 数据科学工作流：Agent 会在沙盒笔记本中针对调用方的数据集编写并执行代码，然后回答研究问题。使用 asta auth login 进行身份验证。

步骤 1 — 拟定一个更明确的问题

在询问用户任何内容之前，分析其请求和周边上下文（当前项目、对话历史、正在处理的文件），拟定一个更明确的分析问题，要求：

• 指明要分析的具体数据集
• 说明用户想做出什么决策或获得什么见解，而不只是“分析 X”
• 将问题表述为 DataVoyager 可以通过代码实际回答的形式

示例：

• 用户说“看看这个 CSV” → 检查文件路径，并尽可能查看前几行，拟定一个具体问题，例如“控制地区因素后，sales_q3.csv 中哪些列与季度收入的相关性最强？”
• 用户说“泰坦尼克号数据里有什么” → “titanic.csv 中哪些特征最能预测生还情况？不同舱位和性别的乘客生还率有何差异？”
• 用户针对特定数据集提出具体问题 → 原样复述

步骤 2 — 通过一个聊天问题确认

在聊天中（不要使用 AskUserQuestion），展示：

拟议分析：

• 数据集：<path> （将上传到你的 DataVoyager 工作区）
• 问题：<tightened>

你可以：

• 回复 yes / go，按当前方案运行
• 回复修改意见（例如 “只关注 Q3”、“忽略缺失值”），我会据此修改问题
• （仅当 AskUserQuestion 可用时）回复 interview，通过表单进一步完善问题

仅当 AskUserQuestion 工具可用时，才包含 interview 这一项。

等待用户回复。处理方式：

1. 肯定回复（“yes”“go”“proceed”“looks good”）→ 步骤 4。
2. 自然语言修改意见 → 更新问题，并重新展示相同提示。
3. “Interview” / “refine” → 步骤 3（需要 AskUserQuestion；如果不可用，则改为在聊天中询问）。

绝不要要求用户预先上传数据集。该技能会负责上传，详见步骤 4；用户只需提供本地文件路径。

步骤 3 — 可选访谈（仅在用户要求时）

使用以下内容触发一次 AskUserQuestion：

1. 问题 — <tightened> 与 <alternative reframe>（如果有替代表述）
2. 范围 — “聚焦（单个假设）” / “探索性（多个角度）”
3. 额外背景 — 自由文本：“DataVoyager 还需要了解哪些数据相关信息？”（字段含义、已知注意事项）

将回答整合到查询字符串中。

步骤 4 — 提交

一次 submit 调用会生成会话 UUID，将文件上传到 context/<uuid>/，并启动分析。响应包含任务 ID（id）和会话 UUID（contextId）；请记录两者，以便轮询和后续操作。

asta analyze-data submit \
  --output "/tmp/analyze-data-$$.json" \
  "<confirmed question>" ./sales.csv ./regions.csv

TID=$(jq -r .id /tmp/analyze-data-$$.json)
CTX=$(jq -r .contextId /tmp/analyze-data-$$.json)

可恢复性。 $CTX 用于标识 DataVoyager 会话。若要在同一工作区中提出后续问题，请运行 asta analyze-data submit --context-id "$CTX" '<follow-up question>' [<new-files>...]。新文件（如有）会附加到现有上下文；如果没有传入文件，Agent 会复用已有文件。若要基于相同数据集启动全新会话，请省略 --context-id 并重新传入文件。

第 5 步 — 轮询

不要在前台循环轮询（会阻塞会话），也不要单独启动 sleep 60 后再检查（较长的初始休眠会阻塞运行环境）。改为在后台运行 poll 子命令——它会在进入终态时退出，运行环境会在任务完成时通知你。

asta analyze-data poll "$TID" --output "/tmp/analyze-data-$TID.json"

使用 run_in_background: true 运行。状态更新会输出到 stderr；最终 Task JSON 会写入 --output。收到完成通知后，读取 /tmp/analyze-data-$TID.json 获取最终结果。

任务运行期间，不要主动检查。去处理其他事情或等待——通知是权威信号。如果用户在收到通知前要求检查状态，只有这时才查看后台任务的 stderr。

终态：

• completed → 第 6 步
• failed → 报告 status.message 并停止
• input-required → 转达给用户，然后运行 asta analyze-data send-message --task-id <ID> --context-id "$CTX" '<reply>'，并重新启动轮询循环

运行时间：差异很大（简单的探索性数据分析（EDA）几分钟即可完成；多步骤建模可能需要 20–40 分钟）。约 2 小时内不要直接判定失败。

第 6 步 — 导出和编入索引

交由 Asta Artifacts 技能导出任务输出（表格、图表、笔记本和任何书面分析），并使用 asta-documents 注册每个产物。将 analyze-data 作为调用技能传入，并根据分析问题生成一个 slug；Asta Artifacts 会处理路径规范、清单和 index.yaml。

第 7 步 — 为用户总结

按以下顺序呈现：

1. 索引和探索路径 — 用一个简短的内容块说明两种浏览方式。两种方式都必须包含（用于语义搜索的技能路径，以及用于直接阅读的文件系统路径）：

   已在 .asta/analyze-data/<slug>/index.yaml 中为 N 个产物编入索引。 可通过 asta documents search --summary='<concept>' --root=.asta/analyze-data/<slug> 探索，也可以直接打开目录：open <absolute-path-to-slug-dir>

   使用绝对路径（例如 /Users/.../project/.asta/analyze-data/2026-04-23-…/）。从分析的核心术语中选择 <concept>（具体而非泛泛的术语，例如列名或模型类型）。

2. 一段综合总结 — 用 2–4 句话为本次分析撰写全新的总结。核心发现是什么？数据结果与用户预期有何不同？指出意外发现、注意事项，以及分析是否回答了原始问题。酌情发挥——不要套用模板，要阅读输出并综合概括。

3. 关键发现 / 图表表格 — 每个重要发现或图表占一行：发现 + 1–2 句详细说明 +（如适用）图表文件名。

不要倾倒原始 JSON。不要复述 Agent 执行的每个步骤。不要在结尾补充“如果你还想了解……”，探索路径块已告知用户如何继续。

参考资料

• DataVoyager：https://github.com/allenai/dv-core-asta-integration
• A2A 规范：https://a2a-protocol.org/latest/specification/