Python Script (PYTHON_SCRIPT)

Runs your own Python script in a closed-off container and passes its JSON result on. Use it as a step in the flow, or connect it to an Agent as a tool. It is the answer for anything that no other module does.

Category: Utilities · Deployed: yes · Tool-capable: yes

Ports

Port Kind Purpose

Input (in_input)

Input

As a step: the result of the previous module. The script reads it as pipeline_input

Result (out_result)

Output

The script’s result as JSON

Tool (tool_mcp)

Tool

As a tool: connect to the Tools port of an Agent

Use either the Tool port or the Input and Result ports. If the module is connected to an agent as a tool, it does not run as a step.

Properties

Field Required Meaning

Script (script)

Yes

The Python code. pipeline_input is ready to use in it. The script must print its result as JSON. Without extra packages, only Python’s built-in libraries are there

Requirements (requirements)

No

Extra Python packages, best with a fixed version, for example requests==2.32.3. Empty → nothing is installed and the script runs without internet. With packages → they are installed at the start of every run, and the script gets internet access

Timeout (s) (timeoutSeconds)

No

The most time for installing the packages and running the script together, 1–300 seconds. Empty → 30. Higher → long installs and slow scripts can finish. Lower → a stuck script is stopped sooner. A value above 300 is refused when the pipeline is sent to the agent

Description (description)

No, but needed as a tool

Tells the agent’s model what the script does and when to use it. Without it, the agent only sees a general text

What the script gets and must return

Input. pipeline_input is a dictionary (a JSON object).

  • As a step: only a JSON object from the previous module is passed in. If the previous result is plain text, a list or another JSON value, pipeline_input is empty ({}). Put a Template or an Agent with a JSON answer in front, if you need to pass data.

  • As a tool: the model sends an object called input. It becomes pipeline_input. If the model sends nothing, pipeline_input is empty.

Result. The script prints its result as JSON, and nothing else. For example:

import json
print(json.dumps({"total": pipeline_input.get("a", 0) + pipeline_input.get("b", 0)}))

  • The whole output must be one JSON value. Extra print lines for debugging break it. If the output is not valid JSON, the result is {"raw": "<the text>"} instead.

  • The output is limited to 1 MB. Longer output is cut. A cut JSON text is no longer valid, so the result is then the cut text in raw, together with "truncated": true.

When the script fails

A script that fails does not stop the run. It passes on a result like this:

Field Meaning

success

false

error

A short reason — the last line of the error output, "Script timed out after …s", or the exit code

stderr

The error output

exitCode

The exit code, when there is one

truncated

Only when the output was cut

The next module receives this as its input. Put a Validator after the script, if a failure must lead to another path. As a tool, the agent receives the same result and can react to it.

How it runs

Each run starts a fresh, closed-off container. Nothing stays between runs, except the downloaded packages.

  • With Docker, the agent server starts a short-lived container. It has 256 MB of memory, 1 CPU, no rights of an administrator and a limit on the number of processes. Without Requirements, it has no network and a read-only file system. The downloaded packages are kept in a volume, so later runs start faster.

  • With Kubernetes, the agent server starts a Job with a ConfigMap that holds the script and its input. Both are deleted after the run. The memory and CPU limits come from the agent server’s settings. Their defaults are 256 Mi of memory and 1 CPU. The agent server itself does not block the network there. Whether the packages are kept between runs depends on the cluster setup.

  • The Python version and image are set by the agent server. By default, it is Python 3.12.

Use cases

  • Exact calculations: maths, dates or statistics that a model gets subtly wrong.

  • Reshape data between two modules that use different formats.

  • Own checks, though Validator with the type Script is the better fit for a plain Pass or Fail decision.

  • A tool for an agent: a precise calculator, instead of letting the model calculate in its text.

Notes

  • Only the built-in libraries are there unless you list packages. Using requests without listing it fails at run time.

  • The timeout counts installing and running together. A long package list can use up the whole time before your code starts. Leave Requirements empty if you do not need packages. Then nothing is installed.

  • Packages need internet. They are installed again at the start of every run, so each run needs the package server. With a long list, expect a slow start.

  • The script cannot reach other containers or the internet without Requirements (with Docker). If it must call a web service, list at least one package. This also turns on the network for the whole run.

  • A model decides the input when the module is a tool. Check the values in the script, and do not trust them.

  • The pipeline cannot be deployed without a script. The message is "Script is required".

  • A failed run is passed on as normal JSON, so in a long pipeline an error is easy to miss. Check the result with a Validator where it matters.