AIエージェント画面の動くデモ

2026-11-14 時点の Snowflake 公式ドキュメント をもとに整理 / 見直し目安:毎月。製品名や機能の状態は変わることがあります。

このページでわかること

このページでは、Snowflake Cortex Agents の答えがどんなイベントの列として届き、それをどの部品に割り当てると画面になるかを、 動くデモで確認できます。全体像の「画面を作るときに決めること」を、実際に動かして見るページです。

1. 動くデモ

「再生」を押すと、記録したイベントが届いた順に流れます。右がそのまま届いたイベント、左がそれを組み立てた画面です。 「イベント名を表示」で部品ごとの元のイベントが、「答えだけ(くるくる)」で途中経過を見せない場合の待ち方が見られます。

0.0 秒
見せ方

先月の店舗別の売上を見せて。いちばん落ちた店は、なぜ落ちたの?

「再生」を押すと、エージェントからイベントが届き始めます。

届いたイベント(1 件)

  1. metadata

イベント名とフィールド名は公式ドキュメントに合わせています。店舗・数字・SQL・文書と、状態の文言は架空の例です。

2つの見せ方を比べると

同じ約11秒でも、「答えだけ」ではその間なにも変わらず、終わった瞬間に全部が出ます。「段階表示」では、考え始め・集計・検索・答えの順に画面が育つので、 待っている理由がわかり、表が出た時点で読み始められます。一方で、出るものが多いと落ち着かないので、考え中の文字は畳み、終わった状態表示は消しています。

2. イベントと部品の対応

デモで使ったイベントを、届く中身・画面の部品・作り手が決めることの3つで並べました。部品は content_index の順に並べ、ツールの呼び出しと結果は tool_use_id で結び付けます。

イベント届く中身画面の部品決めること
response.statusいまの段階(計画中・ツール実行中など)と短い文答えの上の1行の状態表示文言を利用者向けに言い換えるか。終わったら消す
response.thinking.delta考えている途中の文字折りたたみの「考えた道すじ」見せるか。見せるなら、答えが出たら畳む
response.tool_use呼んだツールの種類・名前・入力ツールのカード(「データを集計」「文書を検索」)ツール名を利用者の言葉に直す
response.tool_result.statusツールの中の進み具合(SQL を作成中・実行中)カードの中の小さな状態細かすぎるなら出さない
response.tool_resultツールの結果(Cortex Analyst なら SQL など)カードを「完了」に。SQL を折りたたみで根拠をどこまで見せるか
response.tableSQL の結果セットと表題表のカード数字の書式、並べ替え、ダウンロード
response.chartVega-Lite の仕様(文字列)グラフのカード描画ライブラリ、配色、ダークモード
response.text.delta答えの文字答えの文章(少しずつ伸びる)Markdown として描くか
response.text.annotation引用(検索結果の文書の題・抜粋)本文の [1] と、出典の一覧どの位置に番号を付けるか、元の文書へ飛ばすか
response.warning致命的でない注意答えの下の小さな注意目立たせすぎない
errorエラーのコードと文エラー表示と再試行利用者向けの言い方と次の手
response最後のまとめ(全体の内容と状態)完了の合図。評価ボタンを出す履歴に保存する形

3. 受け取りのコード

fetch でストリームを読み、空行ごとにイベントを取り出して振り分ける最小の形です。TypeScript・Python の Cortex Agent SDK(プレビュー)を使えば、この受け取りの部分は任せられます。

typescript
// 自作の画面から Cortex Agents を呼び、届いたイベントを振り分ける(簡略化した例)
const controller = new AbortController(); // 「止める」ボタンで controller.abort()

const res = await fetch(
  `https://${account}.snowflakecomputing.com/api/v2/databases/${db}/schemas/${schema}/agents/${agent}:run`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      Accept: "text/event-stream",
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: [{ type: "text", text: question }] }],
    }),
    signal: controller.signal,
  },
);

