Agent Script Steps

Beta

Script steps are in beta and appear only for organizations enrolled in the rollout. Contact your Kindo representative if you want them enabled for your organization.

A Script step runs a Python script from one of the agent’s attached skills. No model is involved unless the script asks for one: the step runs the script in the agent’s sandbox, reads the result the script declares, and moves the run on. Use it for work that should happen the same way every time, such as syncing records, transforming a webhook payload, or calling an integration in a loop.

Add a Script Step

1. In the agent builder, select + under Agent Steps, then Add Script step.

2. Pick the Skill. The list shows the skills attached to this agent. If you may attach skills, your own library appears too, and choosing one of those attaches it when you save.

3. Pick the Script: a .py file inside the skill package. The editor previews the file.

4. Set the Timeout and the Agent follow-up toggle, then save.

Setting	What it does
Skill	The attached skill the script comes from. The step runs the skill’s latest version, and the run records the exact content that ran.
Script	A relative .py path inside the skill package. Python is the only supported language.
Tools	Read-only. Scripts run with the tool servers enabled in the agent’s Tools section.
Timeout (seconds)	Wall-clock limit for the script, from 1 to 900 seconds. Defaults to 120.
Agent follow-up	Lets the script hand its result to the agent for a model turn. Off by default. See Agent follow-up.

A skill that a Script step runs cannot be detached from the agent until the step is removed or pointed at another skill. The agent’s organization needs a default chat model even with Agent follow-up off; without one the step fails before the script starts. A Script step never retries: scripts can call tools with side effects, so a step that fails is reported, not run again.

How a Script Runs

• Kindo runs python3 <script path> in a fresh working directory inside the run’s sandbox. The skill’s files are staged at their package-relative paths, so a script can import its sibling modules.
• Only text files in the skill package are staged. Binary files are skipped.
• The kindo_script helper module is importable from any staged path. Only the Python standard library is guaranteed to be installed.
• Network access follows your organization’s Sandbox Network Access setting. See Tool Actions and Permissions.
• A script still running when the timeout expires is killed.
• Files the script writes outside its working directory stay in the run’s sandbox for the rest of the run, so later steps that use the sandbox can read them.

Read the Input

import kindo_script

run_input = kindo_script.read_input()
trigger_data = run_input["triggerData"]
messages = run_input["messages"]

read_input() returns the run’s input as a dictionary, or None when it is unavailable. It holds what the run started with under triggerData and the run’s conversation so far under messages. Ignore keys you do not recognize; new ones may be added.

What the run started with

How the run started	triggerData
Integration Event trigger	The event body Kindo received.
Direct Webhook URL trigger	The request body.
Started by a parent agent, or from a chat	The text the parent forwarded, as a string.
Run manually, on a schedule, or through the API	null. Input values sent through the API are agent inputs, not the trigger data.

payload holds the same value as triggerData and is deprecated. Read triggerData.

The conversation so far

messages lists the run’s messages, oldest first. Each agent step adds a user message describing the step and an assistant message holding its result, so the output of an earlier step is in an assistant message. The first step’s user message begins with the run’s trigger or parent context, then the step’s own text.

Key	Type	Meaning
id	string	The message’s identifier. The Conversations API returns it with the msg_ prefix as the id of the message’s first item; later items of an assistant message add a numbered suffix, and tool calls are keyed by call_id.
index	integer	The message’s position in the conversation, starting at 0.
role	string	"user" or "assistant".
createdAt	string	When the message was recorded, in ISO 8601.
step	object or null	The step the message belongs to, as {"number": 1, "name": "Fetch incidents"}. number is an integer and name is a string or null. The value is null for a message outside any step, such as one sent in the run’s chat after its steps finished, or every message of a conversation that is not an agent run.
forgotten	boolean	true when the agent’s context management has summarized this message out of the model’s view. The message is included in the messages list; the summary that replaced it is not included.
parts	array of objects	What the message holds, in order. See the table below.
truncated	boolean	Present, as true, when parts were dropped to fit the message’s size limit. Parts are dropped from the start of the message, so the ones it produced last are kept.

Each part carries type and the keys for its kind:

Key	Type	Meaning
type	string	"text", "reasoning", "tool-<name>" for a built-in tool, "dynamic-tool" for a tool from a connected tool server, or another kind. A tool part is one that has toolCallId; a part of any other kind carries only its type.
text	string	The text of a text or reasoning part.
toolCallId	string	Tool parts. Identifies the call.
toolName	string	dynamic-tool parts. The tool’s name.
state	string	Tool parts. Where the call got to, such as "output-available" or "output-error".
input	JSON value	Tool parts. What the tool was called with.
output	JSON value	Tool parts. The result, present when the call succeeded. Check its type before indexing into it: the agent’s context management can replace an older call’s output with a placeholder string, and such a part is marked truncated.
errorText	string	Tool parts. The error, present when the call failed.
truncated	boolean	Present, as true, when the part was cut to fit its size limit, or when context management replaced its output. A cut tool part keeps every key except input and output, and only the start of its errorText. A cut text part keeps the start of its text.

