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

# Run Code Tool

> Run code in a secure sandboxed environment with rich output support

## What it does

The Run Code tool (`execute_python`) runs code in a secure sandboxed environment. Perfect for data analysis, calculations, visualizations, and any computational tasks your agents need to perform.

<Note>
  **Run Code is pre-checked when you create an agent.** It's a default-on baseline because it pairs so closely with attachments and knowledge-base files — reading, parsing, and transforming uploaded data. It behaves like any other tool — you can uncheck it at any time. See [Default-on tools](/features/build-an-agent#default-on-tools).
</Note>

## Key features

* Execute Python code in isolated Jupyter notebook cells
* Support for popular libraries (pandas, numpy, matplotlib, etc.)
* **Enhanced output display** with separate sections for different output types
* **Smart output categorization** - stdout, stderr, results, and text outputs are displayed distinctly
* Automatic error handling with detailed tracebacks
* Persistent session state across multiple executions

## Parameters

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `code`    | string | Yes      | The Python code to execute in a single cell |

## Output types & display

The tool now intelligently categorizes and displays different types of output:

### 📤 **Output** (stdout)

Print statements and console output appear in a clean gray section:

```python theme={null}
print("Processing data...")
print("Results calculated successfully!")
```

### 📊 **Result** (expression results)

The final expression result is highlighted in a blue section:

```python theme={null}
# This result will be prominently displayed
42 + 8  # Shows: 50
```

### ⚠️ **Warnings/Errors** (stderr)

Non-fatal warnings and errors appear in an orange warning section:

```python theme={null}
import warnings
warnings.warn("This is a warning message")
```

### 🎨 **Rich Media** (charts, images, etc.)

Visual outputs like charts and images are displayed with full formatting:

```python theme={null}
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [4, 5, 6])
plt.show()  # Chart appears as rich visual content
```

## Common use cases

### Data analysis with clear output

```python theme={null}
import pandas as pd
import numpy as np

# Create sample data
data = {'sales': [100, 150, 200, 175], 'month': ['Jan', 'Feb', 'Mar', 'Apr']}
df = pd.DataFrame(data)

print("Dataset created successfully!")  # Appears in Output section
print(f"Shape: {df.shape}")            # Appears in Output section

df.describe()  # Appears in Result section with rich formatting
```

### Create visualizations with status updates

```python theme={null}
import matplotlib.pyplot as plt

print("Creating visualization...")  # Shows progress in Output

# Create a simple chart
plt.figure(figsize=(8, 6))
plt.plot([1, 2, 3, 4], [10, 20, 25, 30])
plt.title('Sample Chart')
plt.xlabel('X-axis')
plt.ylabel('Y-axis')

print("Chart generated!")  # Confirms completion
plt.show()                 # Chart appears as rich visual
```

### Mathematical calculations with explanations

```python theme={null}
import math

print("Calculating complex formula...")  # Process indicator

# Complex calculations
result = math.sqrt(144) + math.pow(2, 8)
print(f"Square root of 144: {math.sqrt(144)}")  # Step-by-step output
print(f"2 to the power of 8: {math.pow(2, 8)}")

result  # Final result prominently displayed
```

### Error handling demonstration

```python theme={null}
import warnings

print("Starting calculation...")

# This generates a warning (appears in orange section)
warnings.warn("Using deprecated function")

# This works fine
result = 10 * 5
print(f"Calculation complete: {result}")

result  # Final result in blue section
```

## Knowledge base file access

Knowledge base files appear in the sandbox at `/home/user/kb/{kb_id}/` **only when you request them** via the `kb_files` parameter on the `execute_python` call (format `kb/{kb_id}/{filename}`). They are **not** pre-loaded — the directory does not exist until you request a file into it, so `os.listdir('/home/user/kb/{kb_id}/')` without a prior request will fail. Use `list_kb_files` to discover exact filenames first, then pass them in `kb_files`.

You can request files from **any knowledge base in your organization** — the KB does not need to be in the agent's accessible-KB list. Requesting a file mounts both the original binary and its `.md` companion.

### What's available in the sandbox

