Skip to main content

Execution environments

An execution environment is the sandboxed Linux container an agent runs Python and shell commands in ("sandboxed Linux containers where agents run Python and shell tools at inference time"). For Studio users whose agents run code (a Specialist agent cannot be activated without one) and the engineer who builds a custom image when the prebuilt one lacks a package or tool. You create it from an image, Studio provisions it in your deployment's AWS account, and you attach it to agents in their Configure dialog.

Before you start: environments run as functions in your deployment's account and count against its AWS Lambda quotas; a new account starts with reduced quotas, so request an increase (AWS Lambda quotas) if provisioning fails on one. Environments carry no variables or secrets: credentials reach the agent's code through its data connectors. A custom image needs Docker, the AWS CLI signed in to the account, and access to the deployment's environment repository in Amazon Elastic Container Registry (ECR). Each user can hold 256 environments; Create Environment is disabled at the cap.

Prebuilt or custom​

Prebuilt: two images ship with every Studio, chosen under Prebuilt Environment with a description under the picker. Choose one unless you need something neither has.

  • AlphaAgent Python: "Python 3.12 with numpy, pandas, pyarrow, scipy, scikit-learn, statsmodels, matplotlib, seaborn, plotly, yfinance, sqlalchemy, psycopg2 (PostgreSQL), pymysql (MySQL), snowflake-connector-python (Snowflake), httpx, requests, pytz, boto3, and fastmcp (MCP client)." plus the document toolkit below.
  • AlphaAgent Python and Java: "Everything in AlphaAgent Python, plus a Java 21 runtime and JPype so Python code can call Java libraries. A sample JAR is at /opt/alphaagent/java/alphaagent-sample.jar." Choose it when agents call Java libraries from Python, for example through JPype. Your own JARs are not in it: to add them, build a custom image on top of it (Build a custom environment image). It has the same limits as AlphaAgent Python, including the 900 second execution limit.

A Studio upgraded to a release that includes the Python and Java image receives it with the upgrade, after Organisations 1.1.2 or later has mirrored it. Until then the picker offers it but creating the environment fails with a "not found in the repository" message.

Custom (push to ECR): an image you build and push to the deployment's environment repository. Studio refuses anything else, with the reason verbatim: outside the repository ("Custom images must be in this deployment's environment repository (<repository>). Push your image there and pick it from the list."); not Linux amd64 with Python ("Linux-based (Python) images only."; Windows, PowerShell-based and non-Python images are not supported; suggested bases python:3.11-slim, python:3.12-bookworm, ubuntu:22.04 with Python, continuumio/miniconda3); a multi-platform or attestation manifest ("Build with --platform linux/amd64 --provenance=false --sbom=false."); over 4.0 GB compressed as ECR reports it ("environments accept images up to 4.0 GB"). Studio pins the image by digest at provision (Image digest (pinned at provision)), so a moved tag changes nothing.

Steps: create an environment​

  1. Open Agent Management in the dock, then Environments in the sidebar. The list shows Name, Environment ID, Image Source (prebuilt or custom), Status, Resources (for example "2048 MB · 1.16 vCPU") and Updated At; search by ID or name.
  2. Click Create Environment. Under Basic Information enter a Name (80 characters) and optional Description (500).
  3. Under Container Image choose the Image Source: Prebuilt offers a Prebuilt Environment picker with "AlphaAgent Python" and "AlphaAgent Python and Java"; Custom (push to ECR) lists the repository's images in Image URI as repository:tag (size MB) to choose from; only when the list is empty or cannot be read does the field take a typed tag or @sha256: digest from that repository (View build & push instructions opens this page; an empty repository reads "Push your image to ECR, then refresh the page to see it here.").
  4. Under Resource Configuration ("vCPU is derived from memory (1 vCPU per 1769 MB). Execution timeout is 1 to 900 seconds (default 15 minutes) and is enforced per run."): Memory (MB) 1,769 to 3,008, default 2,048, clamped when you leave the field; vCPU read-only; Execution timeout (seconds) default 900; Max Workspace Storage (MB) 512 to 3,008, default 512.
  1. Click Create. The row shows Creating…; the list refreshes every 30 seconds while anything provisions.
  2. Wait for Active, then open the agent, choose Configure, and set the environment (Agents: configure and activate).

Build and push a custom image​

To build a custom image, follow Build a custom environment image; Studio refuses images outside the repository, non-Linux/amd64, multi-platform manifests, or over 4.0 GB.

Provisioning and status​

StatusMeaning
Creating…Provisioning the function from the image and running the handler contract probe; up to 15 minutes.
ActiveThe probe passed; agents can use it.
Needs attentionProvisioning or the probe failed; the banner names the reason. Fix it and click Provision, which "also retries a failed one".
Needs provisioningNot yet provisioned (a Library copy pulled without Provision now); click Provision.
InactiveSwitched off; agents cannot use it.