const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value.replace(/\r\n/g, "\n");
  // SSE は空行で1件ずつ区切られる。event: 行が種類、data: 行が中身(JSON)
  let sep: number;
  while ((sep = buffer.indexOf("\n\n")) !== -1) {
    const lines = buffer.slice(0, sep).split("\n");
    buffer = buffer.slice(sep + 2);
    const event = lines.find((l) => l.startsWith("event:"))?.slice(6).trim();
    const data = lines.filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).join("\n");
    if (event && data) dispatch({ event, data: JSON.parse(data) });
  }
}

// 届いたイベントは列に貯め、画面の状態はその列から組み立てる
// (受け直し・巻き戻し・テストがしやすい。このページのデモも同じ作り)
function dispatch(e: { event: string; data: any }) {
  switch (e.event) {
    case "response.status":
    case "response.thinking.delta":
    case "response.tool_use":
    case "response.tool_result.status":
    case "response.tool_result":
    case "response.table":
    case "response.chart":
    case "response.text.delta":
    case "response.text.annotation":
    case "response.warning":
    case "error":
    case "response":
      events.push(e);
      render(buildView(events));
      break;
    default:
      // 知らない種類のイベントは無視する(種類は今後増える)
  }
}

4. 同じ画面を AI に作らせるプロンプト

イベントと部品の対応をそのまま指示にしたものです。コーディング用の AI に貼り付けて使えます。

AIプロンプトテンプレート

Snowflake Cortex Agents の Run API(Server-Sent Events)を受けて描く、チャット画面のコンポーネントを React + TypeScript で作ってください。

## 受け取るイベントと描き方
- response.status:答えの上に1行の状態表示(終わったら消す)
- response.thinking.delta:折りたたみの「考えた道すじ」に追記。答えが出たら畳む
- response.tool_use:ツールのカード。type が cortex_search なら「文書を検索」、cortex_analyst_text_to_sql なら「データを集計」と表示。tool_use_id で結果と結び付ける
- response.tool_result.status:同じカードの中に進み具合を表示
- response.tool_result:カードを「完了」にし、content の中に SQL があれば折りたたみで見せる
- response.table:result_set(resultSetMetaData.rowType と data)を表で描く。数値は桁区切り
- response.chart:chart_spec(Vega-Lite の JSON 文字列)を vega-embed で描く
- response.text.delta:答えの文章に追記(Markdown として描く)
- response.text.annotation:本文のその位置に [番号] を付け、答えの下に出典の一覧(doc_title と抜粋)
- response.warning:答えの下に小さな注意
- error:エラーの文と「もう一度」ボタン
- response:完了。評価ボタン(役に立った/立たなかった)を出す

## 作りの条件
- 届いたイベントは配列に貯め、画面の状態はその配列から組み立てる関数で作る
- 上の一覧にない種類のイベントは無視する
- 「止める」ボタンで AbortController を使って受信を止め、届いた分は残す
- 部品は content_index の順に並べる
- 状態表示には role="status" を付ける

このプロンプトはあくまでたたき台です。AIの回答はモデルやバージョン、会話の文脈によって毎回異なります。意図通りに動かない場合は、条件を追記・修正してお使いください。

よくある質問

Vega-Lite のグラフはどう描けばよいですか?

response.chart の chart_spec は Vega-Lite の仕様が文字列で届くので、JSON として読み、vega-embed などの描画ライブラリに渡します。配色やダークモードは画面の側で上書きできます。このページのデモは、仕様からデータだけを読み、自前の横棒グラフで描いています。

途中で通信が切れたらどうなりますか?

実行そのものはサーバーで続き、run_id を指定してストリームを受け直せます。画面は届いたイベントの列を持っておき、受け直した分を足して組み立て直すと、表示が二重になりません。

「止める」はサーバーの実行も止めますか?

fetch を中断するだけでは受信が止まるだけです。サーバー側の実行を止めるには、実行の中止(cancel)の API を呼びます。

次に読む

出典(公式ドキュメント)

このページに関するニュース