analyze-data

データ分析

DataVoyager エージェント（Cloud Run 上でホストされ、asta-gateway 経由でアクセス）を使用して、マルチエージェントのデータサイエンスパイプラインを実行します。エージェントはサンドボックス化されたノートブックで呼び出し元のデータセットに対するコードを記述・実行し、調査上の質問に回答します。認証には asta auth login を使用します。

ステップ 1 — 質問を具体化する

ユーザーに何かを尋ねる前に、リクエストと周辺のコンテキスト（現在のプロジェクト、会話履歴、作業中のファイル）を分析し、具体化した分析上の質問を作成します。その質問は次の条件を満たす必要があります。

• 分析対象となる具体的なデータセットを明記する
• 単に「X を分析する」ではなく、ユーザーが求める判断や知見を示す
• DataVoyager が実際にコードで回答できる質問にする

例：

• ユーザーが「この CSV を見て」と言った場合 → ファイルパスを確認し、可能であれば先頭の数行を調べ、次のような具体的な質問を作成します：「sales_q3.csv のどの列が、地域を調整したうえで、四半期売上と最も強く相関していますか？」
• ユーザーが「タイタニックのデータには何がある？」と言った場合 → 「titanic.csv では、生存を予測するうえで最も有効な特徴量は何ですか？ また、乗客クラスと性別によって生存率はどう異なりますか？」
• ユーザーが具体的なデータセットについて具体的な質問をした場合 → その質問をそのまま繰り返します

ステップ 2 — チャットで質問を 1 つ提示して確認する

チャットで（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 回実行します。

1. 質問 — <tightened> と <alternative reframe> を比較します（代替の言い換えがある場合）
2. 範囲 — 「焦点を絞る（単一の仮説）」／「探索的（複数の観点）」
3. 追加のコンテキスト — フリーテキストで「DataVoyager がデータについて把握しておくべきことはありますか？」と尋ねます（フィールドの意味、既知の注意点など）

回答を質問文に反映します。

ステップ 4 — 送信する

submit を 1 回呼び出すと、セッション 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>...] を実行します。新しいファイルがある場合は既存のコンテキストに追加され、ファイルを渡さない場合はエージェントが既存のファイルを再利用します。同じデータセットを使って新しいセッションを開始するには、--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 を渡し、分析上の問いに基づくスラッグを指定してください。パスの規則、マニフェスト、index.yaml の処理は Asta Artifacts が担当します。

ステップ 7 — ユーザー向けの要約

次の順に提示します。

1. インデックス登録と探索用パス — 2 通りの閲覧方法を示す短いブロックを 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. 1 段落の統合的な要約 — 今回の実行内容に合わせて、2～4 文で新たに作成します。主な発見は何か、データが示した結果はユーザーの予想とどう異なるか、意外な点や留意事項は何か、分析で当初の問いに答えられたかを伝えます。ここは裁量に任されます。定型文を使わず、出力を確認して要約してください。

3. 主な発見／チャートの表 — 注目すべき知見または図ごとに 1 行を設けます。発見、1～2 文の詳細、該当する場合は チャートのファイル名を記載します。

生の JSON をそのまま出力しないでください。エージェントが実行したすべての手順を繰り返さないでください。最後に「ご希望であれば……」といった要約を付け加えないでください。探索用ブロックで、ユーザーが次に進む方法はすでに案内しています。

参考資料

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