The Code Interpreter

LLMs are notoriously bad at things computers are great at: summing a column of a CSV, parsing a 40-page PDF, fitting a regression, rendering a chart. Ask a model to add up 10,000 numbers and it will confidently produce a number that is plausible and wrong. The fix is not a better prompt — it is to let the agent write code and run it, then read the actual output.

AgentCore Code Interpreter is the managed sandbox for exactly that. It is a secure, isolated code-execution environment so agents can run code for data analysis, computation, and file processing instead of guessing. It is one of AgentCore's two built-in Tools (the other being the Browser tool). It is framework-agnostic — your agent can be Strands, LangGraph, plain Python, whatever — and you reach it through the same SDK regardless.

There is a default/system interpreter you can use immediately, identified as aws.codeinterpreter.v1, with no resource to create. When you need a different posture — say PUBLIC network egress, or a specific execution role — you create a custom interpreter that bundles its own network mode and execution role.

The languages are Python, JavaScript, and TypeScript. You pass the language in each executeCode call, and you can optionally pin a runtime:

Crucially, the Python environment ships with a deep stack of data libraries already installed — so the common analytics case needs zero setup.

The Python sandbox comes batteries-included. As of writing (verify the live page — the exact list changes), the pre-installed selection covers most analytics and ML work:

• Dataframes & numerics: pandas, polars, numpy, scipy, duckdb, SQLAlchemy
• Plotting: matplotlib, seaborn, plotly
• ML: scikit-learn, torch, xgboost, spacy, nltk
• Files & docs: openpyxl, pypdf/pdfplumber, python-docx, python-pptx, pillow, opencv-python
• HTTP & web: requests, httpx, beautifulsoup4, fastapi
• Agent/cloud: boto3, openai, mcp, pydantic

The Node environment includes axios, lodash, uuid, zod, and cheerio.

When you need something that is not pre-installed, add it at runtime two ways:

# 1) The SDK convenience helper (preferred)
ci.install_packages(["yfinance", "statsmodels"])

# 2) Or shell out via executeCommand
ci.invoke("executeCommand", {"command": "pip install yfinance statsmodels"})

Because the session keeps state across calls (next section), a package you install in one call is importable in the next.

Everything runs inside a session, and the lifecycle is explicit:

The key property is that state persists across calls within a session. Variables, imported modules, installed packages, and files you wrote all survive from one execute_code to the next — the session is a live REPL-like process, not a fresh container per call.

Isolation is strong and per-session: each session runs in its own Firecracker microVM with isolated CPU, memory, and filesystem. When the session ends, memory is sanitized and the microVM is destroyed. Access is governed by IAM, and activity is logged to CloudTrail/CloudWatch.

The limits below are [VOLATILE] — teach the shape, verify the live quotas page before you rely on a number:

The 100 MB-inline vs 5 GB-via-S3 split is the one to internalize early: small payloads go inline through the SDK; anything large goes through S3 and the execution role's S3 permissions.

The ergonomic entry point is the code_session context manager, which starts a session against the default aws.codeinterpreter.v1 interpreter and auto-stops it when the block exits:

from bedrock_agentcore.tools.code_interpreter_client import code_session

with code_session("us-west-2") as ci:
    ci.install_packages(["pandas", "matplotlib"])
    ci.upload_file(
        path="sales.csv",
        content="date,revenue\n2024-01-01,1000",
        description="CSV",
    )
    result = ci.execute_code(
        "import pandas as pd; print(pd.read_csv('sales.csv')['revenue'].sum())"
    )
    for event in result.get("stream", []):
        for content in event.get("result", {}).get("content", []):
            if content.get("type") == "text":
                print(content["text"])
    out = ci.download_file("sales.csv")
# auto-stopped on exit

The convenience helpers — install_packages, upload_file, execute_code, download_file — wrap the lower-level tool actions for the common cases.

When you need full control (custom interpreter, explicit lifecycle), use the explicit class form and put stop() in a finally:

from bedrock_agentcore.tools.code_interpreter_client import CodeInterpreter

ci = CodeInterpreter("us-west-2")
ci.start()
try:
    ci.invoke("executeCode", {"language": "python", "code": "print(2 ** 10)"})
finally:
    ci.stop()  # always

Control plane vs data plane — this distinction matters for IAM and for which SDK client you reach for:

The code_session/CodeInterpreter SDK classes wrap the data plane against aws.codeinterpreter.v1. You only touch the control plane when you create or manage a custom interpreter.

Under the helpers, you invoke the interpreter with a name (the action) and a payload. The full set:

A direct invoke looks like this:

result = ci.invoke("executeCode", {
    "language": "python",
    "code": "total = sum(range(101)); print(total)",
    "clearContext": False,
})

