--- title: "AgentCore Code Interpreter — the sandbox where agent-generated code runs without melting your account" date: 2026-06-01 service: "Amazon Bedrock AgentCore" component: "Code Interpreter" tags: [agentcore, code-interpreter, sandbox, python, javascript, typescript, sessions, executeCode, executeCommand, writeFiles, network-mode, s3, quotas, boto3] source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html verified_on: 2026-06-01 url: https://vanemmerik.ai/aws-ai/2026-06-01.html --- # AWS Bedrock & AgentCore · Tip of the Day · 2026-06-01 ## AgentCore Code Interpreter — the sandbox where agent-generated code runs without melting your account **AgentCore Code Interpreter** is the managed sandbox where an agent can write code, run it, and inspect the result without you having to host a Jupyter kernel, harden a container, or trust the model not to delete your S3 bucket. Yesterday's Observability tip covered the dashboard you didn't have to build. Today's question is the one underneath it: **where does the code actually run?** $ pip install bedrock-agentcore boto3 $ aws bedrock-agentcore start-code-interpreter-session \ --code-interpreter-id aws.codeinterpreter.v1 \ --name demo --session-timeout-seconds 900 ≈ 9 min read · Bedrock AgentCore · Code Interpreter --- ## 01 · Why Code Interpreter exists Most useful agentic work eventually wants to run a small program. Parse a CSV, plot a chart, validate a JSON schema, solve an integer-program, re-encode a video. The model can write the code; the question is where that code executes. The two failure modes both end the same way: - **Run it in your application process** and you've just executed arbitrary, model-authored code inside a runtime that has your credentials, your network, and your filesystem. - **Build your own sandbox** and you're managing a container fleet, a kernel pool, a package mirror, network egress rules, an S3 staging pattern, and CloudTrail integration — all so the agent can run `pandas`. **AgentCore Code Interpreter** is AWS's managed answer. From [Execute code and analyze data using Amazon Bedrock AgentCore Code Interpreter](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html): > "The AgentCore Code Interpreter runs in a containerized environment > within Amazon Bedrock AgentCore, ensuring that code execution remains > isolated and secure." It supports **Python, JavaScript, and TypeScript**, ships with hundreds of pre-installed libraries, exposes a tight session API, and is logged to CloudTrail. You don't manage the container. > **The shift.** You stop hosting an interpreter. AgentCore gives you a > per-session sandbox with 2 vCPU / 8 GB / 10 GB of disk and a clear > contract for getting code in and results out. --- ## 02 · Two modes — managed and custom There are two paths into the Code Interpreter, and the choice is purely about how much control you need over execution role and network egress. | Mode | How you reference it | When to pick it | | --- | --- | --- | | **Managed (system)** | `codeInterpreterIdentifier="aws.codeinterpreter.v1"` | Default. No setup, no IAM role to provision, no network policy to wire. Use when the agent only needs to crunch numbers or build charts. | | **Custom** | `CreateCodeInterpreter` → returns a `codeInterpreterId` you pass to `start_code_interpreter_session` | Use when you need an execution role that can read/write a specific S3 bucket, or when you want explicit `SANDBOX` vs `PUBLIC` network mode. | Custom Code Interpreters are created on the **`bedrock-agentcore-control`** endpoint; sessions and invocations land on the **`bedrock-agentcore`** data-plane endpoint. The two-client pattern is the same one Memory and Gateway use. A minimal custom interpreter, straight from the [creation doc](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-create.html): cp = boto3.client("bedrock-agentcore-control", region_name="us-east-1") resp = cp.create_code_interpreter( name="my-data-sandbox", description="S3-reading sandbox for the analyst agent", executionRoleArn="arn:aws:iam::111122223333:role/CodeInterpreterExecRole", networkConfiguration={"networkMode": "SANDBOX"}, ) code_interpreter_id = resp["codeInterpreterId"] The execution role's trust policy must let `bedrock-agentcore.amazonaws.com` assume it; the calling identity needs the `bedrock-agentcore:CreateCodeInterpreter` / `InvokeCodeInterpreter` / `StartCodeInterpreterSession` actions scoped to `arn:aws:bedrock-agentcore:::code-interpreter/*`. --- ## 03 · The session model Code Interpreter is **session-based**. You create the interpreter (or use the managed one) once; every invocation runs inside a session you explicitly start and stop. Each session keeps its own state — Python globals, files on disk, environment variables — so successive `executeCode` calls within the same session can build on each other. The state you care about lives in three fields on `start_code_interpreter_session`: - **`codeInterpreterIdentifier`** — `aws.codeinterpreter.v1` for managed, or the ID you got back from `CreateCodeInterpreter`. - **`name`** — a human label that shows up in CloudWatch and CloudTrail. - **`sessionTimeoutSeconds`** — the idle timeout. Default 900 (15 min); the [quota table](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/bedrock-agentcore-limits.html) caps the *synchronous* invocation timeout at 15 minutes, but asynchronous commands started via `startCommandExecution` can run for **up to 8 hours**. The full lifecycle: client = boto3.client("bedrock-agentcore", region_name="us-east-1") s = client.start_code_interpreter_session( codeInterpreterIdentifier="aws.codeinterpreter.v1", name="analyst-session-1", sessionTimeoutSeconds=1800, ) session_id = s["sessionId"] # ... call invoke_code_interpreter as many times as you like ... client.stop_code_interpreter_session( codeInterpreterIdentifier="aws.codeinterpreter.v1", sessionId=session_id, ) When the session is stopped — explicitly, or by hitting the timeout — the sandbox is destroyed. Anything not exported to S3 or returned in a response is gone. The high-level SDK (`bedrock_agentcore.tools.code_interpreter_client.CodeInterpreter`) wraps this in a `code_session` context manager, which is the path the docs steer you toward. --- ## 04 · The tool surface — one verb, nine names Every Code Interpreter call goes through one boto3 method, `invoke_code_interpreter`, with a `name` field that selects the tool. The [API reference examples](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-api-reference-examples.html) list nine: | Tool name | Arguments | What it does | | --- | --- | --- | | `executeCode` | `language`, `code` | Run a Python/JS/TS snippet. Returns a stream of `result` events. | | `executeCommand` | `command` | Run a synchronous shell command (`ls -l`, `pip install …`). Bounded by the 15-minute sync ceiling. | | `startCommandExecution` | `command` | Fire-and-forget for long-running shell work. Returns a `taskId`. | | `getTask` | `taskId` | Poll the status of a long-running task. | | `stopTask` | `taskId` | Cancel a long-running task. | | `writeFiles` | `content: [{path, text}, …]` | Drop files into the sandbox before executing code that reads them. | | `readFiles` | `paths: […]` | Read sandbox files back into the calling process. | | `listFiles` | `directoryPath` | Walk the sandbox's filesystem. | | `removeFiles` | `paths: […]` | Clean up temporary files between steps. | Calls return a stream of events with a `result` field; the SDK helper flattens them, but with `boto3` you iterate `response["stream"]` and pull `event["result"]["content"]` for text and image outputs. --- ## 05 · Batteries included The sandbox image ships with **hundreds of pre-installed libraries** so the agent rarely has to `pip install` (and you rarely have to widen the network policy to let it). The [pre-installed libraries doc](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-preinstalled-libraries.html) is exhaustive; the headline shape: - **Data and analytics**: `pandas`, `polars`, `numpy`, `scipy`, `statsmodels`, `sympy`, `pyarrow`, `duckdb`, `SQLAlchemy`. - **Visualisation**: `matplotlib`, `seaborn`, `plotly`, `bokeh`. - **ML and AI**: `scikit-learn`, `torch`, `torchvision`, `xgboost`, `spacy`, `nltk`, the `mcp` reference SDK, even the `openai` client. - **Documents**: `openpyxl`, `xlrd`, `XlsxWriter`, `python-docx`, `PyPDF2`, `pdfplumber`, `reportlab`. - **Media**: `pillow`, `opencv-python`, `moviepy`, `ffmpeg-python`, `pydub`. - **AWS**: `boto3` is in the image. So is `awscli` (via terminal commands), so `aws s3 cp …` works directly when the execution role allows it. If you do need to install something, `pip install ` works in `PUBLIC` network mode; in `SANDBOX` mode it fails — that's the trade. --- ## 06 · Network modes and S3 The single most-asked question after "does it run pandas" is "can it read my S3 bucket?". Two pieces decide that: 1. **Network mode** on the Code Interpreter resource. From the [creation doc](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-create.html): - `SANDBOX` — limited external network access. No public internet, no `pip install`. AWS API calls go via the assumed execution role. - `PUBLIC` — full internet egress. The model can fetch a webpage, `pip install` a library, or call any HTTPS endpoint. 2. **Execution role** — what AWS resources the sandbox can touch when it makes API calls. The role's trust policy must include `Service: bedrock-agentcore.amazonaws.com`. Scope its permissions tight: usually `s3:GetObject` and `s3:PutObject` on one prefix. With that role in place, the agent can `aws s3 cp` files in and out of S3 directly inside the sandbox — which is the right pattern for anything over a few hundred megabytes. The inline file upload tool (`writeFiles`) caps at the **100 MB max payload size**; objects in S3 can go up to **5 GB** per file according to the [Code Interpreter overview](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html). The pattern from the [S3 integration doc](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-s3-integration.html): # Inside an executeCommand call, with an execution role attached: aws s3 cp s3://my-bucket/input/data.csv . python analyse.py aws s3 cp report.html s3://my-bucket/output/ --- ## 07 · Limits worth knowing From the [AgentCore service quotas](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/bedrock-agentcore-limits.html) table for Code Interpreter: - **Hardware per session: 2 vCPU / 8 GB RAM** — not adjustable. The ceiling for what a single session can crunch. - **Disk: 10 GB per session** — not adjustable. Sessions handling multi-GB datasets should stream from S3 rather than landing files. - **Synchronous request timeout: 15 minutes** — not adjustable. Anything longer must go through `startCommandExecution`. - **Asynchronous command max duration: 8 hours** — not adjustable. The same ceiling as Runtime sessions. - **Max payload size: 100 MB** — not adjustable. `writeFiles` and inline uploads share this budget; use S3 for anything bigger. - **Concurrent active sessions: 1,000 per account** — adjustable via Service Quotas. - **Code Interpreter tool configurations: 1,000 per account** — adjustable. Build one per network/IAM profile, not one per agent. - **`InvokeCodeInterpreter` rate: 30 TPS per account** — adjustable. Same shape as Runtime invocations. Two gotchas that aren't in the quota table: - **Session state evaporates on stop.** Anything not written to S3 or returned over the wire is gone. Plan for that — don't rely on `executeCode` calls saving files between sessions. - **`SANDBOX` mode is the default surprise.** A custom Code Interpreter created without a `networkConfiguration` block defaults to limited egress. If the agent's first `pip install` fails with a network error, this is almost always why. --- ## 08 · Try it in five minutes With AWS credentials and the right IAM permissions in place: pip install bedrock-agentcore boto3 python - <<'PY' from bedrock_agentcore.tools.code_interpreter_client import CodeInterpreter import json code_client = CodeInterpreter("us-east-1") code_client.start() try: resp = code_client.invoke("executeCode", { "language": "python", "code": ( "import pandas as pd\n" "df = pd.DataFrame({'x': range(10)})\n" "df['y'] = df['x'] ** 2\n" "print(df.tail())\n" ), }) for event in resp["stream"]: print(json.dumps(event["result"], indent=2)) finally: code_client.stop() PY That's the whole loop: start, invoke, stop. The managed `aws.codeinterpreter.v1` interpreter handles the rest. Add a `writeFiles` call before the `executeCode` to upload data, or swap to `executeCommand` and `aws s3 cp` to pull a file from S3 first. Tomorrow we'll look at **AgentCore Browser** — the sibling built-in tool that lets the agent drive a real Chromium session the same way Code Interpreter lets it run a Python kernel. --- **Verified against the official AWS docs on 2026-06-01.** Sources: , , , , , , , , , , . If the docs change, this lesson is a snapshot of that day — check the sources for current behaviour. --- > **This page — research, writing, verification, and deployment — was built by > Claude Cowork.** No human touched the prose, the layout, or the upload > pipeline. The lesson was generated this morning, cross-checked against the > official AWS docs by an independent verification pass, and published > to Cloudflare R2 on a schedule. > > A daily experiment by Monty van Emmerik · — AWS Bedrock & AgentCore · Tip of the Day · No. 007 · vanemmerik.ai