sim/apps/docs/content/docs/en/blocks/function.mdx

---
title: Function
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Image } from '@/components/ui/image'
import { FAQ } from '@/components/ui/faq'

The Function block executes custom JavaScript, TypeScript, or Python code in your workflows. Transform data, perform calculations, or implement custom logic.

<div className="flex justify-center">
  <Image
    src="/static/blocks/function.png"
    alt="Function Block with Code Editor"
    width={500}
    height={400}
    className="my-6"
  />
</div>

## Outputs

- **`<function.result>`**: The value returned from your function
- **`<function.stdout>`**: Console.log() output from your code

## Example Use Cases

**Data Processing Pipeline** - Transform API response into structured data
```
API (Fetch) → Function (Process & Validate) → Function (Calculate Metrics) → Response
```

**Business Logic Implementation** - Calculate loyalty scores and tiers
```
Agent (Get History) → Function (Calculate Score) → Function (Determine Tier) → Condition (Route)
```

**Data Validation and Sanitization** - Validate and clean user input
```
Input → Function (Validate & Sanitize) → API (Save to Database)
```

### Example: Loyalty Score Calculator

<Tabs items={['JavaScript', 'Python']}>
  <Tab value="JavaScript">
```javascript title="loyalty-calculator.js"
// Process customer data and calculate loyalty score
const { purchaseHistory, accountAge, supportTickets } = <agent>;

// Calculate metrics
const totalSpent = purchaseHistory.reduce((sum, purchase) => sum + purchase.amount, 0);
const purchaseFrequency = purchaseHistory.length / (accountAge / 365);
const ticketRatio = supportTickets.resolved / supportTickets.total;

// Calculate loyalty score (0-100)
const spendScore = Math.min(totalSpent / 1000 * 30, 30);
const frequencyScore = Math.min(purchaseFrequency * 20, 40);
const supportScore = ticketRatio * 30;

const loyaltyScore = Math.round(spendScore + frequencyScore + supportScore);

return {
  customer: <agent.name>,
  loyaltyScore,
  loyaltyTier: loyaltyScore >= 80 ? "Platinum" : loyaltyScore >= 60 ? "Gold" : "Silver",
  metrics: { spendScore, frequencyScore, supportScore }
};
```
  </Tab>
  <Tab value="Python">
```python title="loyalty-calculator.py"
import json

# Reference outputs from other blocks using angle bracket syntax
data = json.loads('<agent>')
purchase_history = data["purchaseHistory"]
account_age = data["accountAge"]
support_tickets = data["supportTickets"]

# Calculate metrics
total_spent = sum(p["amount"] for p in purchase_history)
purchase_frequency = len(purchase_history) / (account_age / 365)
ticket_ratio = support_tickets["resolved"] / support_tickets["total"]

# Calculate loyalty score (0-100)
spend_score = min(total_spent / 1000 * 30, 30)
frequency_score = min(purchase_frequency * 20, 40)
support_score = ticket_ratio * 30

loyalty_score = round(spend_score + frequency_score + support_score)

tier = "Platinum" if loyalty_score >= 80 else "Gold" if loyalty_score >= 60 else "Silver"

result = {
    "customer": data["name"],
    "loyaltyScore": loyalty_score,
    "loyaltyTier": tier,
    "metrics": {
        "spendScore": spend_score,
        "frequencyScore": frequency_score,
        "supportScore": support_score
    }
}
print(json.dumps(result))
```
  </Tab>
</Tabs>

## Python Support

