Serverless Framework 实战：在 AWS Bedrock AgentCore 上部署带代码解释器的 LangGraph JavaScript Agent

Serverless Framework 实战在 AWS Bedrock AgentCore 上部署带代码解释器的 LangGraph JavaScript Agent【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless本文基于 Serverless Framework 仓库中bedrock-agentcore插件的官方示例完整讲解如何使用LangGraph JS AWS 托管代码解释器Code Interpreter构建一个可执行 Python/JavaScript/TypeScript 代码、读写沙箱文件、运行 Shell 命令的 AI Agent并把它部署到 AWS Bedrock AgentCore。读完本文你将掌握示例工程的结构、serverless.yml中最简配置的写法、沙箱代码执行工具的实现方式、本地端到端测试test-invoke.js以及后续移除资源的标准流程。示例工程完整源码位于 langgraph-code-interpreter 示例目录配套插件说明见 Bedrock AgentCore Plugin 文档。示例概览让 Agent 真正动手算大模型本身的弱点是只说不做。本示例解决的核心问题就是当模型需要精确计算、生成/分析数据或运行脚本时如何安全地让它执行真实代码。它由两部分协作构成LangGraph JS Agent采用 LangChain/LangGraph 生态的createAgentReAct 模式的 Agent由 ClaudeAmazon Bedrock 上的ChatBedrockConverse驱动负责理解用户问题并自主决定何时调用工具AWS 托管代码解释器示例直接使用AWS 管理的默认解释器SANDBOX 模式无需自建容器模型通过一组文件/命令工具驱动解释器在隔离沙箱中执行代码。示例声明的核心能力对应 README沙箱化执行在 SANDBOX 环境中运行 Python、JavaScript 或 TypeScript文件操作在沙箱中读取、写入、列出文件Shell 命令执行 Shell 命令LangGraph JSReAct 模式的 Agent 代码执行工具链。提供给 Agent 的 5 个工具示例中所有能力都以工具tool形式暴露给模型由模型按需自主调用工具作用execute_code在沙箱中执行 Python / JavaScript / TypeScript 代码execute_command运行 Shell 命令read_files读取沙箱中的文件内容write_files向沙箱写入文件list_files列出目录内容这 5 个工具并不是凭空注册的——它们分别是对CodeInterpreter客户端方法的薄封装详见下文 index.js 实现解析。仓库中还有一组同主题的 Python 版本示例可供对照langgraph-code-interpreterPython。工程结构与零配置 serverless.yml示例目录文件如下langgraph-code-interpreter/ ├── serverless.yml # Serverless Framework 配置Agent 定义 ├── index.js # LangGraph JS Agent 主逻辑入口 ├── test-invoke.js # 本地端到端测试脚本 ├── package.json # npm 依赖与 Node 版本声明 ├── package-lock.json └── README.md其中最值得一提的是serverless.yml只有寥寥几行# Deploy: serverless deploy # Test: RUNTIME_ARNarn node test-invoke.js service: langgraph-code-interpreter provider: name: aws ai: agents: # Runtime agent with code execution capabilities # Uses AWS-managed default code interpreter (SANDBOX mode) codeAgent: {}对应 serverless.yml 的完整内容。它之所以能这么简洁是因为ai顶级配置属性由 Serverless Framework 的 Bedrock AgentCore 插件解析见插件 README负责把ai.agents.codeAgent翻译成 AgentCore 的 CloudFormation 资源不需要显式声明代码解释器默认的 AWS 托管代码解释器SANDBOX 模式由 AgentCore 自动检测并注入这正是本示例与自定义解释器示例的最大区别部署形态目录中没有Dockerfile插件会自动根据package.json检测 Node.js 运行环境、执行依赖安装并构建 ARM64 容器镜像——这与 langgraph-basic 示例 描述的免 Dockerfile 构建机制一致package.json通过engines.node声明24.x见 package.json作为容器基础镜像选型的依据。ai顶层属性下实际上支持 6 类资源agents运行时 Agent、memory对话记忆、toolsLambda/OpenAPI/Smithy/MCP 工具、gateways工具路由网关、browsers浏览器能力与codeInterpreters自定义代码解释器。每种资源使用独立的节区不存在type判别字段。本示例只用到agents且整个 Agent 采用默认配置。核心实现 index.js 解析index.js采用BedrockAgentCoreApp的运行时编程模型整体流程是初始化 LLM → 注册 Agent 应用 → 在每次请求中创建独立的CodeInterpreter→ 用 5 个工具包裹其方法 →createAgent组装 → 调用并返回结果。1. 模型与运行时初始化const AWS_REGION process.env.AWS_REGION || us-east-1 const MODEL_ID process.env.MODEL_ID || us.anthropic.claude-sonnet-4-5-20250929-v1:0 const model new ChatBedrockConverse({ model: MODEL_ID, region: AWS_REGION, }) const app new BedrockAgentCoreApp({ invocationHandler: { requestSchema: z.object({ prompt: z.string().describe(The user message to process), }), async process(request, context) { /* ... */ }, }, }) app.run()关键点模型默认使用 Claude Sonnet 4.5us.anthropic.claude-sonnet-4-5-20250929-v1:0均可用MODEL_ID、AWS_REGION环境变量覆盖其中AWS_REGION会被 AgentCore 自动注入到运行时运行时 SDK 来自bedrock-agentcore/runtimenpm 依赖bedrock-agentcore见 package.json 第 13 行requestSchema用 zod 声明请求载荷为{ prompt }与客户端test-invoke.js发送的 JSON 一一对应。2. 每次请求创建独立的代码解释器会话const sessionId context?.sessionId || default // Create code interpreter per request (for session isolation) const codeInterpreter new CodeInterpreter({ region: AWS_REGION })示例刻意在process内部创建解释器实例以便实现会话级隔离每个请求拥有独立的执行沙箱互不污染。3. 工具封装5 个工具对应 5 个方法下面完整展示 5 个工具的定义均使用 LangChain 的tool()与 zod schema这是理解代码解释器如何变成 Agent 工具的核心代码。执行代码const executeCode tool( async ({ code, language }) { const result await codeInterpreter.executeCode({ code, language: language || python, }) return result || Code executed successfully (no output) }, { name: execute_code, description: Execute code in a secure sandbox. Supports Python, JavaScript, and TypeScript., schema: z.object({ code: z.string().describe(Code to execute), language: z .enum([python, javascript, typescript]) .optional() .describe(Programming language (default: python)), }), }, )执行 Shell 命令const executeCommand tool( async ({ command }) { const result await codeInterpreter.executeCommand({ command }) return result || Command executed successfully (no output) }, { name: execute_command, description: Execute a shell command in the sandbox., schema: z.object({ command: z.string().describe(Shell command to execute), }), }, )读取文件const readFiles tool( async ({ paths }) { const result await codeInterpreter.readFiles({ paths }) return result || No content }, { name: read_files, description: Read contents of files in the sandbox., schema: z.object({ paths: z.array(z.string()).describe(List of file paths to read), }), }, )写入文件const writeFiles tool( async ({ files }) { const result await codeInterpreter.writeFiles({ files }) return result || Files written successfully }, { name: write_files, description: Write files in the sandbox., schema: z.object({ files: z .array( z.object({ path: z.string().describe(File path), content: z.string().describe(File content), }), ) .describe(Files to write), }), }, )列出目录const listFiles tool( async ({ path }) { const result await codeInterpreter.listFiles({ path: path || . }) return result || No files found }, { name: list_files, description: List files in the sandbox directory., schema: z.object({ path: z .string() .optional() .describe(Directory path (default: current directory)), }), }, )4. 组装 Agent 并完成一轮推理const codeTools [executeCode, executeCommand, readFiles, writeFiles, listFiles] const agent createAgent({ model, tools: codeTools, }) const result await agent.invoke({ messages: [{ role: user, content: request.prompt }], }) const finalMessage result.messages[result.messages.length - 1] const response finalMessage.content return JSON.stringify({ result: response, tools_used: codeTools.map((t) t.name), interpreter_type: default, })这段代码体现了 ReAct 模式的精髓Agent 根据用户问题规划步骤若需要计算/文件操作便自主挑选合适工具调用最后把推理结果作为result返回给客户端。5. 会话清理无论成功还是失败方法都在finally中显式停止解释器会话避免沙箱资源泄漏} finally { try { await codeInterpreter.stopSession() console.log(Code interpreter session stopped) } catch { // ignore cleanup errors } }沙箱模式说明SANDBOX / PUBLIC / VPC本示例使用的是AWS 托管默认代码解释器网络模式为SANDBOX无网络访问适合纯隔离计算场景。从底层编译器源码可以确认这种模式划分compilers/codeInterpreter.js中的buildCodeInterpreterNetworkConfiguration会将配置归一化映射为AWS::BedrockAgentCore::CodeInterpreterCustom资源的NetworkConfiguration// mode 缺省时大写归一为 SANDBOX支持 PUBLIC / SANDBOX / VPC const networkMode (network.mode || SANDBOX).toUpperCase()对应 CloudFormation 模式枚举PUBLIC可访问外网、SANDBOX默认隔离无网、VPC私有网络需提供 Subnets 与 SecurityGroups。插件 README 中关于ai.codeInterpreters的配置表也印证了这一点属性是否必填说明network.mode否sandbox默认、public或vpcnetwork.subnets否VPC 子网 IDvpc模式必填network.securityGroups否VPC 安全组 IDvpc模式必填description否CodeInterpreter 描述≤1200 字符role否IAM 角色 ARN 或定制化对象tags否资源标签键值对因此只要你的场景是隔离的数值/数据处理默认解释器如本示例就是最省事的方案当 Agent 需要调用外部 API、抓取网页等联网能力时才需要显式声明一个network.mode: public的自定义解释器。补充需要公网时的自定义解释器仓库提供了配套对照示例 langgraph-code-interpreter-custom两示例的差异可概括为维度默认解释器本示例自定义解释器custom 示例网络模式SANDBOX无网络PUBLIC可访问公网标识AWS 托管aws.codeinterpreter.v1自定义解释器 ID典型场景隔离计算外部 API 调用、网页抓取自定义示例的serverless.yml会在ai.codeInterpreters下定义解释器、通过!GetAtt拿到CodeInterpreterId写入环境变量并手动授予StartCodeInterpreterSession/InvokeCodeInterpreter/StopCodeInterpreterSession权限而本示例由于使用托管默认解释器上述 IAM 授权全部由插件自动生成无需任何手工配置。从部署到端到端验证1. 部署在示例目录下执行npm install sls deploy前置条件与仓库其他 LangGraph JS 示例一致参见 langgraph-basic READMENode.js 20Docker用于自动构建容器镜像已配置 AWS 凭证Serverless Framework CLInpm install -g serverlesssls deploy完成后从 CloudFormation 输出中取出 Agent 的Runtime ARN。按插件约定每个 Agent 资源都会自动生成形如{Name}RuntimeArn的输出AgentCore 插件的输出命名规则见 CloudFormation Outputs 一节因此本例可在部署输出中找到codeAgentRuntimeArn。2. 本地端到端测试测试脚本通过InvokeAgentRuntimeCommand直接调用已部署的 Agent读取环境变量RUNTIME_ARN与可选AWS_REGION并为每次运行生成随机SESSION_IDRUNTIME_ARNyour-runtime-arn node test-invoke.js脚本内置了两组真实场景的测试用例见 test-invoke.jsTest 1让 Agent编写并执行 Python 代码计算并展示前 20 个斐波那契数Test 2让 Agent生成 1~100 之间的 10 个随机数并计算它们的均值、中位数与标准差。这两组用例都要求模型真正调用execute_code工具让沙箱执行代码而不是凭语言模型猜答案能非常直观地验证代码解释器是否正常工作。调用协议方面值得注意的实现细节同样来自test-invoke.jsconst command new InvokeAgentRuntimeCommand({ agentRuntimeArn: RUNTIME_ARN, runtimeSessionId: SESSION_ID, payload: Buffer.from(JSON.stringify({ prompt: inputText })), contentType: application/json, accept: application/json, text/event-stream, })payload的 JSON 结构{ prompt }必须与index.js中requestSchema的 zod 声明严格一致accept同时声明 JSON 与text/event-stream脚本对异步迭代的响应体逐块聚合后尝试JSON.parse优先输出result字段。此外index.js通过tools_used字段会把本次实际调用的工具列表随结果返回方便你在测试输出中确认 Agent 是否真的按预期执行了代码——例如{result:..., tools_used:[execute_code], interpreter_type:default}。3. 更多验证与清理手段插件为 AgentCore 资源提供了一组配套 CLI 命令见插件 README 的 Commands 一节部署完成后也可以直接调用sls invoke --agent codeAgent -d Hello # 直接调用已部署的 Agent sls logs --agent codeAgent # 拉取 Agent 运行日志 sls package # 仅生成 CloudFormation不部署不再需要时执行资源清理sls remove延伸阅读如果你希望进一步探索 AgentCore 代码执行能力的边界建议继续阅读仓库内以下相关内容自定义代码解释器示例JavaScript同主题的 PUBLIC 网络版对照实现自定义代码解释器示例PythonPython 语言版本的自定义解释器写法代码解释器编译器源码底层 CloudFormation 资源生成逻辑Bedrock AgentCore Plugin 文档ai配置全部资源类型的完整参考与输出变量说明langgraph-basic 示例理解免 Dockerfile 自动构建的 Agent 基础部署方式。【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考