# Code Execution

Code Execution is compatible with **only Azure OpenAI models**. It is strongly recommended that Code Execution is used with **Azure OpenAI GPT-5 or later.**

# Functionality

The Code Execution tool allows users to direct models to write and run Python code within a safely containerized execution environment to solve complex problems in subjects such as math, data analysis, and coding. This tool enhances the natural language capabilities of models with deterministic code-based logic.

## Use Cases

The Code Execution tool lets users run Python against their own data and files directly from chat. Common capabilities:

- Analyze uploaded CSV/XLSX: compute metrics, build charts, forecast trends, detect outliers  
- Perform reliable calculations — sums, totals, filters, subtotals — eliminating hallucinated numerical answers  
- Read macro-enabled Excel files (.xlsm) as data — macros will not execute  
- Export results as XLSX, DOCX, CSV, and PNG  
- Generate Word (DOCX) reports with formatted text, figures, and custom templates  
- Create Excel models with financial projections and year-over-year growth tables  
- Compare two Excel files and generate a structured difference report  
- Generate PowerPoint presentations from uploaded templates (quality varies — see Limitations)  
- Translate and reformat documents (text-layer PDFs work best; complex layouts are best-effort)  
- Upload up to 10 files at once, max 100 MB per file

### Triggering Code Execution

The orchestrator automatically invokes Code Execution when appropriate. Users can also explicitly trigger it with phrases such as:

- "Use code to…"  
- "Create a file…"  
- "Generate a visualisation…"  
- "Using code, calculate…"

### Common Workflow Examples

| **Use Case**         | **Setup**               | **Example Prompt**                                           |
|----------------------|------------------------|-------------------------------------------------------------|
| Excel Q&A            | Upload CSV/XLSX        | "What is total new revenue for this quarter? Use code."  |
| Excel analysis       | Upload dataset         | "Filter by segment X and calculate subtotals for each category." |
| Excel comparison     | Upload two Excel files  | "Compare the two files and generate an Excel difference report." |
| Financial model      | No file needed         | "Create an Excel revenue model with year-over-year growth and a simple forecast." |
| Word report          | Optional: upload template | "Create a Word report on Q3 waste management KPIs with a professional layout." |
| Template-based doc   | Upload Word/PPTX template | "Use the uploaded template to create a report on operational metrics." |
| Document translation  | Upload PDF or Word file | "Translate the uploaded document into French, preserving the structure." |
| HTML dashboard       | Upload data file       | "Using code, generate an interactive HTML dashboard summarising the key metrics." |

## Output Rendering

Code Execution outputs are rendered as interactive cards inline in the chat interface. Users can toggle between the Python source code view and the rendered output view using tabs on each card. The following output types are supported:

| **Output Type**                 | **Description**                                                             |
|----------------------------------|-----------------------------------------------------------------------------|
| Charts & Images (PNG/SVG)       | Rendered inline with responsive scaling, aspect ratio preservation, and one-click copy |
| Tables                           | CSV/tabular data displayed as a styled, horizontally scrollable table with column headers |
| HTML                             | Rendered in a sandboxed preview with the option to download as HTML or PNG                   |
| Files (PDF, DOCX, XLSX, etc.)   | Presented as download cards with type-specific icons and one-click download            |

Each card also includes a **Code View** with Python syntax highlighting, copy, and expand functionality.

## Limitations

- Models are currently restricted to those available through the Azure Responses API. The Unique Quality Assessment team strongly recommends that Code Execution is only used with **Azure OpenAI GPT-5 or later.**  
- **Knowledge Base files are not accessible to Code Execution**  
- **The sandbox has no outbound internet access** — no external API calls or runtime package installs are possible. Live data (e.g. market prices, news) must be retrieved via the Web Search tool and passed into the code interpreter.  
- Upload up to **10 files at once** with maximum file size: **100MB**. Allowed file types: PDF, DOCX, XLSX, PPTX, CSV, HTML, MD, TXT, PNG, JPG, JPEG.  
- **Plotly graphs cannot be directly exported as PNG images** for embedding in PDF, Word (DOCX), or PowerPoint (PPTX) files. The Azure OpenAI code execution container does not include the `kaleido` package, which Plotly requires for static image export. If you need charts embedded as images in exported documents, request that the model use **matplotlib** instead of Plotly.

### What Is Possible vs. Not Possible

