Python tools

Status: Current | Last reviewed: 2026-08-12

A Python tool runs code you write inside a sandbox. Use it for logic that doesn't fit an API call — data transforms, custom calculations, glue between systems — without standing up a separate service.

Configuration

Field Required Notes
Python source Yes Your code. It runs in an isolated sandbox, not on the host.
Requirements No Pinned wheels, one per line (e.g. httpx==0.27.0, pydantic>=2.5). The sandbox installs them before running your code.
Parameters Yes The inputs the LLM passes in. You author these directly — name, type, description, required — and they become the tool's schema.

You can test the tool from the editor with a sample input payload (e.g. {"customer_id": "123"}) and see the result before saving.

Note: The tool type is python_sandboxed. An older python_script type exists on some tenants but can no longer be created — it's kept only so existing references keep working.

Inline Python tools on an agent

In an agent's Prompt tab, the Tools dropdown includes Create Inline Python Tool. Inline tools use the same Python editor, parameter builder, and test experience as shared Python tools, including testing before the agent stage is saved. They are saved inside that agent stage only, do not appear in the shared Tools list, and cannot be selected by other agents unless you recreate them there.

The Run button in the inline editor's Test panel works before the tool is saved to the shared Tools list. It runs the current source in the sandbox in mock mode, so you can check the tool logic without live integration credentials.

Inline Python tools work the same way on a workflow Tool node — open the node, use its tool dropdown, and pick Create Inline Python Tool.

Reading a failed test run

A successful run shows ok in _N_ms plus the returned value under Result. A failure shows the error message, and below it whichever of these the sandbox produced:

Block What it holds
stdout / stderr Anything your code printed before it stopped.
traceback Where it failed. For an error in your own code this is the Python traceback with the offending line.

The traceback is worth reading even when the message looks final. Some messages — sandbox exited rc=255 with no envelope is the common one — mean the sandbox itself could not start, which is a problem with the environment rather than with your code; the traceback is the only place that difference shows. If you see one of those, the tool source is probably fine and it's worth reporting to whoever runs your environment.

Reading and updating variables

Python tools receive the tool arguments and a runtime context:

async def run(args, context):
    account_id = args["account_id"]
    context.vars["last_account_id"] = account_id
    context.vars["lookup_status"] = "complete"
    return {"account_id": account_id, "status": "complete"}

Use args for the parameters the LLM or workflow node supplied. Use context.vars to read session or flow variables. Any values you write to context.vars are merged back after the tool finishes: in workflow Tool nodes they update the flow variables for later nodes, and in agent inline tools they update the conversation's session variables for later prompt rendering and tool bindings.

See also