The Function block supports Python as an alternative to JavaScript. Python code runs in a secure [E2B](https://e2b.dev) cloud sandbox.

<div className="flex justify-center">
  <Image
    src="/static/blocks/function-python.png"
    alt="Function block with Python selected"
    width={400}
    height={500}
    className="my-6"
  />
</div>

### Enabling Python

Select **Python** from the language dropdown in the Function block. Python execution requires E2B to be enabled on your Sim instance.

<Callout type="warn">
If you don't see Python as an option in the language dropdown, E2B is not enabled. This only applies to self-hosted instances — E2B is enabled by default on sim.ai.
</Callout>

<Callout type="info">
Python code always runs in the E2B sandbox, even for simple scripts without imports. This ensures a secure, isolated execution environment.
</Callout>

### Returning Results

In Python, print your result as JSON to stdout. The Function block captures stdout and makes it available via `<function.result>`:

```python title="example.py"
import json

data = {"status": "processed", "count": 42}
print(json.dumps(data))
```

### Available Libraries

The E2B sandbox includes the Python standard library (`json`, `re`, `datetime`, `math`, `os`, `collections`, etc.) and common packages like `matplotlib` for visualization. Charts generated with matplotlib are captured as images automatically.

<Callout type="info">
  The exact set of pre-installed packages depends on the E2B sandbox configuration. If a package you need isn't available, consider calling an external API from your code instead.
</Callout>

### Matplotlib Charts

When your Python code generates matplotlib figures, they are automatically captured and returned as base64-encoded PNG images in the output:

```python title="chart.py"
import matplotlib.pyplot as plt
import json

data = json.loads('<api.data>')

plt.figure(figsize=(10, 6))
plt.bar(data["labels"], data["values"])
plt.title("Monthly Revenue")
plt.xlabel("Month")
plt.ylabel("Revenue ($)")
plt.savefig("chart.png")
plt.show()
```

{/* TODO: Screenshot of Python code execution output in the logs panel */}

### JavaScript vs. Python

| | JavaScript | Python |
|--|-----------|--------|
| **Execution** | Local VM (fast) or E2B sandbox (with imports) | Always E2B sandbox |
| **Returning results** | `return { ... }` | `print(json.dumps({ ... }))` |
| **HTTP requests** | `fetch()` built-in | `requests` or `httpx` |
| **Best for** | Quick transforms, JSON manipulation | Data science, charting, complex math |

## Best Practices

- **Keep functions focused**: Write functions that do one thing well to improve maintainability and debugging
- **Handle errors gracefully**: Use try/catch blocks to handle potential errors and provide meaningful error messages
- **Test edge cases**: Ensure your code handles unusual inputs, null values, and boundary conditions correctly
- **Optimize for performance**: Be mindful of computational complexity and memory usage for large datasets
- **Use console.log() for debugging**: Leverage stdout output to debug and monitor function execution

<FAQ items={[
  { question: "What languages does the Function block support?", answer: "The Function block supports JavaScript and Python. JavaScript is the default. Python support requires the E2B feature to be enabled, as Python code always runs in a secure E2B sandbox environment." },
  { question: "When does code run locally vs. in a sandbox?", answer: "JavaScript code without external imports runs in a local isolated VM for fast execution. JavaScript code that uses import or require statements requires E2B and runs in a secure sandbox. Python code always runs in the E2B sandbox regardless of whether it has imports." },
  { question: "How do I reference outputs from other blocks inside my code?", answer: "Use the angle bracket syntax directly in your code, like <agent.content> or <api.data>. Do not wrap these references in quotes — the system replaces them with actual values before execution. For environment variables, use double curly braces: {{API_KEY}}." },
  { question: "What does the Function block return?", answer: "The Function block has two outputs: result (the return value of your code, accessed via <function.result>) and stdout (anything logged with console.log(), accessed via <function.stdout>). Make sure your code includes a return statement if you need to pass data to downstream blocks." },
  { question: "Can I make HTTP requests from a Function block?", answer: "Yes. The fetch() API is available in the JavaScript execution environment. You can use async/await with fetch to call external APIs. However, you cannot use libraries like axios or request — only the built-in fetch is supported. Your code runs inside an async context automatically, so you can use await directly." },
  { question: "Is there a timeout for Function block execution?", answer: "Yes. Function blocks have a configurable execution timeout. If your code exceeds the timeout, the execution is terminated and the block reports an error. Keep this in mind when making external API calls or processing large datasets." },
]} />