setup-python-tools

设置 Python 工具执行

为 $ARGUMENTS 添加客户端 Pyodide 执行支持。如果应用使用 Atlas / EOS 侧边栏（integrate-fusion-agent），则跳过此步骤。

**前提条件：**需要 integrate-atlas-chat 中的 src/atlas-agent/，以及 @sinclair/typebox。将 integrate-atlas-chat/code/ 中的 python.ts、pyodide.ts、pyodide-react.ts、pyodide-runtime.ts 复制到 src/atlas-agent/。

CDF runPythonCode 工具会以 toolConfirmation + clientTool 的形式到达。接入 usePyodideRuntime，并将 pythonRuntime 传给 useAtlasChat——无需添加 PythonToolConfig 条目。Pyodide 约 30MB，首次加载后会缓存。

---

第 1 步——了解应用

开始修改前，先阅读以下文件：

• package.json——检查包管理器和现有依赖
• 调用 useAtlasChat 的组件——了解当前的工具和配置

---

第 2 步——安装 Pyodide

使用应用的包管理器安装准确版本 [email protected]。 此版本必须与运行时加载的 CDN 资源匹配——安装其他版本会导致错误。

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

@sinclair/typebox 应已由 integrate-atlas-chat 安装。如果缺少，请添加。

---

第 3 步——设置 usePyodideRuntime

在调用 useAtlasChat 的组件中，添加 Pyodide 运行时 Hook：

import { loadPyodide } from "pyodide";
import { usePyodideRuntime } from "./atlas-agent/pyodide-react";
import { useAtlasChat } from "./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-60s（下载约 30MB）；之后从浏览器缓存加载只需 <2s。

{/* 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
});

注意：不要通过 tools 向 Agent 声明 Python 工具。Agent 已通过其 CDF 配置了解这些工具。库会在需要时自动获取代码。

---

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

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

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

如果有带建议选项卡片的主页，也要禁用这些选项：

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

---

完成

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