> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 代码解释器

> 在 ClickHouse 智能体中执行沙箱化代码

[Beta 版功能](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

代码解释器允许 agent 在托管沙箱中执行代码。可将其用于计算、数据转换、格式转换、绘图，以及其他任何更适合用代码而非自然语言完成的任务。

## 启用代码解释器

在 Agent Builder 中，在 **Capabilities** 部分启用 **Run Code**，然后保存。agent会根据用户请求及其自身指令，自行决定何时运行代码。

![Capabilities 面板中的 Run Code 部分，其中 Run Code 复选框已启用，并带有 Upload to Code Environment 按钮](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/run-code/run-code.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=00125f4a580b82198fdd9dc20dc6d25f)

## 支持的语言

该沙箱是一个 Unix 环境，提供两种通用运行时和一些 shell 实用工具：

* **Python 3** - 数据任务的默认选择。
* **Node.js (JavaScript)** - 当agent更适合使用 JS 完成任务时。
* **Bash** 和 **sh** - 用于串接命令和进行快速 I/O 的 shell 脚本。
* **AWK** 和 **sed** - 面向行的文本处理。
* **bc** - 任意精度计算。

凡是涉及数据解析、转换或计算的任务，agent都会优先使用 Python。

> [!TIP]
>
> 仅在任务确实适合用单行命令解决时，才使用 shell 工具。

## 文件

用户可以将文件上传到对话中；代码解释器可在沙箱的工作目录中访问这些文件。代码也可以生成输出文件 (CSV、图表、归档文件) ，并以可下载附件的形式显示在对话中。

## 沙箱隔离

每次执行都会在一个临时沙箱中运行，不提供网络访问，也不提供持久化存储。会话之间不共享状态——除非 agent 明确重新加载，否则某次运行中的变量和文件不会带到下一次运行中。

不同方案的资源限制 (内存、每次运行可用的文件数、每月请求配额) 同样适用。错误和 stderr 会与 stdout 一并显示在对话中。

## 何时使用它

当答案需要依靠确定性计算，而语言模型仅凭推理无法稳定得出结果时，就应使用代码解释器。
典型场景包括：

* 解析用户上传的 CSV 或 JSON 文件。
* 计算汇总统计信息或进行快速模拟。
* 在不同格式之间转换 (Parquet、JSON、CSV) 。
* 根据查询结果生成图表。

> [!TIP]
>
> 对于模型仅凭上下文就能回答的任务，应避免使用它。
> 代码执行会增加延迟，并消耗配额。