| **Capability**                                                                            | **Status**  |
|-------------------------------------------------------------------------------------------|-------------|
| Python execution on user-uploaded files                                                  | Supported   |
| Charts (PNG/SVG via matplotlib), styled tables, DOCX, XLSX artifacts                      | Supported   |
| Excel analysis: sums, filters, subtotals, calculations — real computation, no hallucinated numbers | Supported   |
| Excel macro-enabled files (.xlsm) — readable as data; macros themselves will NOT execute | Partial     |
| Excel model creation: projections, year-over-year growth, forecasts                        | Supported   |
| Compare two Excel files and generate a difference report                                  | Supported   |
| Word (DOCX) report generation with text, figures, and templates                          | Supported   |
| Document translation and reformatting (text-layer PDFs work best)                         | Supported   |
| Up to 10 files / 100 MB per file                                                         | Supported   |
| Malware scanning on all uploads                                                           | Supported   |
| Hide raw Python code from end users (admin flag)                                         | Supported   |
| PowerPoint (PPTX) generation from templates — quality varies; complex decks 10–15 min    | Limited     |
| High-fidelity PDF translation (complex layouts)                                          | Limited     |
| Generalizable templating for arbitrary client document formats                             | Limited     |
| Plotly PNG export for embedding in DOCX/PDF — use matplotlib instead                     | Not supported|
| Excel macro execution                                                                      | Not supported|
| Overwriting original uploaded files — agent creates new files with suffix                 | Not supported|
| Knowledge Base files accessible to Code Execution                                          | Not supported|
| Audio or video processing                                                                  | Not supported|
| Persistent workspace across sessions                                                        | Not supported|

### All available models

The following models expose the `RESPONSES_API` capability and are therefore compatible with Code Execution. This list is derived directly from the tool's `compatible_models` configuration in the codebase.

**Azure OpenAI models**

- `AZURE_GPT_5_2025_0807`  
- `AZURE_GPT_5_MINI_2025_0807`  
- `AZURE_GPT_5_NANO_2025_0807`  
- `AZURE_GPT_5_CHAT_2025_0807`  
- `AZURE_GPT_5_PRO_2025_1006`  
- `AZURE_GPT_51_2025_1113`  
- `AZURE_GPT_51_THINKING_2025_1113`  
- `AZURE_GPT_51_CHAT_2025_1113`  
- `AZURE_GPT_51_CODEX_2025_1113`  
- `AZURE_GPT_51_CODEX_MINI_2025_1113`  
- `AZURE_GPT_52_2025_1211`  
- `AZURE_GPT_52_CHAT_2025_1211`  
- `AZURE_GPT_54_2026_0305`  
- `AZURE_GPT_54_PRO_2026_0305`  
- `AZURE_GPT_55_2026_0424`  
- `AZURE_GPT_55_PRO_2026_0424`  
- `AZURE_GPT_4o_2024_0513` Not recommended  
- `AZURE_GPT_4o_2024_0806` Not recommended  
- `AZURE_GPT_4o_2024_1120` Not recommended  
- `AZURE_GPT_4o_MINI_2024_0718` Not recommended  
- `AZURE_o1_2024_1217` Not recommended  
- `AZURE_o3_MINI_2025_0131` Not recommended  
- `AZURE_o3_2025_0416` Not recommended  
- `AZURE_o4_MINI_2025_0416` Not recommended  
- `AZURE_GPT_41_2025_0414` Not recommended  
- `AZURE_GPT_41_MINI_2025_0414` Not recommended  
- `AZURE_GPT_41_NANO_2025_0414` Not recommended  
- `AZURE_MODEL_ROUTER_2025_1118`

**LiteLLM (OpenAI) models**

- `litellm:openai-gpt-5`  
- `litellm:openai-gpt-5-mini`  
- `litellm:openai-gpt-5-nano`  
- `litellm:openai-gpt-5-chat`  
- `litellm:openai-gpt-5-pro`  
- `litellm:openai-gpt-5-1`  
- `litellm:openai-gpt-5-1-thinking`  
- `litellm:openai-gpt-5-2`  
- `litellm:openai-gpt-5-2-thinking`  
- `litellm:openai-gpt-5-4`  
- `litellm:openai-gpt-5-4-thinking`  
- `litellm:openai-gpt-5-5`  
- `litellm:openai-gpt-5-5-pro`  
- `litellm:openai-o1`  
- `litellm:openai-o3`  
- `litellm:openai-o3-deep-research`  
- `litellm:openai-o4-mini`  
- `litellm:openai-o4-mini-deep-research`  
- `litellm:openai-gpt-4-1-mini`  
- `litellm:openai-gpt-4-1-nano`

# Security & Governance

