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.
[Screenshot: 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:
| Setting | Range | Default |
|---|---|---|
| Memory | 1,769–10,240 MB | 2,048 MB |
| vCPU | Computed automatically from memory | — |
| Workspace storage | 512–10,240 MB | 512 MB |
| Execution timeout | Fixed at 15 minutes | 15 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.
Related pages
- Agents — attach an environment to an agent in the Agent Map.
- Code interpreter and datasets — what agents do inside an environment.
- How agents run code — the technical detail of sandboxed execution.