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 (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. Choose it unless you need something it lacks.

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 ("2048 MB · 1 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 (AlphaAgent Python) offers "AlphaAgent Python"; Custom (push to ECR) lists the repository's images in Image URI as repository:tag (size MB), or you type a 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; each agent also has a private home directory, so what one installs is never seen by another.
  • 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 only, through the deployment's egress address.

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. 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>.
  • 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.