> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/agent/code-interpreter.md).

# Code Interpreter（程式碼執行）

程式碼執行工具（Code Interpreter）：讓 Agent 在安全沙盒中撰寫並執行 Python 程式碼——計算、分析資料、處理上傳檔案、繪製圖表、產生 Word／Excel／PowerPoint／PDF 檔案；含沙盒規格、產出檔案下載與搭配技能的說明。

## 這是什麼？ <a href="#what-is-this" id="what-is-this"></a>

Code Interpreter 讓 Agent 能在**安全沙盒環境**中執行程式碼，用程式的方式完成任務。

啟用 Code Interpreter 後，Agent 不再只能用文字回答，它還能：自己寫程式做計算、處理你上傳的檔案、產出 Word／PowerPoint／Excel 等檔案，並把結果交給你下載。

## 跟工具有什麼不同？ <a href="#code-interpreter-vs-tool" id="code-interpreter-vs-tool"></a>

|            | 工具              | Code Interpreter |
| ---------- | --------------- | ---------------- |
| **本質**     | 呼叫已定義好的外部 API   | 在沙盒中即時撰寫並執行程式    |
| **彈性**     | 受限於 API 提供的能力   | 任何 Python 能做的都行  |
| **典型使用情境** | 寄信、查 CRM、串第三方服務 | 計算、資料處理、產生檔案、繪圖  |

**簡單判斷**：要打外部 API → 工具；要算東西、處理檔案、產出文件 → Code Interpreter。

## 能做什麼？ <a href="#what-it-can-do" id="what-it-can-do"></a>

* **資料分析與計算**：CSV／Excel 試算、統計、樞紐、清洗
* **圖表繪製**：把資料畫成折線、長條、圓餅等圖表，圖表中的中文可正常顯示
* **文件生成**：產出 Word、PowerPoint、Excel、PDF 給你下載
* **檔案處理**：解析 PDF、轉換格式、辨識圖片中的文字、批次處理上傳檔案

## 沙盒環境 <a href="#sandbox-environment" id="sandbox-environment"></a>

* 執行環境是**安全沙盒**，與正式系統隔離，不會影響其他資料
* 每段對話有自己的工作區，不同對話之間的檔案互不相通
* 你在對話中上傳的附件（包含先前幾輪上傳的）會自動放進工作區，Agent 可以直接讀取；Agent 也可以把知識庫中的檔案複製進工作區處理

### 沙盒規格與限制 <a href="#sandbox-limits" id="sandbox-limits"></a>

下表為系統預設值，系統管理員可能另行調整。

| 項目                      | 預設值    | 超過時                         |
| ----------------------- | ------ | --------------------------- |
| 單次指令執行時間                | 30 秒   | 指令被中止，Agent 會收到逾時結果並可改用其他方式 |
| 記憶體                     | 512 MB | 程式可能因記憶體不足而失敗               |
| CPU                     | 1 核心   | —                           |
| 每段對話的工作區空間              | 100 MB | 工作區已超過上限時，後續執行會回報空間不足       |
| Agent 以檔案工具直接讀取或寫入的單一檔案 | 10 MB  | 該次讀寫失敗；改用程式處理則不受此限          |
| 單次指令的文字輸出               | 1 MB   | 超出部分被截斷                     |

### 預裝套件 <a href="#preinstalled-packages" id="preinstalled-packages"></a>

沙盒提供 Python 3（含 pip）、bash、Node.js 與 npm，下列套件不需安裝即可使用：

| 用途        | 套件與工具                                                                           |
| --------- | ------------------------------------------------------------------------------- |
| 資料分析      | numpy、pandas、scipy、sympy、scikit-learn、statsmodels                               |
| 圖表        | matplotlib（已設定中文字型）、seaborn                                                     |
| Office 文件 | openpyxl、xlsxwriter、python-docx、python-pptx、markitdown；Node.js 的 docx、pptxgenjs |
| PDF       | reportlab、fpdf2、pypdf、pdfplumber、PyMuPDF、pdf2image、qpdf、poppler                 |
| 圖片與文字辨識   | Pillow、cairosvg、pytesseract（Tesseract 支援繁中、簡中、英、日、韓）                            |
| 網頁資料      | requests、beautifulsoup4、lxml                                                    |
| 文件轉檔      | LibreOffice、pandoc                                                              |

### 可以安裝套件或連外網嗎？ <a href="#packages-and-network" id="packages-and-network"></a>

* **安裝套件**：可以用 `pip install` 安裝額外套件，但只在**該次執行**有效，下一次執行要重新安裝。Agent 會把安裝與使用寫在同一次執行中。
* **連外網**：沙盒可以透過 HTTP／HTTPS 連到外部網站，例如下載公開資料或呼叫公開 API。若要固定串接某個外部系統，建議改用[工具](/build/tools.md)。

### 同一段對話內會保留什麼 <a href="#state-persistence" id="state-persistence"></a>

| 會保留                                 | 不會保留                      |
| ----------------------------------- | ------------------------- |
| 工作區中的檔案（含 `/tmp` 的暫存檔），後續幾輪對話都能繼續使用 | 程式在記憶體中的變數與狀態，每次執行都是全新的程式 |
| 已產出、可下載的檔案                          | 用 `pip install` 臨時安裝的套件   |