A previous LLM step’s answer is the text of the latest assistant message:

assistant_messages = [message for message in messages if message["role"] == "assistant"]
previous_answer = "".join(
    part["text"] for part in assistant_messages[-1]["parts"] if part["type"] == "text"
)

Two size limits keep the input bounded, each approximate by what JSON escaping adds: about 64,000 characters for a message, which also bounds any single part, and about 128,000 for messages as a whole. A part over the message limit is cut as its truncated row describes. A message over its limit first cuts the input and output of its largest tool parts, largest first, marking each one truncated, so every call stays listed with its state; only if that is not enough does it drop parts from its start. A message always keeps its last part, cut to fit if it must be. When the conversation outgrows the limit for messages as a whole, it holds the newest messages that fit and leaves out the older ones. messageCount is how many messages with content the conversation holds, including any left out here, so a messageCount larger than the length of messages means older messages were left out. A message’s position is its index, not its place in messages.

Declare the Result

import kindo_script

kindo_script.declare_result("success", detail="Synced 12 records.")

Call declare_result before the script exits. The last call wins. A script that exits with code 0 without declaring anything is a success.

Argument	Type	Meaning
status	"success" or "error"	The outcome. A declared error completes the step; it is an outcome, not a failure.
detail	string	Free text describing the outcome. Shown in the run and passed to the agent on follow-up.
guidance	string, optional	Steering for the agent’s follow-up turn.
infer	boolean, default False	Ask the agent to follow up on the result. Honored only when Agent follow-up is on.
halt_run	boolean, default False	Cancel the run once this step completes. Later steps never run.

declare_result raises ValueError for a status other than success or error, and TypeError when infer or halt_run is not a boolean.

Detail and guidance limits

Kindo keeps the last 8,192 characters of detail and of guidance. A longer value loses its beginning, and a leading … marks that this happened. Only the truncated text is stored. Write a summary, or a pointer to output stored elsewhere, rather than a full log.

How Kindo reads an exit

What the script did	Status	Detail
Declared a valid result, with any exit code	As declared	As declared
Declared nothing and exited 0	success	stdout
Declared nothing and exited non-zero	error	stderr, then stdout, then “Script failed without output.”
Wrote a result Kindo could not parse	error	stderr, then stdout, then “Script failed without output.”
Was killed at the timeout	error	”Script exceeded its time limit.” followed by the end of stderr or stdout

A timeout is an error whatever the script declared. Undeclared infer and halt_run are False. Write diagnostics to stderr: it is what becomes the detail when a script fails without declaring one, and a Python traceback lands there on its own.

Agent follow-up

With Agent follow-up on, a script that declares infer=True hands its result to the agent. The agent receives the declared status, detail, and guidance, along with every tool call the script made, and runs a model turn with the agent’s tools on your organization’s default chat model. The model’s reply becomes the step’s response. With the toggle off, infer=True is ignored and the step completes with the declared result.

kindo_script.declare_result(
    "error",
    infer=True,
    detail="Upstream returned 404 for 3 of 12 records.",
    guidance="Retry the failed records with the fallback endpoint.",
)

Halting the run

A script that declares halt_run=True completes its step and then cancels the run. Steps after it never run, and the run shows a Run halted marker. Declared together with infer=True, the follow-up turn runs first, then the run halts.

For objective evaluation, a Script step’s verdict follows its status: success is satisfied and error is not satisfied. Because halt_run cancels the run, a run halted by a script reports an aggregate result of partial on the Agents API, with the per-step verdicts intact.

Call Tools from a Script

Scripts use the sandbox tool channel, the same one shell commands use: the kindo_tool module and the kindo-tool CLI, with the same stderr rule, the same ceiling of 100 calls, counted per step run, and the same rule that only tools set to run automatically are callable. Script steps always have the channel and need no separate enrollment in its rollout. Three things differ for Script steps:

• The tool set comes from the tool servers enabled in the agent’s Tools section rather than from the conversation.
• The channel stays open for the whole script run, bounded by the step’s timeout rather than by a single command’s.
• Each call is recorded in the run as its own entry beside the script’s execution, as well as in the audit log.

import kindo_tool

issues = kindo_tool.call_tool("linear_list_issues", {"teamId": "ENG"})

What the Run Records

Each Script step adds two messages to the run’s conversation: a message naming the skill and script, and a response holding the execution. The execution shows the declared fields under RESULT and the free text under DETAIL. Each tool call the script made appears alongside it.

• A run stopped while a script is running kills the script. The response is marked Generation Stopped, and the execution reads “Tool execution was interrupted before completion”.
• Version history captures the skill, script path, timeout, and Agent follow-up setting. Duplicating or restoring an agent keeps its Script steps. Importing an agent definition attaches each pinned skill to the new agent, and is refused when the importer cannot see that skill, which includes every skill from another organization.

Next Steps

• Skills
• Creating and Managing Agents
• Agent Runs API