Skip to main content
Version: 1.0.11

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 write code inline. Instead the orchestrating agent writes a compact analysis spec, and a dedicated coder fulfils it by running real Python in a sandbox inside your AWS account. This page explains how that works: the spec-driven coder and where it lives, the per-conversation sessions, the per-environment Lambda that executes the code, the S3 conversation filesystem each run gets, the caps on output, the difference between a session's lifetime and its durable files, and how users are kept isolated from each other.

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

Agents do not run code on the Studio servers, and the orchestrating agent does not author code directly. When it needs to compute, the agent calls a single tool — run_analysis — with a compact specification of what it wants. That spec is handed to a coder: a long-lived loop built on the Claude Agent SDK that lives in the code-interpreter ECS Fargate service in your account. The coder plans and writes the code to satisfy the spec, then runs it.

The coder does not have a shell. Native shell execution is disabled — all code runs through a single tool, run_in_env, which executes it inside the agent's execution environment (an isolated AWS Lambda in your account; see below). Alongside it the coder has a small, fixed set of tools: read_document (read a fetched or uploaded document), connector_fetch (pull connector data), register_artifact (register a dataset, chart, or report), and emit_citation (attach a source to the answer). Everything else it might want to do, it does as code inside run_in_env.

Each conversation that needs code gets its own sandbox session, and the code for that session executes inside its own isolated Lambda invocation. 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; the code the coder runs via run_in_env executes 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 conversation filesystem​

Each conversation gets a durable filesystem in the S3 workspaces bucket in your account, organised under a per-conversation prefix:

s3://alphaagent-workspaces-{account}-{region}/conversations/{conversation_id}/
    spec/        # the analysis specs the orchestrator wrote
    docs/        # documents fetched or uploaded, cached point-in-time
    datasets/    # registered datasets (durable, versioned)
    charts/      # chart artifacts
    reports/     # generated reports
    work/        # scratch checkpoints

(A workflow run, which has no conversation, is scoped by its execution id instead.)

This is where files live. When the coder runs code that downloads data, writes a CSV, or saves a chart, those files are synced here. It is durable: files written here persist in your S3 bucket independently of any session, and the chat's workspace viewer reads them straight from S3. Because the filesystem is keyed by the conversation rather than a single session, work the coder did in an earlier turn is still there in a later one.

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 conversation filesystem. The pattern that lets the coder work with large results without dumping them into chat — dataset registration via register_artifact — is covered in Datasets and data flow.

Session lifetime vs. the persistent filesystem​

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 conversation filesystem is persistent. The files under conversations/{conversation_id}/ remain in your S3 bucket 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'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 Lambda invocations and separate per-conversation S3 prefixes, 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 filesystem prefix, 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​