AIエージェント画面の動くデモ
このページでわかること
このページでは、Snowflake Cortex Agents の答えがどんなイベントの列として届き、それをどの部品に割り当てると画面になるかを、 動くデモで確認できます。全体像の「画面を作るときに決めること」を、実際に動かして見るページです。
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.table | SQL の結果セットと表題 | 表のカード | 数字の書式、並べ替え、ダウンロード |
| response.chart | Vega-Lite の仕様(文字列) | グラフのカード | 描画ライブラリ、配色、ダークモード |
| response.text.delta | 答えの文字 | 答えの文章(少しずつ伸びる) | Markdown として描くか |
| response.text.annotation | 引用(検索結果の文書の題・抜粋) | 本文の [1] と、出典の一覧 | どの位置に番号を付けるか、元の文書へ飛ばすか |
| response.warning | 致命的でない注意 | 答えの下の小さな注意 | 目立たせすぎない |
| error | エラーのコードと文 | エラー表示と再試行 | 利用者向けの言い方と次の手 |
| response | 最後のまとめ(全体の内容と状態) | 完了の合図。評価ボタンを出す | 履歴に保存する形 |
3. 受け取りのコード
fetch でストリームを読み、空行ごとにイベントを取り出して振り分ける最小の形です。TypeScript・Python の Cortex Agent SDK(プレビュー)を使えば、この受け取りの部分は任せられます。
// 自作の画面から 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 を呼びます。
次に読む
- 用語集の「画面と通信」:agent:run・SSE・tool_use_id・run_id などの意味
- Snowflake のAIエージェントの全体像:画面の手前で決まっていること