Python Code

Python Code lets you write a few lines of Python code to do exactly what you need with your data: calculate amounts, clean and reorganize information, combine fields or apply your own business rules. The component receives the data from the previous step, runs your code in isolation and delivers whatever your code returns.

It can also work as a tool for an agent: the agent calls it when needed and passes the values it has decided on.

When to use it

Calculate totals, discounts or taxes from the data of an order.
Reorganize the information a service returns so it fits the next step.
Apply your own rules, such as classifying customers by purchase volume.
Give an agent a specific operation that must always be done the same way.

Configuration

Field	What it does
Input Data	The data your code works with. Connect it to the output of the previous component. Accepts messages, data and files.
Python Code	The code that runs. The input data is available in `data` and the result is whatever you pass to `return`. If you don’t write `return`, the component delivers nothing.

What your code has at hand

data: the input data. A record arrives as a set of fields, for example data["amount"]; a list arrives as a list of records.
env: the variables of the environment assigned to the flow, for example env.get("CURRENCY"). If the flow has no environment, it is empty.
components: what other components in the flow have returned in this run, when the component works as a step of the flow.
args: the values the agent sends when the component works as a tool.
tools and models: the tools and models you connect to the component (see the advanced options). Use return tools or return models to see which ones are available and how to call them.
print(): whatever you write with print() appears in the run log, but it is not part of the result.

A simple example that calculates the total of an order:

total = data["quantity"] * data["price"]
return {"order": data["order"], "total": round(total, 2)}

Advanced options

Field	What it does
Packages	Additional modules your code needs, one per line. The first time they are used it may take a few extra seconds.
Volume Directory	Name of a folder in your storage where the code can save files that are kept between runs. In the code, the path to that folder is in `volume`. Leave it empty if you don’t need to save files.
Python Version	Version of the language your code runs with. Default: `3.13`.
Enable Tools Input	Adds the Tools input so you can connect tools and call them from the code with `tools["name"](...)`. Off by default.
Enable Models Input	Adds the Model input so you can connect AI models and call them from the code with `models["name"]("your question")`. Off by default.

Use as a tool

These fields apply when you connect the Tool output to an agent.

Field	What it does
Tool Name	Name the agent sees for the tool. Default: `py_tool`.
Tool Description	Tells the agent what the tool is for and when to use it.
Tool Input Schema	The values the agent must send when calling the tool. They reach your code in `args`.

Output

Processed Data: what your code returns. A set of fields becomes a record, a list becomes a list of records (each set of fields as a record, each other value as a record with it in the text field), and a text or a number becomes a record with that value in the text field.
Tool: the component as a tool for an agent. When you connect one of the two outputs, the other is hidden.

To apply the code to each item of a list separately, use Batch Mode.

Example

You receive orders from your store with quantity and unit price, and your billing sheet needs the total including tax. You connect the orders to Python Code and write code that multiplies quantity by price, adds 21 % and returns the order number with its total. The Processed Data output goes straight to the component that writes to the sheet.

Good practices

Always finish with return. To see how your data arrives, start with return data and run the component.
Keep keys and service addresses in the flow’s environment and read them with env, instead of writing them in the code.
If another component already does the task, such as filtering or joining data, use that component: the flow will be easier to understand.