### 地端部署 <a href="#on-premise" id="on-premise"></a>

地端部署的沙盒規格與能否連外網，依部署設定與機房網路政策而定，可能與上表不同，請洽系統管理員確認。

## 產出檔案：存在哪裡、保留多久、怎麼下載 <a href="#output-files" id="output-files"></a>

* **存在哪裡**：Agent 要給你的檔案會放在工作區的 `/workspace/outputs/` 資料夾，跟著這段對話保存。
* **保留多久**：產出檔案跟著對話保存；對話被刪除後就無法再下載。
* **怎麼下載**：
  * Agent 挑出要交付的檔案時，回覆下方會出現 「已產出 N 個檔案」 卡片，點擊 <mark style="color:blue;">下載</mark>。
  * MaiGPT 與後台對話頁的 <mark style="color:blue;">Output</mark> 面板，列出這段對話所有產出，可下載或預覽。
  * Web Chat 會在右側開啟 <mark style="color:blue;">輸出檔案</mark> 面板，點擊 <mark style="color:blue;">下載</mark>。
  * 以 API 串接時，可用技術人員手冊的[對話產出清單 API](https://docs.maiagent.ai/tech/api-integration/conversation-outputs-api) 取得清單。

{% hint style="info" %}
Output 面板會列出 `outputs` 資料夾中的所有檔案，包含 Agent 修改過程中留下的不同版本。若只需要最終版，可以在提問時請 Agent 用固定檔名覆蓋，或完成後請它刪除舊版。
{% endhint %}

## 搭配技能 <a href="#use-with-skills" id="use-with-skills"></a>

[技能](/build/skills.md)上傳的檔案（範本、腳本、參考資料等）需要搭配 Code Interpreter 才能使用。Agent 同時綁定技能並啟用 Code Interpreter 時，執行該技能會把技能的檔案放進沙盒的 `/workspace/skills/<技能名稱>/`，讓 Agent 直接讀取或執行。

未啟用 Code Interpreter 時，Agent 仍能讀到技能的指令內容，但用不到技能的檔案。技能檔案的上傳方式見[技能管理](/build/skills/skills-management.md)。

## 適合的場景 <a href="#when-to-use" id="when-to-use"></a>

* 內部財務／銷售團隊請 Agent 整理 Excel、產出每週報表
* HR／行政請 Agent 把問卷結果做成圖表、產出 PowerPoint
* 法務／合約團隊請 Agent 從 PDF 抽取關鍵欄位、輸出 Word 摘要
* 任何需要「即席計算」或「即席生成檔案」的對話場景

## 我需要做什麼？ <a href="#what-do-i-need-to-do" id="what-do-i-need-to-do"></a>

需要 <mark style="color:blue;">AI 助理權限</mark>，且對該 Agent 有編輯權限。

1. **進入 Agent 設定**：從左側選單進入 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">AI 助理</mark>，開啟要設定的 Agent
2. **切換為 Agent 模式**：在 <mark style="color:blue;">回答模式設定</mark> 的 <mark style="color:blue;">回答模式</mark> 選擇 <mark style="color:blue;">Agent 模式</mark>
3. **開啟 Code Interpreter**：打開 <mark style="color:blue;">Code Interpreter</mark> 開關並儲存
4. **測試**：在對話中請 Agent 做一件需要計算或產檔的任務，確認能在回覆或 Output 面板下載

在 MaiGPT 中使用時，成員的角色也需要開放 <mark style="color:blue;">Code Interpreter</mark>，見 [MaiGPT 角色使用權限](/org/roles/maigpt-role-permissions.md)。

## 費用 <a href="#billing" id="billing"></a>

Agent 每成功執行一次沙盒動作（執行指令、寫入或讀取檔案、搜尋工作區檔案等），就依「Code Interpreter」計費項目扣一次 Credits；執行失敗不扣。這是 AI 回覆本身的模型用量之外的費用，費率見 [Credits 計費制度](/others/credits.md#pricing-tab)。

## 常見問題 <a href="#faq" id="faq"></a>

### 產生一個檔案，Output 面板卻出現好幾個？ <a href="#faq-many-files" id="faq-many-files"></a>

Agent 在修正或重做時，常會另存新檔名（例如 `report_v2.docx`），舊版也留在 `outputs` 資料夾。請以最新的檔案為準，或在提問時要求只保留最終版。

### 回覆裡沒有下載連結？ <a href="#faq-no-download-link" id="faq-no-download-link"></a>

檔案不一定出現在回覆文字中。請查看回覆下方的 「已產出 N 個檔案」 卡片，或打開 <mark style="color:blue;">Output</mark>（Web Chat 為 <mark style="color:blue;">輸出檔案</mark>）面板。

### 下載時顯示「檔案已過期，請重新產生後再下載」？ <a href="#faq-file-expired" id="faq-file-expired"></a>

代表這個檔案已不存在，例如之後的執行把它刪除或改名。請 Agent 重新產生一次即可。

### 處理大型檔案或長時間運算失敗？ <a href="#faq-large-task" id="faq-large-task"></a>

可能超過[沙盒規格與限制](#sandbox-limits)。可以請 Agent 分批處理、先篩選需要的欄位，或把資料拆成較小的檔案再上傳。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/agent/code-interpreter.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.