• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. AI Agents
  3. Code Interpreter

AgentCore Code Interpreter for agents

Amazon Bedrock AgentCore Code Interpreter runs code that an agent writes (Python, JavaScript or TypeScript) in an isolated sandbox session, with shell commands and files, so the agent can calculate, analyze data and produce charts. Every agent can use the AWS-managed code interpreter without configuration; define a custom one under ai.codeInterpreters when the code needs internet access or resources in a VPC.

This Python agent uses the AWS-managed code interpreter through the Strands Agents tool. No code interpreter configuration is needed in serverless.yml:

# serverless.yml
ai:
  agents:
    analyst: {}
# agent.py
import os

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
from strands_tools.code_interpreter import AgentCoreCodeInterpreter

app = BedrockAgentCoreApp()
code_interpreter = AgentCoreCodeInterpreter(region=os.environ["AWS_REGION"])


@app.entrypoint
async def invoke(payload, context):
    agent = Agent(
        tools=[code_interpreter.code_interpreter],
        system_prompt="You are a data analyst. Run code to calculate and analyze data.",
    )
    async for event in agent.stream_async(payload.get("prompt", "")):
        yield event


if __name__ == "__main__":
    app.run()

The agent needs the bedrock-agentcore, strands-agents and strands-agents-tools packages; with a Dockerfile in the service directory, the Framework builds and deploys it as described in AgentCore Runtime agents. The agent's generated role allows sessions on the AWS-managed code interpreter, aws.codeinterpreter.v1.

Within a session, variables, imports and files persist between calls. A session stops after 15 minutes by default, or when the agent stops it.

Use the code interpreter from a LangGraph agent

In Python, create_code_interpreter_toolkit from langchain_aws.tools returns ready-made tools; call cleanup() to stop the session:

import os

from langchain.chat_models import init_chat_model
from langchain_aws.tools import create_code_interpreter_toolkit
from langgraph.prebuilt import create_react_agent


async def run(prompt):
    toolkit, tools = await create_code_interpreter_toolkit(region=os.environ["AWS_REGION"])
    try:
        llm = init_chat_model(os.environ["MODEL_ID"], model_provider="bedrock_converse")
        agent = create_react_agent(model=llm, tools=tools)
        result = await agent.ainvoke({"messages": [{"role": "user", "content": prompt}]})
        return result["messages"][-1].content
    finally:
        await toolkit.cleanup()

Use the code interpreter from a JavaScript agent

The bedrock-agentcore package provides CodeInterpreter, with executeCode, executeCommand, readFiles, writeFiles, listFiles and stopSession. Wrap the methods as tools for your agent framework:

// index.js
import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime'
import { CodeInterpreter } from 'bedrock-agentcore/code-interpreter'
import { ChatBedrockConverse } from '@langchain/aws'
import { tool } from '@langchain/core/tools'
import { createAgent } from 'langchain'
import { z } from 'zod'

const codeInterpreter = new CodeInterpreter({ region: process.env.AWS_REGION })

const executeCode = tool(
  async ({ code, language }) =>
    (await codeInterpreter.executeCode({ code, language })) || 'No output',
  {
    name: 'execute_code',
    description: 'Run code in a sandbox and return its output.',
    schema: z.object({
      code: z.string(),
      language: z
        .enum(['python', 'javascript', 'typescript'])
        .default('python'),
    }),
  },
)

const agent = createAgent({
  model: new ChatBedrockConverse({
    model: process.env.MODEL_ID,
    region: process.env.AWS_REGION,
  }),
  tools: [executeCode],
})

const app = new BedrockAgentCoreApp({
  invocationHandler: {
    requestSchema: z.object({ prompt: z.string() }),
    async process(request) {
      try {
        const result = await agent.invoke({
          messages: [{ role: 'user', content: request.prompt }],
        })
        return { result: result.messages.at(-1).content }
      } finally {
        await codeInterpreter.stopSession()
      }
    },
  },
})

app.run()

Set MODEL_ID in the agent's environment. The dependencies:

{
  "type": "module",
  "dependencies": {
    "@langchain/aws": "^1.2.5",
    "@langchain/core": "^1.1.28",
    "bedrock-agentcore": "^0.4.0",
    "langchain": "^1.2.27",
    "zod": "^4.3.6"
  }
}

Define a custom code interpreter

A custom code interpreter is an AWS::BedrockAgentCore::CodeInterpreterCustom resource with your network mode and execution role. network.mode selects what the sandboxed code can reach:

ModeThe code can reach
SANDBOX (default)No public internet
PUBLICThe internet, for example to call APIs or download packages
VPCResources in your VPC, through your subnets
ai:
  codeInterpreters:
    webAnalyst:
      description: Code interpreter with internet access
      network:
        mode: PUBLIC

