Skip to main content
Version: 0.9.20

How agents run code

When an AlphaAgent agent needs to compute something — query data, transform it, build a table, or render a chart — it writes and runs real Python and shell code in a sandbox inside your AWS account. This page explains how that sandbox works: per-conversation sessions, the per-environment Lambda that executes code, the S3 workspace each session gets, the caps on output, the difference between a session's lifetime and its durable workspace, and how users are kept isolated from each other.

The model: sandboxed sessions, not a shared shell​

Agents do not run code on the Studio servers. Each conversation that needs code gets its own sandbox session, and code for that session executes inside an isolated AWS Lambda function in your account. The session is the unit of isolation: it is tied to a single conversation and a single user, it has its own working files, and it tears down independently of other sessions.

This means two users — or two conversations of the same user — never share a runtime, a working directory, or in-memory state.

Per-environment Lambdas​

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). Each environment is backed by its own AWS Lambda function in your account, named alphaagent-env-{environment_id}.

  • An agent is assigned an environment; its code runs in that environment's Lambda.
  • The first run in a brand-new environment incurs the usual cold-start latency while the function warms up.
  • Custom environments (your own image) work the same way — they become their own alphaagent-env-{id} function.

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

The S3 workspace​

Every session gets a workspace — a dedicated prefix in the S3 workspaces bucket in your account:

s3://alphaagent-workspaces-{account}-{region}/workspaces/sessions/{session_id}/workspace/

The workspace is where files live. When the agent runs code that downloads data, writes a CSV, or saves a chart, those files are synced to this prefix. The workspace is the durable artifact of a session: files written there persist in your S3 bucket, and the chat's workspace viewer reads them straight from S3.

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 (on the order of one megabyte) 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 (25 MB by default).

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

Session lifetime vs. the persistent 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 service restart or expiry, that session id is gone — the agent simply creates a new session for the next turn.
  • The workspace is persistent. The files in workspaces/sessions/{session_id}/workspace/ remain in your S3 bucket independently of the 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's S3 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 Lambdas and separate S3 prefixes per session, this keeps one user's code, files, and data fully separated from another's.

For workflows, this isolation has a specific consequence: each workflow node runs in its own session and its own workspace, 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​