setup-python-tools

设置 Python 工具执行

通过 Pyodide 为此 Dune 应用添加客户端 Python 工具执行功能。

目标：$ARGUMENTS

背景

Atlas Agent 可以在其 CDF 配置中定义 Python 工具（type: "runPythonCode"）。 当 Agent 调用其中一个工具时，会先收到一个 toolConfirmation（自动允许），随后收到一个 clientTool 操作。该库会自动从 Agent 配置中获取工具的 Python 代码，并通过所提供的 pythonRuntime 执行。

你只需要：

1. 设置 usePyodideRuntime 以获取运行时实例
2. 将 pythonRuntime 传递给 useAtlasChat

无需添加 PythonToolConfig 条目——该库会从 Agent 的 CDF 配置中读取代码。

流程如下：

1. usePyodideRuntime 会加载 Pyodide（约 30 MB，首次加载后会缓存）、安装软件包， 并将 Cognite SDK 凭据注入 Python 环境
2. 当 Agent 调用 Python 工具时，该库会从 Agent 的 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 运行时 Hook：

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
}

Hook API 参考

返回字段	类型	描述
runtime	PythonRuntime | undefined	已初始化的运行时；未就绪时为 undefined
loading	boolean	Pyodide 正在加载／初始化时为 True
error	string | null	初始化失败时的错误消息
progress	{ stage: string; percent: number }	当前初始化进度，可用于界面显示
isReady	boolean	便捷属性：!loading && !error && runtime !== undefined

加载状态界面

将加载指示器放在聊天输入框上方，而不是消息列表中。 保持紧凑——使用显示阶段文字和百分比的胶囊／徽标。错误应单独显示为徽标。 首次加载约需 30～60 秒（下载约 30 MB）；之后从浏览器缓存加载仅需不到 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 声明给 Agent。Agent 已从其 CDF 配置中获知这些工具。 该库会在需要时自动获取代码。

---

步骤 5 — 在 Python 加载期间禁用输入

运行时就绪前，用户不应发送消息。请禁用整个输入区域 （而不只是发送按钮），以明确当前状态：

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

如果有带建议选项的首页，也请禁用这些选项：

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

---

完成

现在，应用可以通过 Pyodide 在客户端执行 Python 工具。当 Agent 调用 Python 工具时，该库会自动从 Agent 配置中获取代码，在 浏览器中运行，并将结果返回给 Agent。