Skip to main content
Version: 1.0.11

Execution environments

An execution environment is the sandboxed Linux compute where an agent's coder runs Python and shell commands at runtime — for example, to analyze data returned by a connector. This page covers choosing a prebuilt or custom image, configuring resources, and managing the agents that depend on an environment.

What an environment is​

When an agent needs to run code, it delegates the work to a coder that runs inside the execution environment (see Code interpreter and datasets): an isolated Linux container with Python available. You define environments once and then attach them to agents in the Agent Map. Every Specialist agent needs an environment before it can be activated.

Environments are created in your own AWS account, and code runs there — your data and computations stay inside your boundary. For the technical detail, see How agents run code.

Creating an environment​

From the Environments list, click Create and provide a name and description. Then choose an image and configure resources.

Image source: prebuilt vs custom​

  • Prebuilt — a ready-to-use Python image maintained for AlphaAgent, with common data libraries already installed. Choose this if you don't need special packages.
  • Custom — your own container image, which you build and push to your container image registry (Amazon ECR) in your account. Choose this when your agents need specific libraries or system tools.

When you pick Custom, Studio lists the images available in your registry so you can select the one your agents should use. Build and push that image by following the steps below. A few requirements to be aware of:

  • The image must be Linux on the amd64 architecture — Python-based Linux images only. Windows or PowerShell images are not supported.
  • The image must be built as a single-platform image in a compatible container format, because a default build can produce a manifest the runtime rejects. The build flags below handle this.

If the image list fails to load, check that your AWS credentials and region are configured correctly.

Building and pushing a custom image​

1. Build your image. Your Dockerfile must install the packages AlphaAgent needs to run code in your environment:

pip install awslambdaric boto3

It must also include the AlphaAgent execution handler. Download it and place it in the same folder as your Dockerfile:

Download handler.py

COPY handler.py /opt/handler.py

2. Push your custom image to your account's ECR registry. Replace <region> with your AWS region and <ecr-registry> with your registry host (for example 123456789012.dkr.ecr.<region>.amazonaws.com):

# 1. Authenticate with ECR
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <ecr-registry>

# 2. Build and push a Lambda-compatible image (single-platform Linux/amd64, Docker v2 schema 2 —
#    provenance/SBOM off, since a default docker build adds an OCI manifest list Lambda rejects).
docker buildx build \
  --platform linux/amd64 \
  --provenance=false --sbom=false \
  -t <ecr-registry>/alphaagent-envs:my-agent-env-1.0 \
  --push .

Once the image is pushed, return to Studio, choose Custom as the image source, and select your image from the Image URI list.

Resource configuration​

You set the compute resources for the environment:

SettingRangeDefault
Memory1,769–3,008 MB2,048 MB
vCPUComputed automatically from memory—
Workspace storage512–3,008 MB512 MB
Execution timeoutFixed at 15 minutes15 minutes

vCPU is derived from the memory you choose (more memory means more CPU) and is shown for reference — you don't set it directly. The execution timeout is fixed: a single code execution can run for up to 15 minutes.

New AWS accounts have reduced Lambda quotas

Execution environments run on AWS Lambda in your account, so they are subject to your account's Lambda quotas. New AWS accounts start with reduced concurrency and per-function memory quotas, which AWS raises automatically as your usage grows. On a brand-new account you may not be able to provision the largest environments or run many environments at once until those quotas increase. If you hit a concurrency or memory limit, request a quota increase (or wait for AWS to raise it automatically) — see the AWS Lambda quotas documentation.

When an environment is still provisioning​

Creating an environment provisions real infrastructure in your AWS account, and that takes a little time. The environment is not usable the instant you click Create — it has to reach an active state first.

If an agent tries to run code before its environment is ready, it won't fail silently: the agent reports that it can't reach its infrastructure or can't execute/write code, and the run stops with an infrastructure-related error rather than a normal result. This is expected while the environment is still coming up.

What to do:

  • Wait for the environment to finish provisioning and show as active before activating or running agents that depend on it.
  • If the errors persist well after creation, confirm the environment actually reached the active state, and that your AWS credentials and region are configured correctly (a custom image that can't be pulled will also keep an environment from becoming usable).
  • Only attach and activate Specialist agents once their environment is ready.

Viewing an environment and its dependents​

Open an environment to see its details and the Environment Map — the agents whose active configuration uses this environment.

From here you can manage dependents in bulk:

  • Disassociate All removes the environment reference from every dependent agent at once (the agents are taken out of service until re-wired).
  • Re-associate All restores those references after a change.

These bulk actions are useful when you are reconfiguring or replacing an environment that many agents share.

Deleting an environment​

Deleting checks for impact first. If any agents or swarms reference the environment, Studio shows a guard listing them and does not delete — you detach or re-point those dependents first. If nothing depends on it, a confirmation lets you delete.

There is no separate "update" screen for environments; to change one substantially, create a new environment and re-point the agents that should use it.