Serverless Framework 部署 LangGraph Code Interpreter Agent：基于 Bedrock AgentCore 托管代码解释器的 Python 实战
【免费下载链接】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
本文以仓库内的完整可运行示例 langgraph-code-interpreter 为核心，讲解如何用 Serverless Framework v4+ 在 AWS Bedrock AgentCore 上部署一个具备真实代码执行能力的 LangGraph Agent：Agent 通过langchain-aws的create_code_interpreter_toolkit()接入 AWS 托管默认代码解释器（SANDBOX 模式），可运行 Python 代码、操作文件、安装依赖，并能按thread_id隔离会话状态。读完本文你能够理解该示例的完整配置与代码结构、掌握部署/验证/清理的完整流程，并了解 Serverless Framework 底层如何把ai配置编译为 CloudFormation 资源。
示例定位与能力概览
这个示例解决的是一个典型痛点：LLM 无法执行真实计算与代码。当提示词要求"算出第 50 个斐波那契数"这类必须实际运行代码才能回答的问题时，仅靠模型心智计算不可靠。该示例通过把代码解释器（Code Interpreter）以工具（Tool）形式挂载到 LangGraph ReAct Agent 上，让 Agent 在执行任务时自主决定"写代码并运行"，从而具备数据计算、文件操作与结果验证能力。
示例主要特点（源自 README）：
- Default Code Interpreter：直接使用 AWS 托管的默认代码解释器（SANDBOX 模式），无需自建解释器资源；
- LangGraph Integration：通过
langchain-aws的create_code_interpreter_toolkit()一行获取整套工具； - Full Tool Suite：一次获得代码执行、文件读写、包安装等完整工具链；
- Session Isolation：每个
thread_id独立维护会话状态，互不干扰。
说明：示例属于仓库中 Bedrock AgentCore 插件（
packages/serverless/lib/plugins/aws/bedrock-agentcore/）下的 Python 示例族，同族还包括 BASIC/DOCKER/BROWSER/MEMORY/GATEWAY 等多类变体，本示例聚焦"默认托管代码解释器"这一最小闭环。
前置条件
- 拥有已开通 Bedrock 模型访问权限的 AWS 账号；
- 本机安装 Docker（示例以容器方式部署运行时代码）；
- Serverless Framework v4 及以上；
- Python 3.12+（pyproject.toml 中
requires-python = ">=3.12"）。
项目结构
langgraph-code-interpreter/ ├── serverless.yml # Serverless Framework 配置（定义 agent 运行时） ├── agent.py # LangGraph Agent 与代码解释器工具逻辑 ├── Dockerfile # 容器定义（Python 3.12 slim） ├── pyproject.toml # Python 依赖声明 ├── test-invoke.py # 验证脚本（斐波那契校验） └── README.md # 示例说明部署流程
1. 执行部署
serverless deploy在示例目录下运行时，Serverless Framework 读取serverless.yml，编译出 Agent Runtime 所需的 CloudFormation 资源（含容器镜像构建与上传、IAM 角色等），并输出部署信息。
2. 记录运行时端点 URL
部署完成后，输出中会给出 runtime 端点 URL，ARN 内嵌在 URL 路径中，类似：
ai: agents: codeAgent: https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/.../invocations其中的 ARN 是后续测试脚本调用所必需的RUNTIME_ARN。
配置剖析：极简 serverless.yml 背后是什么
本示例的 serverless.yml 非常精简：
service: langgraph-code-interpreter provider: name: aws ai: agents: # Runtime agent with code execution capabilities # Uses AWS-managed default code interpreter (SANDBOX mode) codeAgent: {}关键点在于：codeAgent: {}是空对象。从源码结构看，这意味着 Agent不声明任何自定义代码解释器，因此在运行时使用的是 AWS 托管的默认代码解释器（SANDBOX 模式），agent.py通过create_code_interpreter_toolkit()直接接入即可，无需额外 IAM 授权自定义解释器资源。
对比同目录的 langgraph-code-interpreter-custom 示例可以看到差异：自定义解释器需要在ai.codeInterpreters下显式声明并配置network.mode: PUBLIC，还要在 agent 的environment与role.statements中注入解释器 ID 与权限。本示例即"零自定义、全托管"的最简形态。
网络模式背景（SANDBOX / PUBLIC / VPC）
结合示例族中的对比说明与插件编译器实现，代码解释器存在三种网络模式：
| 模式 | 网络访问 | 适用场景 |
|---|---|---|
| SANDBOX（默认） | 无 | 最高安全性、本地计算（本示例） |
| PUBLIC | 公网 | 调用外部 API、下载数据 |
| VPC | 私有 VPC | 访问内部资源 |
该行为与插件实现一致：在 compilers/codeInterpreter.js 中，buildCodeInterpreterNetworkConfiguration()会将network.mode归一化为大写并默认取SANDBOX，同时据此生成NetworkMode，VPC 模式下再附带Subnets与SecurityGroups；若配置了自定义解释器，最终会编译为AWS::BedrockAgentCore::CodeInterpreterCustom类型资源。需要外网能力的读者可直接对照 langgraph-code-interpreter-custom 示例迁移。
Agent 代码逐段解读
agent.py 是 Agent 的全部运行时逻辑，其骨架如下：
from bedrock_agentcore.runtime import BedrockAgentCoreApp from langchain.chat_models import init_chat_model from langchain_aws.tools import create_code_interpreter_toolkit from langgraph.prebuilt import create_react_agent # Initialize the AgentCore app app = BedrockAgentCoreApp() # Configuration AWS_REGION = os.environ.get("AWS_REGION", "us-east-1") MODEL_ID = os.environ.get("MODEL_ID", "us.anthropic.claude-sonnet-4-20250514-v1:0")三处易被忽略的细节值得展开：
BedrockAgentCoreApp运行时入口：@app.entrypoint装饰的invoke是每次请求的入口，它从payload取prompt，从context取session_id（缺省为"default"）。容器内通过app.run(port=port, host="0.0.0.0")启动 HTTP 服务，端口默认取环境变量PORT（默认 8080）。- 模型与区域配置均可覆盖：
MODEL_ID默认使用us.anthropic.claude-sonnet-4-20250514-v1:0，AWS_REGION默认us-east-1；示例注释指出 AWS_REGION 由 AgentCore 自动注入，本地调试时才需手动指定。 - 模型通过 Bedrock Converse 协议调用：
init_chat_model(MODEL_ID, model_provider="bedrock_converse")是 langchain 统一模型初始化入口，这里显式指定了 AWS Bedrock 的 Converse 提供方。
创建代码解释器工具包并构建 Agent
# Create code interpreter toolkit (uses AWS-managed default) toolkit, code_tools = await create_code_interpreter_toolkit(region=AWS_REGION) # Initialize chat model llm = init_chat_model(MODEL_ID, model_provider="bedrock_converse") # Create the LangGraph agent with code interpreter tools agent = create_react_agent(model=llm, tools=code_tools) # Create config with thread_id for session isolation config = {"configurable": {"thread_id": session_id}} # Run the agent result = await agent.ainvoke( {"messages": [{"role": "user", "content": prompt}]}, config=config, )核心调用链为：
create_code_interpreter_toolkit(region=...)返回二元组(toolkit, code_tools)，code_tools即挂载给 Agent 的工具列表；不传入自定义identifier即走 AWS 托管默认解释器（对应 SANDBOX）。运行日志会打印Created toolkit with N tools与各工具名，便于排查。create_react_agent是 LangGraph 预构建的 ReAct Agent，负责"思考 → 调用工具 → 观察结果"循环。thread_id放在configurable中供 LangGraph 做会话/记忆隔离，agent.ainvoke一次完成整个执行过程。
响应提取与资源清理
# Extract the final response final_message = result["messages"][-1].content # Clean up the toolkit await toolkit.cleanup() return { "result": final_message, "tools_used": [t.name for t in code_tools], "interpreter_type": "default", }关键实践是在返回前必须await toolkit.cleanup()释放解释器会话资源；返回体中附带tools_used与interpreter_type: "default"字段，后者会被测试脚本用于确认走的是默认解释器路径。整个invoke外层用try/except包裹，异常时返回{"error": str(e)}，避免运行时崩溃。
可用工具一览
按 README 与agent.py中code_tools的命名，create_code_interpreter_toolkit()提供以下工具：
| Tool | 描述 |
|---|---|
execute_code | 运行 Python/JS/TS 代码 |
execute_command | 运行 shell 命令 |
read_files | 读取文件内容 |
write_files | 创建/更新文件 |
list_files | 列出目录内容 |
delete_files | 删除文件 |
upload_file | 上传文件（附描述） |
install_packages | 安装 Python 包 |
这些工具共同支撑起"数据分析、数学计算、批量文件加工、可视化"等典型 Agent 任务；由于解释器运行在 AWS 托管沙箱中，包安装与文件操作都被限制在隔离环境内。
Dockerfile 与依赖版本
Dockerfile 采用分层构建思路：
FROM python:3.12-slim WORKDIR /app COPY pyproject.toml . RUN pip install --no-cache-dir . COPY agent.py . ENV PYTHONUNBUFFERED=1 CMD ["python", "agent.py"]- 先拷依赖清单、后拷业务代码：
pyproject.toml层先于agent.py，可在依赖未变化时最大化利用镜像层缓存； pip install --no-cache-dir .：以项目方式安装，构建系统依赖 setuptools（见 pyproject 的[build-system]）；PYTHONUNBUFFERED=1：确保容器日志实时输出，便于 AgentCore 采集运行时日志。
pyproject.toml 声明的关键依赖（以当前仓库中版本约束为准）：
| 包 | 版本约束 | 作用 |
|---|---|---|
| bedrock-agentcore | >=1.3.0 | AgentCore 运行时 SDK（BedrockAgentCoreApp） |
| langchain | >=1.2.10 | 模型统一初始化init_chat_model |
| langchain-aws | >=1.2.5 | create_code_interpreter_toolkit |
| langgraph | >=1.0.8 | ReAct Agent 图执行引擎 |
本地验证：确认真实执行了代码
test-invoke.py 是一个独立于 Agent 的"验收测试"，其验证哲学是：选一个无法靠心算完成的题目——第 50 个斐波那契数（12586269025）。
export RUNTIME_ARN="arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/..." python test-invoke.py脚本核心行为：
- 配置长超时客户端：代码执行可能耗时较长，boto3 客户端显式配置
read_timeout=300、connect_timeout=30、retries={'max_attempts': 1}，避免默认短超时导致误判。 - 每次调用独立会话：
session_id = str(uuid.uuid4())，对应"会话隔离"特性验证。 - 调用
invoke_agent_runtime：向RUNTIME_ARN对应的运行时发送{"prompt": ...}，并读取流式response。 - 答案校验：同时检查纯数字
12586269025与千分位格式12,586,269,025是否出现在回复中；若未命中，则退而检查回复中是否出现def、fib、for、print(等"代码执行痕迹"，输出VALIDATION PASSED或VALIDATION INCONCLUSIVE并返回相应退出码。
该脚本可作为模板改造：替换EXPECTED_ANSWER与提示词即可复用于其他"需要真实计算/取数"的验收场景。
典型提示词示例
# Data analysis（数据分析） "Create a dataset of 100 random sales records and calculate average by product" # Calculations（数学计算） "Calculate the 50th Fibonacci number" # File operations（文件操作） "Create a Python script that reads a CSV and generates a summary report" # Visualization（可视化） "Generate a bar chart showing monthly sales trends"这四类提示词分别命中工具集中的代码执行、文件读写与包安装能力——例如"生成条形图"会触发install_packages（安装绘图库）→execute_code（绘图）→ 输出文件，直观体现工具编排闭环。
资源清理
验证完毕后，删除部署创建的全部资源（运行时、容器镜像、IAM 角色等）：
serverless remove关联示例：需要外网能力时怎么办
- langgraph-code-interpreter-custom：在默认示例之上声明
ai.codeInterpreters并配置network.mode: PUBLIC，让沙箱内代码可访问外部 API 与互联网资源；其 Agent 通过CodeInterpreter.start(identifier=CUSTOM_INTERPRETER_ID)绑定自定义解释器，并在serverless.yml中借助!GetAtt PublicInterpreterCodeInterpreter.CodeInterpreterId注入解释器 ID、借助role.statements授予bedrock-agentcore:StartCodeInterpreterSession / InvokeCodeInterpreter / StopCodeInterpreterSession权限。若你的 Agent 需要联网取数（如抓取公共 API），请参照该示例在本文最小闭环上增量演进。
小结：一个可复用的最小 Agent 模板
本示例的价值在于它浓缩出一个"零基础设施心智负担的代码执行 Agent"最小模板：极简serverless.yml声明运行时 → 容器化 Python 代码定义 Agent →create_code_interpreter_toolkit一行接入托管解释器 →thread_id隔离会话 → 斐波那契题目验收真实执行能力 →serverless remove一键清理。需要联网、接入自定义解释器或增加网关/记忆等能力时，仓库中 python 示例目录 的其余变体（browser、memory、gateway、multi-gateway 等）提供了阶梯式的扩展参照。
【免费下载链接】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），仅供参考
