> 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/maiagent-user-guide/en/build/agent/code-interpreter.md).

# Code Interpreter (Code Execution)

Code Interpreter: lets an Agent write and run Python code in a secure sandbox to calculate, analyze data, process uploaded files, draw charts, and generate Word/Excel/PowerPoint/PDF files; includes sa

## What is it? <a href="#what-is-this" id="what-is-this"></a>

Code Interpreter lets an Agent run code in a **secure sandbox environment** to complete tasks programmatically.

With Code Interpreter enabled, an Agent can do more than answer in text: it can write programs to perform calculations, process files you upload, generate Word/PowerPoint/Excel files, and let you download the results.

## How does it differ from tools? <a href="#code-interpreter-vs-tool" id="code-interpreter-vs-tool"></a>

|                       | Tools                                                           | Code Interpreter                                         |
| --------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
| **How it works**      | Calls predefined external APIs                                  | Writes and runs programs on demand in a sandbox          |
| **Flexibility**       | Limited to the capabilities the API provides                    | Can do anything Python can do                            |
| **Typical use cases** | Sending email, querying a CRM, integrating third-party services | Calculations, data processing, file generation, charting |

**Quick guide**: calling an external API → tools; calculating, processing files, or generating documents → Code Interpreter.

## What can it do? <a href="#what-it-can-do" id="what-it-can-do"></a>

* **Data analysis and calculations**: CSV/Excel calculations, statistics, pivot tables, data cleaning
* **Charting**: create line, bar, pie, and other charts from data, with proper display of Chinese text
* **Document generation**: create Word, PowerPoint, Excel, and PDF files for download
* **File processing**: parse PDFs, convert formats, recognize text in images, and batch-process uploaded files

## Sandbox environment <a href="#sandbox-environment" id="sandbox-environment"></a>

* Runs in a **secure sandbox**, isolated from the production system, without affecting other data
* Each conversation has its own workspace; files are not shared across conversations
* Attachments you upload in a conversation (including those from earlier turns) are automatically placed in the workspace for the Agent to read directly; the Agent can also copy files from the knowledge base into the workspace for processing

### Sandbox specifications and limits <a href="#sandbox-limits" id="sandbox-limits"></a>

The table below lists system defaults. Your system administrator may adjust them.

| Item                                                               | Default    | When exceeded                                                                               |
| ------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------- |
| Execution time per command                                         | 30 seconds | The command is terminated; the Agent receives a timeout result and can try another approach |
| Memory                                                             | 512 MB     | The program may fail due to insufficient memory                                             |
| CPU                                                                | 1 core     | —                                                                                           |
| Workspace storage per conversation                                 | 100 MB     | Once the workspace exceeds the limit, subsequent operations report insufficient storage     |
| Single file read or written directly by the Agent using file tools | 10 MB      | That read or write fails; processing the file with code is not subject to this limit        |
| Text output per command                                            | 1 MB       | Output beyond the limit is truncated                                                        |

### Preinstalled packages <a href="#preinstalled-packages" id="preinstalled-packages"></a>

The sandbox provides Python 3 (with pip), bash, Node.js, and npm. The following packages are available without installation:

| Purpose                     | Packages and tools                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Data analysis               | numpy, pandas, scipy, sympy, scikit-learn, statsmodels                                                                    |
| Charts                      | matplotlib (configured with Chinese fonts), seaborn                                                                       |
| Office documents            | openpyxl, xlsxwriter, python-docx, python-pptx, markitdown; docx and pptxgenjs for Node.js                                |
| PDF                         | reportlab, fpdf2, pypdf, pdfplumber, PyMuPDF, pdf2image, qpdf, poppler                                                    |
| Images and text recognition | Pillow, cairosvg, pytesseract (Tesseract supports Traditional Chinese, Simplified Chinese, English, Japanese, and Korean) |
| Web data                    | requests, beautifulsoup4, lxml                                                                                            |
| Document conversion         | LibreOffice, pandoc                                                                                                       |

### Can I install packages or access the internet? <a href="#packages-and-network" id="packages-and-network"></a>

* **Installing packages**: you can install additional packages with `pip install`, but they are available only for **that execution** and must be reinstalled for the next execution. The Agent installs and uses them within the same execution.
* **Internet access**: the sandbox can access external websites over HTTP/HTTPS, for example to download public data or call public APIs. For a persistent integration with an external system, use [tools](/maiagent-user-guide/en/build/tools.md).

### What persists within a conversation? <a href="#state-persistence" id="state-persistence"></a>

| Persists                                                                                                    | Does not persist                                                             |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Files in the workspace (including temporary files in `/tmp`), available for later turns in the conversation | Variables and program state in memory; each execution starts a fresh program |
| Generated files available for download                                                                      | Packages temporarily installed with `pip install`                            |

### On-premises deployment <a href="#on-premise" id="on-premise"></a>

