setup-python-tools

Python ツール実行のセットアップ

この Dune アプリに、Pyodide を使ったクライアント側の Python ツール実行を追加します。

対象：$ARGUMENTS

背景

Atlas エージェントでは、CDF 設定に Python ツール（type: "runPythonCode"）を定義できます。 エージェントがツールを呼び出すと、toolConfirmation（自動許可）に続いて clientTool アクションが届きます。ライブラリはエージェント設定からツールの Python コードを 自動的に取得し、提供された pythonRuntime を介して実行します。

必要な作業は次のとおりです。

1. usePyodideRuntime をセットアップしてランタイムインスタンスを取得する
2. pythonRuntime を useAtlasChat に渡す

PythonToolConfig エントリは不要です。ライブラリはエージェントの CDF 設定からコードを読み込みます。

処理の流れは次のとおりです。

1. usePyodideRuntime が Pyodide を読み込み（約30MB、初回読み込み後はキャッシュされます）、パッケージをインストールし、 Cognite SDK の認証情報を Python 環境に注入します
2. エージェントが Python ツールを呼び出すと、ライブラリはエージェントの CDF 設定からコードを取得し（セッションごとにキャッシュ）、 ラップして Pyodide で実行し、結果を返します

---

ステップ 1 — アプリを把握する

変更を加える前に、次のファイルを確認してください。

• package.json — パッケージマネージャーと既存の依存関係を確認します
• useAtlasChat を呼び出すコンポーネント — 現在のツールと設定を把握します

---

ステップ 2 — Pyodide をインストールする

アプリのパッケージマネージャーを使用して、必ず [email protected] をインストールしてください。 このバージョンは、実行時に読み込まれる CDN アーティファクトと一致している必要があります。異なるバージョンをインストールするとエラーが発生します。

• pnpm → pnpm add [email protected]
• npm → npm install [email protected]
• yarn → yarn add [email protected]

注：@cognite/dune-industrial-components、@sinclair/typebox、ajv、ajv-formats は すでにインストールされているはずです。インストールされていない場合は、それらもインストールしてください（integrate-atlas-chat スキルを参照）。

---

ステップ 3 — usePyodideRuntime をセットアップする

useAtlasChat を呼び出すコンポーネントに、Pyodide ランタイムフックを追加します。

import { loadPyodide } from "pyodide";
import { usePyodideRuntime } from "@cognite/dune-industrial-components/atlas-agent/pyodide";
import { useAtlasChat } from "@cognite/dune-industrial-components/atlas-agent/react";

function MyChat() {
  const { sdk, isLoading } = useDune();

  // Initialize Python runtime (loads Pyodide, installs packages, sets up Cognite SDK)
  const {
    runtime: pythonRuntime,
    loading: pythonLoading,
    progress: pythonProgress,
    error: pythonError,
    isReady: pythonReady,
  } = usePyodideRuntime({
    loadPyodide,
    client: isLoading ? null : sdk,
    requirements: ["pandas", "numpy"],    // optional — additional packages
  });

  // ... useAtlasChat below
}

フック API リファレンス

戻り値フィールド	型	説明
runtime	PythonRuntime | undefined	初期化済みのランタイム。準備ができていない場合は undefined
loading	boolean	Pyodide の読み込み／初期化中は true
error	string | null	初期化に失敗した場合のエラーメッセージ
progress	{ stage: string; percent: number }	UI に表示する現在の初期化の進行状況
isReady	boolean	便利な判定値：!loading && !error && runtime !== undefined

読み込み状態の UI

読み込みインジケーターは、メッセージ一覧ではなくチャット入力欄の上に配置します。 コンパクトに保ち、ステージのテキストと割合を表示するピル／バッジにします。エラーバッジは別に表示します。 初回の読み込みには約30～60秒かかります（約30MBをダウンロードします）。2回目以降はブラウザーのキャッシュから読み込まれ、2秒未満です。

{/* Loading — shown above the input while Pyodide initializes */}
{pythonLoading && (
  <div className="flex items-center gap-2 rounded-lg border bg-muted/50 px-3 py-2 text-sm text-muted-foreground">
    {/* Optional: <IconBrandPython /> from @tabler/icons-react */}
    <span>{pythonProgress.stage || "Initializing Python..."}</span>
    {pythonProgress.percent > 0 && pythonProgress.percent < 100 && (
      <span className="text-xs opacity-70">({pythonProgress.percent}%)</span>
    )}
  </div>
)}

{/* Error — shown if init fails (after loading finishes) */}
{pythonError && !pythonLoading && (
  <div className="flex items-center gap-2 rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
    <span>Python runtime failed to load</span>
  </div>
)}

---

ステップ 4 — useAtlasChat に接続する

ランタイムを useAtlasChat に渡します。それだけで完了です。ツール設定は不要です。

const { messages, send, isStreaming, progress, error, reset, abort } = useAtlasChat({
  client: isLoading ? null : sdk,
  agentExternalId: "my-agent",
  tools: [renderTimeSeries],   // regular client tools (declared to agent), if any
  pythonRuntime,               // from usePyodideRuntime — enables Python tool execution
});

注：Python ツールは tools を使ってエージェントに宣言しません。エージェントはすでに CDF 設定から認識しています。ライブラリは必要に応じてコードを自動的に取得します。

---

ステップ 5 — Python の読み込み中は入力を無効にする

ランタイムの準備ができる前に、ユーザーがメッセージを送信できないようにします。状態を明確にするため、 送信ボタンだけでなく入力エリア全体を無効にしてください。

<ChatInput
  onSend={handleSend}
  disabled={isStreaming || pythonLoading}
  // ...
/>

候補チップを表示するホームページがある場合は、そちらも無効にしてください。

<ChatHomePage
  onSuggestionClick={handleSuggestionClick}
  disabled={pythonLoading}
/>

---

完了

これで、アプリは Pyodide を介してクライアント側で Python ツールを実行できます。エージェントが Python ツールを呼び出すと、ライブラリがエージェント設定からコードを自動的に取得し、ブラウザー内で実行して、 結果をエージェントに返します。