Skip to main content
When you turn a chat session into a reusable agent, any scripts the session wrote can be bundled with the agent and reused on every future run. Bundled scripts make runs reproducible, eliminate cross-run drift, and give you a debuggable paper trail for what your agent actually does. This page walks through the full lifecycle end-to-end with a real example — a stock performance analyzer — and shows how to use follow-up messages to improve the script over time.

​
Why bundled scripts matter

Without bundled scripts, every run asks the language model to re-read your agent’s text procedure and re-write the code. That leads to drift:
  • “Blue” becomes navy one run, cornflower the next
  • Edge-case handling quietly changes each time
  • A function accepting three inputs might silently take four next run
  • Metric definitions (annual return, volume, high/low) shift between runs
Bundling locks the deterministic heavy lifting into a fixed file. The language model still handles narrative parts — summaries, event bullets, web-search context — but the number-crunching code stays identical forever.
Bundled scripts are reference files in the Files tab. They sit alongside any manually uploaded templates, CSVs, or config files and are mounted into the sandbox on every run.

​
The full lifecycle

1

Create — the first session writes a script to disk

The agent writes a .py file (via the Write tool or a cat > bash command) and runs it. This is the working version, the one you see producing the output you like.
Chat turn with a 'Writing meta_stock_plot.py' artifact chip and a python3 command executing it
Scripts piped straight to stdin (python3 << 'EOF' … EOF) evaporate after running — there’s nothing on disk to bundle. Always write to a file first, then execute. The super agent follows this rule by default.
2

Persist — clicking 'Turn into reusable agent' bundles the script

When you ask “make this reusable” or click Turn into reusable agent, the platform runs a short probe that scans /tmp/*.py, /home/user/workspaces/*/*.py, and any files the agent wrote via Write. Everything found is uploaded to cloud storage under the new agent’s identity, then registered as an attached file.
Persist turn showing a cp command into app-staging, then a node marker emission, followed by the app creation confirmation
The bundled file now shows up in the Files panel on the agent’s detail page:
Agent detail page for Stock Performance Analyzer with the right-side Files panel listing stock_plot.py
3

Run — the agent reads a manifest and executes the bundled file directly

On every subsequent run, the agent reads /home/user/agent/app-files.json — a manifest that maps the logical file name (meta_stock_plot.py) to its mounted path (/home/user/workspaces/apps/<appId>/meta_stock_plot.py). It then runs that path verbatim, passing your form inputs as environment variables.
Chat showing 'cat /home/user/agent/app-files.json' followed by 'TICKER=AAPL YEAR=2024 python3 /home/user/workspaces/apps/.../meta_stock_plot.py'
No re-derivation, no drift. The script runs exactly the same way every time; only the inputs change.
4

Improve — follow-up messages replace the bundled file

Need to change the chart colors, add a new metric, or fix a bug? Send a follow-up message to the agent describing the change. The agent rewrites the script, stages the new version, and the platform replaces the old file in place. All future runs automatically use the improved version.Examples of follow-ups that update the script:
  • “Change the color palette to three shades of blue”
  • “Add a 200-day moving average overlay”
  • “Output the metrics as CSV instead of JSON”
  • “Fix the high/low annotations to show dates on the x-axis”
Follow-ups that don’t touch the script (just the surrounding prose):
  • “Rename this agent to ‘Portfolio Tracker’”
  • “Reword the description”
  • “Add a second form field for a comparison ticker”
The agent figures out which category your message falls into. Prose-only changes bump the version and skip the staging step entirely.

​
Parameterize via environment variables

Bundled scripts should read runtime inputs from environment variables, not hardcoded literals. That way one bundled file handles every form submission. 
import os

TICKER = os.environ.get("TICKER", "META")
YEAR = int(os.environ.get("YEAR", "2024"))
MA_PERIOD = int(os.environ.get("MA_PERIOD", "50"))

# ... rest of script uses TICKER / YEAR / MA_PERIOD
The agent runtime reads your agent’s form inputs and passes them to the bundled script as env vars named after each field’s id. A form field ticker becomes $TICKER; ma_period becomes $MA_PERIOD.
Split a complex workflow into multiple small scripts, one per concern: fetch.py downloads data, analyze.py computes metrics, plot.py renders the chart. Each can be bundled and invoked separately. You can attach up to 50 reference files per agent.

​
Managing bundled files

​
Inspect what’s attached

Open the agent’s detail page and look at the Files panel on the right. Every reference file currently bundled is listed there; click a file to preview its contents. This is useful when you’re debugging unexpected behavior or want to verify a follow-up actually updated the script.

​
Upload manually

Beyond auto-bundled scripts, you can click Upload on the Files panel to add any file up to 10 MB — templates, reference datasets, style guides, SQL fixtures. Uploaded files mount into the sandbox at the same predictable paths as auto-bundled ones and appear in the same manifest.

​
Removing a file

Click the trash icon next to any file in the Files panel to delete it permanently. The agent will stop mounting it on subsequent runs.

​
Troubleshooting

Two common causes:
  1. The original script was piped via stdin. Nothing made it to disk, so nothing was staged. Re-create the agent from a fresh session where the script is written to a file first.
  2. The bundled script has hardcoded values instead of env vars. If your form says ticker = AAPL but the bundled script always runs META, the agent will rewrite the script every time to get the right input. Parameterize via env vars and the bundled file becomes reusable.
Check the agent’s Files panel — if there’s no .py file listed, the first issue applies. If there is one, preview it and look for hardcoded literals.
Follow-up updates only affect future runs. Past session records are immutable — they preserve exactly what happened at the time, including the script version in effect then. Run the agent again to see the new version in action.
The agent only uses the bundled file when the runtime procedure instructs it to. When an agent is created through a follow-up rather than a fresh session, the platform may not automatically wire “run the bundled script” into the procedure. Ask the agent to “run the bundled script from app-files.json” in a follow-up and it will update the procedure to reference the staged file.
Not currently. Direct editing is on the roadmap; for now, all updates go through follow-up messages. The upside is that every change is traced in a chat history, so you can see why each revision happened.

Agents

Full reference for the Agents product, including the Files tab, Config tab, and session history.

Agent Runtime Environment

How sandboxes mount reference files, pass form inputs as env vars, and isolate runs from each other.