Python Tools

Registering a Python tool

Open Apps › Tools, press New tool and choose Python code (self-hosted, New Tool, then Python).

The screens, step by step: Tools, in the Guides.

Fields

Writing tool code

The tool code receives parameters via the _args dictionary. Write the output to stdout — everything printed is returned as the tool result.

# _args is automatically available — no need to import or define it
roi = float(_args['revenue'] - _args['cost']) / float(_args['cost']) * 100
print(f"ROI: {roi:.2f}%")
print(f"Net profit: ${_args['revenue'] - _args['cost']:,.2f}")

Pre-installed packages

The sandbox image includes:

pandas, pandas_ta, numpy, scipy, scikit-learn, matplotlib, seaborn,
requests, httpx, beautifulsoup4, lxml, openpyxl, xlsxwriter, pyyaml,
tabulate, jinja2, jsonschema, pillow, sympy

Example: Financial calculator

# Parameters: principal (number), rate (number), years (number)
principal = float(_args['principal'])
rate = float(_args['rate']) / 100
years = int(_args['years'])

total = principal * (1 + rate) ** years
interest = total - principal

print(f"Principal: ${principal:,.2f}")
print(f"Annual rate: {_args['rate']}%")
print(f"Duration: {years} years")
print(f"Final amount: ${total:,.2f}")
print(f"Total interest earned: ${interest:,.2f}")

Example: Data processing

import pandas as pd
import json

# Read data from vault (mounted at /data)
with open('/data/sales/data.csv') as f:
    df = pd.read_csv(f)

# Process
top_products = df.groupby('product')['revenue'].sum().nlargest(5)
result = top_products.to_dict()
print(json.dumps(result, indent=2))

Example: Text processing with regex

import re

text = _args['text']
pattern = _args.get('pattern', r'\b\d{3}-\d{3}-\d{4}\b')

matches = re.findall(pattern, text)
print(f"Found {len(matches)} matches:")
for m in matches:
    print(f"  {m}")

Accessing the vault

The vault is mounted read-only at /data inside the sandbox. Read vault files directly:

with open('/data/config/thresholds.json') as f:
    import json
    thresholds = json.load(f)

To write to the vault from a Python tool, use the vault_write tool in a subsequent agent step.

What the tool says it does

A Python tool's answers start Not set: Your tool policy treats it as a tool that doesn't say what it does. Press Say what it does to give them:

• What it does: Reads only, Changes something or Deletes something;
• Safe to repeat: calling it twice changes nothing the first call didn't (a workflow won't send a call again after a timeout unless it is);
• Reaches outside this workspace: it talks to a system this workspace doesn't control.

Clear sets them back to Not set. How each answer decides what the tool policy does is on that page.

Testing

Self-hosted, click Test Run in the tool's editor to run the code with sample _args values (Test Arguments (JSON)). Output is shown inline with exit code, stdout, and stderr.

Sandbox constraints

• Network is available — requests and httpx can call external URLs
• 512 MB RAM, 1 CPU, 30s timeout
• Read-only filesystem (except /tmp and /root tmpfs)
• Vault available at /data (read-only)

For wrapping an HTTP endpoint you do not need Python for, HTTP tools are simpler — you describe the request instead of writing the call.