clearContext controls whether you keep the persistent state. clearContext=False (the default behavior you want most of the time) reuses the running interpreter — your earlier variables and imports are still there. clearContext=True gives you a fresh interpreter context, as if nothing had run before. Confusing these two is a classic gotcha: set it True and wonder why your dataframe 'disappeared.'

The async pattern is how you exceed the 15-minute synchronous window — up to 8 hours. A long batch job (startCommandExecution) returns a taskId; you then poll getTask until it completes, and can stopTask to cancel:

start = ci.invoke("startCommandExecution", {"command": "python long_etl.py"})
task_id = start["taskId"]
# ... poll ...
status = ci.invoke("getTask", {"taskId": task_id})

Parsing results. Every invoke returns a stream: a list of events, each with result.content, a list of typed blocks. Text output lives in {"type": "text", "text": ...}:

for event in result.get("stream", []):
    for content in event.get("result", {}).get("content", []):
        if content.get("type") == "text":
            print(content["text"])

If you bypass the SDK, the data-plane invoke is a SigV4-signed HTTPS POST. The interpreter ID is in the path and the session ID is a header:

POST https://bedrock-agentcore.<region>.amazonaws.com/code-interpreters/aws.codeinterpreter.v1/tools/invoke
x-amzn-code-interpreter-session-id: <session-id>
(Authorization: SigV4 required)

Network mode is the lever that decides what the sandbox can reach. It is set in networkConfiguration.networkMode:

• SANDBOX — isolated; no general public internet egress. S3 is reachable via the execution role. This is the default posture for untrusted, agent-generated code.
• PUBLIC — public internet egress allowed. Use only when the code legitimately needs to call external APIs or fetch from the web.

A VPC mode is not documented for Code Interpreter (UNVERIFIED). Do not assume parity with Runtime's VPC support — if you need VPC-scoped egress, treat it as unconfirmed and verify before designing around it.

Now the part most teams get wrong. SANDBOX is not an airtight network jail. It is [VOLATILE], but as documented, SANDBOX mode still permits DNS (A/AAAA) resolution. Teach it as 'no general internet egress, S3-reachable' — not as a perfect isolation boundary.

This is not theoretical. External security research has demonstrated real egress paths out of SANDBOX:

• BeyondTrust — DNS-based command-and-control out of SANDBOX (the DNS-resolution gap weaponized as a covert channel).
• Sonrai — credential exfiltration via the instance metadata service (169.254.169.254) plus a 'global S3' covert channel.
• Palo Alto Unit 42 — a network-isolation bypass.

The honest framing: Code Interpreter is strong on cross-tenant isolation (one customer cannot reach another's microVM), but it is not a perfect data-egress boundary. Verify the current remediation state of this research against the live characteristics page before you make a trust decision.

There are two IAM surfaces: what the caller (your agent/app) may do, and what the sandbox's execution role may touch.

Caller actions operate on resource code-interpreter/*:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:CreateCodeInterpreter",
      "bedrock-agentcore:StartCodeInterpreterSession",
      "bedrock-agentcore:InvokeCodeInterpreter",
      "bedrock-agentcore:StopCodeInterpreterSession",
      "bedrock-agentcore:DeleteCodeInterpreter",
      "bedrock-agentcore:ListCodeInterpreters",
      "bedrock-agentcore:GetCodeInterpreter",
      "bedrock-agentcore:GetCodeInterpreterSession",
      "bedrock-agentcore:ListCodeInterpreterSessions"
    ],
    "Resource": "arn:aws:bedrock-agentcore:us-west-2:<account>:code-interpreter/*"
  }]
}

The execution role is what the code inside the sandbox assumes. Its trust policy uses the bedrock-agentcore.amazonaws.com principal with sts:AssumeRole, and should carry confused-deputy guards — aws:SourceAccount and aws:SourceArn conditions:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {"aws:SourceAccount": "<account>"},
      "ArnLike": {"aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:<account>:*"}
    }
  }]
}

For S3 file movement, scope it tightly to the buckets you actually use and add an s3:ResourceAccount condition rather than granting blanket S3:

{
  "Effect": "Allow",
  "Action": ["s3:GetObject", "s3:PutObject"],
  "Resource": "arn:aws:s3:::my-ci-data-bucket/*",
  "Condition": {"StringEquals": {"s3:ResourceAccount": "<account>"}}
}

The single most important hardening step: do not ship the Starter Toolkit's over-broad default execution role. As documented in the security research, that default grants full S3 read plus Secrets Manager — exactly the credentials an exfiltration technique wants. Combine a tight execution role with no sensitive secrets in the role, and monitoring (CloudTrail/CloudWatch) so a misbehaving session is visible.