The probe runs the image once and asks it to describe its capabilities; the detail page's Container Image section shows Handler contract probe "Passed" or "Failed", the toolkit version and the time, and "The image's toolkit is behind the current handler" when a rebuild is due. Banner reasons: "The image does not implement the AlphaAgent handler contract: <error>." (check awslambdaric and boto3); "Contract probe timed out" and "Provisioning did not finish within 15 minutes" (both end "Provision to retry"); "Handler delivery update failed: <reason>" (usually a permission in your account). In a governed deployment the banner adds "Anyone assigned to this governed deployment can provision it; the environment is shared by everyone here." The page refreshes every 30 seconds while provisioning.

Studio delivers the execution handler at run time rather than relying on the copy in the image: every Studio upgrade points every function at the release's handler and re-probes it, so each environment shows Creating… and returns to Active on its own, prebuilt and custom alike, and a custom image is not rebuilt for a handler fix. Which copy answered is recorded on the environment (The entry point and the delivered handler). An agent that runs code before its environment is Active stops with an error naming the state; there is no fallback environment.

Timeouts, working directory and storage​

  • Execution timeout is per run of code. A quarter of the remaining time, at least 5 and at most 60 seconds, is reserved for saving results; at the budget the code is stopped and the agent reports "(the code was stopped after <budget> s; <reserve> s of the limit is reserved for saving results)" with what was printed. Long work is not lost: the checkpoint helper aa_env.py lets an analysis write its progress to the workspace and stop, and the agent resumes from it in a fresh run, on any image.
  • Every run gets a fresh working directory under /tmp: the project directories it needs are mirrored in from the workspace, changed files are uploaded back, and the directory is removed. Nothing left on local disk is seen by a later run, another agent or another user, and each agent has its own home directory. Agents do not install packages at run time: what the code can import is what the environment's image carries, so a missing package means a custom image.
  • Max Workspace Storage is that scratch disk: you enter 512 to 3,008 MB and Studio provisions at least 2,048 MB whatever you enter, because the toolkit and a real workspace need it.
  • Outbound network from the sandbox: TCP 443, through the deployment's egress (AlphaAgent's NAT gateway or your firewall). On a private deployment the sandbox also reaches the internal service ranges an administrator approved, on port 443 and on the approved ports (for example 5432 for PostgreSQL), and nothing else on your network (Data connectors).
  • Your own certificate authorities: when an administrator adds them to the deployment, code in every environment trusts them for HTTPS, PostgreSQL, MySQL, Node and curl, in addition to the public ones. A custom image needs the openssl command line for PostgreSQL, Node and curl to trust an issuing CA added without its root (Build a custom environment image).

Environment Map, delete and share​

  • Once Active, the detail page shows the Environment Map: "Every agent currently wired to this environment. Disassociate all before deleting; re-associate to bring them back online." Disassociate All removes it from every dependent agent's active configuration; Re-associate All restores them. While an active workflow version runs one of those agents, Disassociate All is refused and nothing changes: deactivate that workflow in Workflow Versions, or activate a version that does not use the agent, then try again. Empty: "No agents are currently using this environment."
  • Delete reads "Checking..." while Studio checks active configurations (also enforced on the server: "<environment> is used by 3 agents: A, B, C. Move them to another environment first."). If agents use it, Cannot Delete Environment lists the Affected Agents; otherwise Delete Environment asks you to type the name and removes the function too. The deployment's default environment cannot be deleted ("This is the deployment's default environment and cannot be deleted."); if Studio cannot read the configurations it refuses ("Couldn't check which agents use this environment").
  • Share opens Share to a Resource Store with no version picker; the copy carries the image reference and the resource budget, nothing else. The recipient's Download environment dialog offers Provision now ("build and start the runtime image immediately after the copy lands. Leave unchecked to provision later from the Environments screen."); an unprovisioned copy shows Needs provisioning (Libraries and sharing).

Notes​

  • "Could not load ECR images. Check your AWS credentials and region configuration.": type a tag from the repository instead. "Choose or enter an image." or "That is not a valid tag or digest for <repository>.": enter a bare tag, repository:tag or repository@sha256:<digest>.
  • On an environment's page the Handler contract probe time is your browser's local time, while Created and Updated under Metadata are UTC clock times.
  • Create refused with a repository, size or manifest message (shown verbatim under the form): rebuild with the flags on Build a custom environment image. Needs attention after Create: read the banner, fix it, Provision.
  • The image build fails installing awslambdaric with a source build that asks for cmake: pin awslambdaric==4.0.4 (Build a custom environment image).
  • A document comes back without its PDF, or a diagram as source: the image lacks a toolkit tool (the agent says which); install the toolkit and rebuild. "Error loading environment" or "Environment not found": go Back and reopen; it may have been deleted.