| File                       | Path                                        | Contains                                                                                                            | How it gets there                                               |
| -------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Original files             | `/home/user/kb/{kb_id}/{filename}`          | The uploaded PDFs, Excel files, `.docx`, etc. — use for binary work (re-rendering templates, opening with openpyxl) | Named in `kb_files`                                             |
| Markdown representations   | `/home/user/kb/{kb_id}/{filename}.md`       | Pre-extracted text content (same as what `read_file` returns for `kb:<file_id>`)                                    | Auto-included with each requested file                          |
| Structured extraction data | `/home/user/kb/{kb_id}/extracted_data.json` | Array of objects with fileId, fileName, uploadDate, plus all extraction schema fields                               | Written for each accessible KB even when no files are requested |

### When to use local files vs KB tools

| Approach                             | Best for                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Read `.md` files in Python           | **Bulk processing** — reading 10+ files at once (e.g., spreading financials, comparing documents, building reports) |
| Load `extracted_data.json` in Python | **Filtering and indexing** — finding which files to process based on structured fields                              |
| `search_knowledge_base` tool         | **Targeted lookups** — finding specific content when you don't know which file has the answer                       |
| `read_file` tool (`kb:<file_id>`)    | **Focused reads** — reading 1-3 specific files, or when you need page images                                        |

<Tip>
  **Performance tip for bulk operations**: Reading `.md` files directly in Python is instant. Each `read_file` tool call requires a round-trip. For agents that process many files (financial analysis, document comparison, portfolio reviews), guide your agent to read files locally instead of making dozens of tool calls.
</Tip>

### Example: bulk processing with local KB files

```python theme={null}
import json

# Step 1: Load the structured index (extracted_data.json is available for accessible KBs
# without an explicit request)
with open('/home/user/kb/{kb_id}/extracted_data.json') as f:
    index = json.load(f)

# Step 2: Filter to the files you need
target_files = [f for f in index if f.get('status') == 'APPROVED']

# Step 3: Request those files via kb_files on THIS execute_python call, e.g.
#   kb_files=[f"kb/{kb_id}/{entry['fileName']}" for entry in target_files]
# then read their .md companions directly — no per-file tool calls needed
for entry in target_files:
    md_path = f"/home/user/kb/{kb_id}/{entry['fileName']}.md"
    with open(md_path) as f:
        content = f.read()
    # Process content...
```

## Available libraries

Common Python libraries are pre-installed including:

* **Data Science**: pandas, numpy, scipy, scikit-learn
* **Visualization**: matplotlib, seaborn, plotly
* **Web**: requests, beautifulsoup4
* **Utilities**: json, csv, datetime, os, sys

## Output formats

The tool supports rich output including:

* **Text**: Standard print output and string representations
* **Images**: PNG, JPEG, SVG graphics from matplotlib, plotly, etc.
* **HTML**: Rich HTML content and tables
* **Charts**: Interactive visualizations
* **Markdown**: Formatted text with markdown syntax

## Visual improvements

✨ **New in latest version:**

* **Color-coded output sections** for easy identification
* **Collapsible code view** to focus on results
* **Success indicators** for code that runs without visible output
* **Enhanced error display** with structured error information
* **Rich media rendering** for charts, images, and formatted data

## Best practices

* Use `print()` statements to show progress and intermediate results
* Structure your code with clear steps and explanations
* Handle errors gracefully with try/except blocks
* Break complex operations into smaller, trackable steps
* Import libraries at the beginning of your code

## Troubleshooting

**"Module not found" errors**

* Check if the library is in the available libraries list
* Try importing alternative libraries with similar functionality
* Use built-in Python modules when possible

**"Code execution timeout"**

* Simplify complex operations
* Avoid infinite loops or very long-running processes
* Break large datasets into smaller chunks

**"Memory errors"**

* Reduce dataset size or use sampling
* Clear variables you no longer need with `del variable`
* Use more memory-efficient data structures

**"No output displayed"**

* Use `print()` statements to generate stdout output
* Ensure your final line is an expression (not assignment) to see results
* Check that your code doesn't have syntax errors

## Related tools

* [Postgres SQL](/tools/postgres_sql) - Query databases for data analysis
* [Call API](/tools/call_api) - Fetch data from APIs for processing
* [Scrape URL](/tools/scrape_url) - Get web data for analysis