description, network and role are fixed when AWS creates the code interpreter: changing one of them replaces it, and it gets a new ID.

Use a custom code interpreter from an agent

The Framework doesn't connect custom code interpreters to agents. Pass the code interpreter ID to the agent in an environment variable, and allow the session actions on its ARN:

ai:
  codeInterpreters:
    webAnalyst:
      network:
        mode: PUBLIC

  agents:
    analyst:
      environment:
        CODE_INTERPRETER_ID: !GetAtt WebAnalystCodeInterpreter.CodeInterpreterId
      role:
        statements:
          - Effect: Allow
            Action:
              - bedrock-agentcore:StartCodeInterpreterSession
              - bedrock-agentcore:InvokeCodeInterpreter
              - bedrock-agentcore:StopCodeInterpreterSession
            Resource: !GetAtt WebAnalystCodeInterpreter.CodeInterpreterArn

The logical ID is the code interpreter's name with the first letter capitalized, followed by CodeInterpreter (webAnalyst becomes WebAnalystCodeInterpreter). In the agent code, pass the ID when you start a session.

In JavaScript:

import { CodeInterpreter } from 'bedrock-agentcore/code-interpreter'

const codeInterpreter = new CodeInterpreter({
  region: process.env.AWS_REGION,
  identifier: process.env.CODE_INTERPRETER_ID,
})

In Python:

import os

from bedrock_agentcore.tools.code_interpreter_client import CodeInterpreter

code_interpreter = CodeInterpreter(region=os.environ["AWS_REGION"])
code_interpreter.start(identifier=os.environ["CODE_INTERPRETER_ID"])
response = code_interpreter.invoke(
    method="executeCode",
    params={"code": "print(6 * 7)", "language": "python"},
)
code_interpreter.stop()

Connect a code interpreter to a VPC

With network.mode: VPC, the code interpreter runs with network interfaces in your subnets:

ai:
  codeInterpreters:
    warehouse:
      network:
        mode: VPC
        subnets:
          - subnet-0123456789abcdef0
          - subnet-0123456789abcdef1
        securityGroups:
          - sg-0123456789abcdef0

subnets and securityGroups are both required, 1 to 16 IDs each, and the subnets must be in Availability Zones that AgentCore supports. For internet access as well, use private subnets with a route to a NAT gateway. See Configure AgentCore for VPC.

IAM role for a code interpreter

The code interpreter's execution role is what code in the sandbox runs with, for example AWS CLI commands that read from Amazon S3. Without role, the Framework creates one per code interpreter, named <service>_<name>_ci_role_<stage> (truncated to 48 characters), that allows CloudWatch Logs under /aws/bedrock-agentcore/. To give the code more access, add statements:

ai:
  codeInterpreters:
    warehouse:
      role:
        statements:
          - Effect: Allow
            Action: s3:GetObject
            Resource: arn:aws:s3:::my-data-bucket/*

role takes the same forms as an agent's role: an object with name, statements, managedPolicies, permissionsBoundary and tags, or an ARN, a logical ID or a CloudFormation intrinsic to use a role you manage. See IAM role for an agent.

ai.codeInterpreters configuration reference

KeyTypeDefaultValue
network.modestringSANDBOXSANDBOX, PUBLIC or VPC
network.subnetslist of stringsNoneSubnet IDs; required with VPC
network.securityGroupslist of stringsNoneSecurity group IDs; required with VPC
descriptionstringNone1 to 1,200 characters
rolestring or objectGenerated roleSee IAM role for a code interpreter
tagsmap of stringsNoneTags on the code interpreter

For a code interpreter named webAnalyst, the stack contains WebAnalystCodeInterpreter, named <service>_webAnalyst_<stage> (truncated to 48 characters), and outputs WebAnalystCodeInterpreterArn (exported as <service>-<stage>-webAnalyst-CodeInterpreterArn), WebAnalystCodeInterpreterId and WebAnalystCodeInterpreterRoleArn.

Examples

  • LangGraph with the AWS-managed code interpreter (JavaScript) and (Python).
  • Custom code interpreter with PUBLIC network mode (JavaScript) and (Python).

Related pages

  • AgentCore Browser: let the agent browse websites.
  • AgentCore Runtime agents: the agent settings, including role and environment.
  • Amazon Bedrock AgentCore Code Interpreter in the AgentCore developer guide.
Edit this page
Prev BrowserNextDev Mode

Contents

  • AgentCore Code Interpreter for agents
  • Use the code interpreter from a LangGraph agent
  • Use the code interpreter from a JavaScript agent
  • Define a custom code interpreter
  • Use a custom code interpreter from an agent
  • Connect a code interpreter to a VPC
  • IAM role for a code interpreter
  • ai.codeInterpreters configuration reference
  • Examples
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport