Python sandbox

The Python sandbox turns any Python function into a tool that runs in an isolated environment, on its own or inside an agent.

Asset path: aixplain/python-sandbox/aixplain · Marketplace card

Try it

import inspect
from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

def calculate_discount(price: float, discount_percent: float):
    discount = price * discount_percent / 100
    return {"discount_amount": round(discount, 2), "final_price": round(price - discount, 2)}

discount_tool = aix.Tool(
    name="Discount calculator",
    description="Calculates the final price after a percentage discount.",
    integration="aixplain/python-sandbox/aixplain",
    config={"code": inspect.getsource(calculate_discount), "function_name": "calculate_discount"},
).save()

agent = aix.Agent(
    name="Pricing assistant",
    description="Calculates prices with discounts.",
    instructions="Use the discount calculator for every price. Show the discount and the final price.",
    tools=[discount_tool],
).save()

result = agent.run("What's the final price for a $100 item with 20% off?")
print(result.data.output)

Show output

Configuration

Field	Parameter	Default	Notes
Code	code	required	The function source as a string. Use inspect.getsource() or read a .py file.
Function name	function_name	inferred	The function to expose. Required when code defines more than one function.

If you omit integration and pass code= instead of config, the SDK uses the Python sandbox and infers function_name.

Actions

The tool has one action, named after the function (here calculate_discount). Its inputs are the function's parameters.

Run the tool directly

Pass the arguments as a dict whose keys match the parameter names. With a single action, action= is optional. result.data holds the run status and the return value in data; dicts and lists arrive as their string form.

result = discount_tool.run(action="calculate_discount", data={"price": 100, "discount_percent": 20})
print(result.data)

Show output

Write the function

• function_name must match a top-level function in code. Helper functions in the same code are fine.
• Return JSON-serializable values: dicts, lists, strings and numbers.
• Use int (0 or 1) instead of bool parameters. A bool argument reaches Python as JSON true and fails with NameError.

Top-level imports, default values and multi-line signatures work. Type hints are optional, but they help the agent call the tool with the right types.

To load the code from a file instead of a live function, read it as a string:

with open("my_function.py") as f:
    code = f.read()

Return errors as data

Return an error field instead of raising. The agent sees the message and can explain it or retry with other inputs.

def get_price(sku: str):
    prices = {"A-100": 49.0, "B-200": 19.5}
    if sku not in prices:
        return {"price": None, "error": f"Unknown SKU {sku}"}
    return {"price": prices[sku], "error": None}

price_tool = aix.Tool(
    name="Price lookup",
    description="Returns the price of a product SKU, or an error for unknown SKUs.",
    integration="aixplain/python-sandbox/aixplain",
    config={"code": inspect.getsource(get_price), "function_name": "get_price"},
).save()

result = price_tool.run(data={"sku": "Z-999"})
print(result.data)

Show output

Troubleshooting

Symptom	Cause	Fix
Function '...' not found in code	function_name does not match a function in code.	Print the code string and check the name.
status is "Failure" and stderr shows ModuleNotFoundError	The package is not installed in the sandbox runtime.	Use the standard library or a common package such as numpy.
A numeric argument of 0 arrives as None	The sandbox passes zero values as None.	Treat None as zero inside the function, for example b = b or 0.
NameError: name 'true' is not defined	The function takes a bool parameter.	Take an int and convert it inside the function.
inspect.getsource() fails	The function was typed in an interactive REPL.	Define it in a file or a notebook cell, or pass the source as a string.

Clean up

agent.delete()
discount_tool.delete()
price_tool.delete()

Next steps

• Tools: see every kind of tool an agent can call.
• Remote MCP: connect tools that already run on an MCP server.
• Agents: configure the agent that calls the tool.
• API reference: tool: every parameter and method.