Skip to main content
Version: 0.9.20

Execution environments

An execution environment is the sandboxed Linux compute where an agent 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 (see Code interpreter and datasets), it does so inside an execution environment: 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.

Create execution environment form

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 and shows copyable instructions for building and pushing one. 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. The push instructions spell out the exact build flags, because a default build can produce a manifest the runtime rejects.

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

Resource configuration​

You set the compute resources for the environment:

SettingRangeDefault
Memory1,769–10,240 MB2,048 MB
vCPUComputed automatically from memory—
Workspace storage512–10,240 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.

[Screenshot: Environment resource configuration]

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.