Skip to main content

How agents run code

When an AlphaAgent agent needs to compute something — query data, transform it, build a table, or render a chart — it does not make up an answer and it does not run code on the Studio servers. Instead the orchestrating agent describes what it needs as a compact analysis spec, and a dedicated coder fulfils it by writing and running real Python in an isolated sandbox inside your own AWS account. This page explains that model at a working level: how code actually executes, where the files it produces live, why results are grounded in real computation rather than fabricated, how output is bounded, and how one user's work is kept fully separate from another's.

Real code, not fabricated data​

The most important guarantee is that numbers, tables, and charts come from code that actually ran against your data — not from the model inventing plausible-looking values. When the agent needs to compute, it hands the coder a specification, and the coder writes Python to satisfy it and executes it in the sandbox. The result the agent reports back is the result the code produced.

This is why the coder runs in your account rather than guessing: a figure in an answer traces to an execution you can inspect, over data that came from your connectors, uploads, or datasets. If the code can't produce a result, the agent tells you — it does not substitute a made-up one.

The model: a spec-driven coder, not a shared shell​

Agents do not author code inline. When the orchestrating agent needs to compute, it calls a single tool with a compact specification of what it wants, and a coder — a long-lived reasoning loop running in your account — plans and writes the code to satisfy that spec, then runs it.

The coder does not have a free-form shell. All code runs through one execution path into the agent's execution environment (an isolated sandbox in your account), and the coder has only a small, fixed set of supporting capabilities alongside it: reading a fetched or uploaded document, pulling connector data, registering a result as a dataset or chart, and attaching a source citation to the answer. Anything else it needs to do, it does as code inside the sandbox.

Each conversation that needs code gets its own sandbox session, and its code executes in its own isolated invocation. The session is the unit of isolation: it is tied to a single conversation and a single user, has its own working files, and tears down independently of other sessions. Two users — or two conversations of the same user — never share a runtime, a working directory, or in-memory state.

Execution environments​

Code runs in execution environments. An execution environment is a container image with a chosen set of preinstalled libraries — the built-in image ships Python with common data libraries, and you can supply your own image for specialised needs.

  • An agent is assigned an environment; the code the coder runs executes in that environment.
  • The first run in a brand-new environment incurs the usual cold-start latency while it warms up.
  • Custom environments work the same way as the built-in one.
  • For long-running tasks, work is automatically sharded across execution environments rather than forced to finish in a single place. This happens for you and improves resilience, so big jobs — running for up to 24 hours — complete reliably.

You manage environments from Studio; the end-user view is in Execution environments.

The conversation workspace​

Each conversation gets a durable workspace stored in your own account, organised per conversation. It holds the specs the orchestrator wrote, documents fetched or uploaded (cached point-in-time), registered datasets, chart artifacts, generated reports, and scratch checkpoints.

This is where files live. When the coder runs code that downloads data, writes a CSV, or saves a chart, those files are synced into the conversation workspace. It is durable: the files persist in your account independently of any session, and the chat's workspace viewer reads them straight from there. Because the workspace is keyed by the conversation rather than a single session, work the coder did in an earlier turn is still available in a later one. (A workflow run, which has no conversation, is scoped by its own run identifier instead.)

Output caps​

Code execution is bounded so a runaway script cannot flood the conversation or the model:

  • Returned output is capped. Standard output and error from a single execution are truncated before they are returned.
  • Stored history is capped again. When execution history is persisted for the workspace UI, output is truncated a second time, so the stored view can be shorter than what the agent originally saw.
  • Workspace downloads are bounded. When you export or zip a workspace, there is a per-file size ceiling.

These caps protect the conversation and the model's context window while leaving the full data files intact in the conversation workspace. The pattern that lets the coder work with large results without dumping them into chat — dataset registration — is covered in Datasets and data flow.

Session lifetime vs. the durable workspace​

These two lifetimes are deliberately different:

  • The session is ephemeral. A session tracks live execution state and expires after a period of inactivity. After a restart or expiry, that session is gone — the agent simply creates a new one for the next turn.
  • The workspace is persistent. The files for a conversation remain in your account independently of any session's lifetime. Losing the session does not lose the files.

So "the session ended" never means "your data was deleted." It means the live sandbox context was released; the produced files stay in your account until you remove them.

Cross-user isolation​

Sandbox sessions enforce ownership. Every session belongs to the user who started it, and any request against a session is checked against that owner. A request from a different user is answered as if the session does not exist — the platform does not distinguish "not yours" from "not found," so session identifiers cannot be used to probe for other users' work. Combined with separate execution invocations and separate per-conversation workspaces, this keeps one user's code, files, and data fully separated from another's.

For workflows, this has a specific consequence: each workflow node runs in its own session and its own workspace scope, so nodes do not automatically share files. Moving data from one node to the next is an explicit step, described in Datasets and data flow.

Where to go next​