For on-premises deployments, sandbox specifications and internet access depend on deployment settings and data center network policies, and may differ from the table above. Contact your system administrator for details.

## Output files: location, retention, and downloads <a href="#output-files" id="output-files"></a>

* **Location**: files the Agent provides are placed in the workspace's `/workspace/outputs/` folder and saved with the conversation.
* **Retention**: output files are saved with the conversation; once the conversation is deleted, they can no longer be downloaded.
* **How to download**:
  * When the Agent selects files to deliver, a “N files generated” card appears below the response. Click <mark style="color:blue;">Download</mark>.
  * The <mark style="color:blue;">Output</mark> panel in MaiGPT and the admin conversation page lists all outputs from the conversation for download or preview.
  * Web Chat opens an <mark style="color:blue;">Output files</mark> panel on the right. Click <mark style="color:blue;">Download</mark>.
  * For API integrations, use the [Conversation Outputs API](https://docs.maiagent.ai/tech/api-integration/conversation-outputs-api) in the technical manual to retrieve the list.

{% hint style="info" %}
The Output panel lists all files in the `outputs` folder, including different versions left during the Agent's edits. If you only need the final version, ask the Agent to overwrite a fixed filename in your prompt, or ask it to delete older versions when finished.
{% endhint %}

## Using skills <a href="#use-with-skills" id="use-with-skills"></a>

Files uploaded to [skills](/maiagent-user-guide/en/build/skills.md) (templates, scripts, reference materials, etc.) require Code Interpreter. When an Agent has both a skill assigned and Code Interpreter enabled, running the skill places its files in the sandbox's `/workspace/skills/<技能名稱>/` directory for the Agent to read or execute directly.

Without Code Interpreter, the Agent can still read the skill's instructions, but cannot use its files. For how to upload skill files, see [Skill Management](/maiagent-user-guide/en/build/skills/skills-management.md).

## Suitable scenarios <a href="#when-to-use" id="when-to-use"></a>

* Internal finance/sales teams ask an Agent to organize Excel data and generate weekly reports
* HR/administrative teams ask an Agent to chart survey results and generate PowerPoint presentations
* Legal/contract teams ask an Agent to extract key fields from PDFs and produce Word summaries
* Any conversation that requires on-demand calculations or file generation

## What do I need to do? <a href="#what-do-i-need-to-do" id="what-do-i-need-to-do"></a>

You need <mark style="color:blue;">AI Assistant permissions</mark> and edit access to the Agent.

1. **Open Agent settings**: from the left menu, go to <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">AI Assistants</mark> and open the Agent you want to configure
2. **Switch to Agent mode**: under <mark style="color:blue;">Response Mode Settings</mark>, select <mark style="color:blue;">Agent Mode</mark> for <mark style="color:blue;">Response Mode</mark>
3. **Enable Code Interpreter**: turn on the <mark style="color:blue;">Code Interpreter</mark> switch and save
4. **Test**: ask the Agent to perform a task that requires calculations or file generation, and confirm that you can download the result from the response or Output panel

For use in MaiGPT, the member's role must also allow <mark style="color:blue;">Code Interpreter</mark>. See [MaiGPT Role Permissions](/maiagent-user-guide/en/org/roles/maigpt-role-permissions.md).

## Billing <a href="#billing" id="billing"></a>

Each successful sandbox action by an Agent (running a command, writing or reading a file, searching workspace files, etc.) deducts Credits once under the “Code Interpreter” billing item. Failed actions are not charged. This charge is separate from model usage for the AI response itself. For rates, see [Credits Billing](/maiagent-user-guide/en/others/credits.md#pricing-tab).

## FAQ <a href="#faq" id="faq"></a>

### Why are there several files in the Output panel when I asked for one? <a href="#faq-many-files" id="faq-many-files"></a>

When correcting or redoing work, the Agent often saves a new filename (such as `report_v2.docx`), leaving older versions in the `outputs` folder. Use the latest file, or ask it to keep only the final version in your prompt.

### Why is there no download link in the response? <a href="#faq-no-download-link" id="faq-no-download-link"></a>

Files do not always appear in the response text. Check the “N files generated” card below the response, or open the <mark style="color:blue;">Output</mark> panel (<mark style="color:blue;">Output files</mark> in Web Chat).

### Why does the download show “The file has expired. Please regenerate it before downloading”? <a href="#faq-file-expired" id="faq-file-expired"></a>

The file no longer exists, for example because a later execution deleted or renamed it. Ask the Agent to regenerate it.

### Why does processing a large file or a long computation fail? <a href="#faq-large-task" id="faq-large-task"></a>

The task may exceed the [sandbox specifications and limits](#sandbox-limits). Ask the Agent to process it in batches, filter the required columns first, or split the data into smaller files before uploading.


---

# 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/maiagent-user-guide/en/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.