- No outbound internet, no external API calls, no runtime package installs
- Code runs inside Azure's hosted container — part of the Azure Responses API
- Uploaded files are malware-scanned before processing
- The agent cannot overwrite uploaded files — it always creates new output files with a suffix
- Strict file-type allowlist: PDF, DOCX, XLSX, PPTX, CSV, HTML, MD, TXT, PNG, JPG, JPEG
- Space-level toggle under 'Coding Capabilities' in Space Admin; the orchestrator auto-invokes — there is no manual toggle for end users
- Admins can hide raw Python code from end users via the `enable` flag in the Code Display configuration
- 20-minute inactivity timeout (Azure maximum)
- All actions, generated code, and outputs are fully auditable; privacy risk classified as Negligible
- SOC2/HITRUST-aligned controls: identity, environment separation, logging, and privileged access management

# Configuration

Users **MUST** use Responses V1 API models in order to enable the Code Execution Tool. The following feature flags MUST also be enabled for complete functionality.

| **Name**                           | **Description**                                                    | **Type** | **Default** |
|------------------------------------|--------------------------------------------------------------------|----------|-------------|
| `generatedFilesConfig`             | Configuration for how generated files are displayed, downloaded and uploaded. | Generated files | See below |
| `executedCodeDisplayConfig`       | Configuration for how executed code is displayed.                  | Code Display  | See below |
| `toolConfig`                       | Core tool configuration for the code interpreter.                   | Tool     | See below |

## Generated Files

| **Name**                      | **Description**                                                                                          | **Type** | **Default**                                             |
|-------------------------------|----------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------|
| `fileDownloadFailedMessage`   | The message to display when a file download fails after all retry attempts.                             | `str`    | "⚠️ File could not be generated. Please try again."  |
| `maxConcurrentFileDownloads`  | The maximum number of concurrent file downloads.                                                         | `int`    | `10`                                                 |
| `maxDownloadRetries`          | Maximum number of additional download attempts per container file after the first try (0 = no retries). | `int`    | `2`                                                  |
| `downloadRetryBaseDelay`      | Base delay in seconds for exponential backoff between download/upload retries.                          | `float`  | `0.5`                                                |
| `progressUpdateInterval`      | Minimum seconds between progress message updates sent to the user.                                        | `float`  | `3.0`                                                |
| `downloadChunkSize`           | Chunk size in bytes for streaming container file downloads.                                              | `int`    | `8192`                                               |
| `downloadReadTimeout`         | HTTP read timeout in seconds for container file downloads. Applies per SDK attempt.                     | `float`  | `120.0`                                              |

## Code Display

| **Name**                      | **Description**                                                                          | **Type** | **Default** |  
|-------------------------------|------------------------------------------------------------------------------------------|----------|-------------|  
| `enable`                      | Enable display of executed code before the assistant message.                           | `bool`   | `true`      |  
| `sleepTimeBeforeDisplay`     | Time to sleep before displaying the executed code. Please increase this value if you experience rendering issues. | `float`  | `0.2`       |

## Tool

| **Name**                              | **Description**                                                                                                                    | **Type** | **Default**    |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|----------|----------------|
| `uploadFilesInChatToContainer`       | If set, the files uploaded to the chat will be uploaded to the container where code is executed.                                   | `bool`   | `true`         |  
| `toolDescription`                     | Short description of the tool used to steer tool selection.                                                                         | `str`    | Access via Space management > Sources & Tools > Code Execution > Settings > Configuration > Tool > Tool Description |
| `toolDescriptionForSystemPrompt`     | The full instructions for the tool that are included in the system prompt (file paths, markdown display syntax, visualization library rules, HTML rendering rules, dataframe display, and query handling). | `str`    | Access via Space management > Sources & Tools > Code Execution > Settings > Configuration > Tool > Tool Description for System Prompt |
| `expiresAfterMinutes`                 | Minutes of inactivity after which the container is deleted. Maximum allowed by OpenAI is 20.                                        | `int`    | `20`           |  
| `useAutoContainer`                    | If set, use the `auto` container setting from OpenAI. Note that this will recreate the container on each call.                      | `bool`   | `false`        |  
| `additionalUploadedDocuments`         | Documents (content_ids) to always upload to the container from the Knowledge Base. Useful for example for templates.                | `list`   |                |

# Feature Flags

The following feature flags must be set for code execution to function:

| **Name**                                         | **Value**                                           |
|--------------------------------------------------|----------------------------------------------------|
| `FEATURE_FLAG_USE_OPENAI_V1_13819`               | `true` or list of comma-separated Company ids     |
| `FEATURE_FLAG_ENABLE_CODE_EXECUTION_UN_17498`    | `true` or list of comma-separated Company ids     |
| `FEATURE_FLAG_ENABLE_CODE_EXECUTION_SIDE_PANEL_UN_18787` | `true` or list of comma-separated Company ids     |
| `FEATURE_FLAG_ENABLE_CODE_EXECUTION_FENCE_UN_17972` | `true` or list of comma-separated Company ids     |