Serverless Framework AgentCore 综合示例深度解析在 LangGraph 智能体中组合 Gateway 工具、MCP、浏览器、代码沙箱与记忆【免费下载链接】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 FrameworkAWS provider的bedrock-agentcore插件所附带的综合示例 ——langgraph-comprehensive。它以单个 LangGraph ReAct 智能体为骨架一次性演示 AgentCore 的多项核心能力通过 Gateway 暴露的 Lambda 函数工具、智能体代码直连的 MCP 服务器、默认浏览器工具、默认代码解释器以及会话记忆。读完本文你将掌握ai:顶层配置的编排方式、AgentCore Runtime 环境变量注入机制、无 Dockerfile 的自动镜像构建buildpacks前提条件以及一套可独立验证各类工具的端到端测试脚本可直接对照示例目录动手部署与二次开发。该示例位于packages/serverless/lib/plugins/aws/bedrock-agentcore/examples/javascript/langgraph-comprehensive/是示例族packages/serverless/lib/plugins/aws/bedrock-agentcore/examples/javascript/中覆盖能力最广的一份。示例定位一个部署展示 AgentCore 六大能力官方 README 明确说明了该示例的核心目标在单个部署中演示 AgentCore 的多种能力而非把每项能力拆成独立工程。对应到示例目录其能力清单如下能力说明对应实现Gateway 工具通过 AgentCore Gateway 将 Lambdacalculator暴露为工具serverless.yml的ai.tools.calculator直连 MCP 服务器AWS Knowledge MCP公共端点无需网关agents/index.js中loadKnowledgeMcpTools()默认浏览器网页导航与内容抽取PlaywrightBrowsercreateBrowserTools()默认代码解释器沙箱化代码执行CodeInterpretercreateCodeInterpreterTools()记忆会话持久化list_events工具 自动保存listEvents/saveToMemory()自动构建无 Dockerfile框架经 buildpacks 由源码构建镜像package.json的scripts.startagents/目录约定Agent 代码位于agents/index.js而非项目根目录结构除了以上功能点示例还体现了 AgentCore 的目录组织约定——业务 Agent 代码放在agents/子目录、Lambda handler 放在handlers/子目录。示例完整文件清单见下表与源码目录examples/javascript/langgraph-comprehensive/一一对应文件用途serverless.yml基础设施配置Lambda、AI 工具、Agent、记忆agents/index.js汇聚全部工具来源的 LangGraph Agenthandlers/calculator.jsCalculator LambdaGateway 工具package.json依赖声明与供自动构建使用的 start 脚本package-lock.json自动构建所需的锁文件test-invoke.js逐项测试各类工具的脚本架构从用户请求到多路工具调度README 给出了架构示意其调用链为用户请求 → AgentCore Runtime →agents/index.js→ LangGraph ReAct Agent → Claude Sonnet。语言模型之下汇聚了六类工具来源User Request -- AgentCore Runtime -- agents/index.js | LangGraph ReAct Agent | Claude Sonnet | ---------------------------------------------- | | | | | | Gateway MCP Direct MCP Browser Code Interp. Memory Direct | | Response Calculator AWS Knowledge (Lambda) (public MCP)其中右侧的 Direct Response 表示智能体在不需要任何工具时也可以直接把最终答案流式返回给 Runtime。六路工具按来源可分为三类经由 Gateway 的工具calculator Lambda通过BEDROCK_AGENTCORE_GATEWAY_URL环境变量以 MCP 协议 SigV4 签名发现智能体直连的工具AWS Knowledge MCPhttps://knowledge-mcp.global.api.aws公共端点、无需网关与认证进程内封装的工具浏览器navigate / get_text / click / screenshot、代码解释器execute_code / execute_command与记忆工具list_events。从实现看所有工具最终被合并后传给createAgent来自langchain由 Claude 自行决策该调用哪个工具这正是 LangGraph ReAct 模式的核心行为agents/index.js。前置条件与 Quick Start示例 README 列出的前置条件以当前仓库实际代码为准可归纳为具备 Bedrock 模型访问权限的 AWS 账户需启用 Claude Sonnet 模型在 Bedrock 控制台启用模型us.anthropic.claude-sonnet-4-5-20250929-v1:0该 ID 同时是agents/index.js中MODEL_ID的默认值本机安装 DockerServerless Framework v4即本仓库packages/serverless对应的 CLI 版本已配置 AWS 凭证。1. 部署serverless deploy框架在此过程中会自动完成对应 README 描述并经插件源码佐证从源码自动构建 Docker 镜像无需 Dockerfile→ 推送至 Amazon ECR → 部署 Calculator Lambda 函数 → 创建带 calculator 工具的 AgentCore Gateway → 创建 AgentCore Memory30 天过期→ 部署 AgentCore Runtime。2. 端到端测试RUNTIME_ARNyour-runtime-arn node test-invoke.jsRUNTIME_ARN从serverless info输出中获取。同时示例还给出了更轻量的交互入口serverless invoke -a assistant -d Hello3. 本地开发serverless dev配置详解serverless.yml中的 AI 编排示例serverless.yml的ai:配置块是 AgentCore 能力编排的核心语法完整内容见 serverless.ymlservice: langgraph-comprehensive provider: name: aws region: us-east-1 functions: calculatorFunction: handler: handlers/calculator.handler runtime: nodejs24.x ai: tools: # Lambda function tool -- math expression evaluator calculator: function: calculatorFunction toolSchema: - name: calculate description: Perform basic arithmetic on two numbers. Supports , -, *, /. For complex calculations, break them into multiple calls. inputSchema: type: object properties: expression: type: string description: Arithmetic expression in number operator number format (e.g., 2 3, 10 / 5) required: - expression agents: assistant: memory: expiration: 30 # Days until memory events expire (3-365)各段配置的语义可结合 AgentCore 插件的配置校验源码确认functions.calculatorFunction一个标准 AWS LambdaNode.js 24 运行时handler 指向handlers/calculator.handler。它并不直接暴露给用户而是作为工具被 AI 网关代理ai.tools.calculator定义一个名为calculator的 AI 工具其类型为 Lambda 函数工具靠toolSchema描述给 LLM 看的结构化入参。校验实现validators/schema.js说明该层合法来源包括function须带toolSchema与mcpMCP 服务端点两类ai.agents.assistant定义一个assistantAgent其memory.expiration为 30表示记忆事件的过期天数官方注释范围是 3–365 天。示例中该工具会被自动放入框架自动创建的默认 Gateway无需手写gateways段。值得强调的是calculator 工具经自动创建的默认 Gateway 暴露而 AWS Knowledge MCP 是从 Agent 代码里直连的完全不经过 Gateway——这正是该示例演示两种 MCP 接入形态差异的地方。插件的配置校验代码validators/config.js还能看到更多细节gateways.tools必须是已存在于ai.tools中的工具名数组Gateway 可配置authorizer其合法类型与 CUSTOM_JWT 的discoveryUrl等要求均有强校验memory既可以内联配置对象也可以用字符串引用ai.memory下的共享定义。综合示例使用的function形式工具正是校验器gatewayConfig.toolssharedTools引用模型的应用场景。工具来源逐路拆解agents/index.js实现剖析Agent 主逻辑约 500 行位于 agents/index.js其顶部注释与代码共同描述了三条由框架自动注入的环境变量BEDROCK_AGENTCORE_GATEWAY_URLGateway 工具的 MCP 端点BEDROCK_AGENTCORE_MEMORY_ID记忆持久化标识AWS_REGIONAWS 区域。1. Gateway 工具Calculator LambdaloadGatewayTools()的完整链路为读取BEDROCK_AGENTCORE_GATEWAY_URL未配置则跳过不影响其他工具加载通过aws-sdk/credential-provider-node的defaultProvider取得临时凭证用aws4fetch的AwsV4Signer构造签名 fetch服务名bedrock-agentcore以StreamableHTTPClientTransport MCPClient连接再用langchain/mcp-adapters的loadMcpTools把远程工具物化为 LangChain 工具。Calculator Lambda 本身位于 handlers/calculator.js它用正则/^\s*([\d.])\s*([\-*/])\s*([\d.])\s*$/严格校验数字 运算符 数字形式如2 3、10 / 5杜绝任意表达式求值对除零、非法格式返回 400 与错误信息。这样刻意设计的“窄接口”可让 LLM 学会把复杂计算拆成多次调用。2. 直连 MCPAWS KnowledgeloadKnowledgeMcpTools()演示了“无认证公共 MCP 端点”的直接接入构造指向https://knowledge-mcp.global.api.aws的 Streamable HTTP 传输连接 MCP 客户端后同样用loadMcpTools(aws-knowledge, client)导入工具。相比 Gateway 路径省去了签名 fetch代码也更短。按源码注释其能力覆盖 AWS 文档检索、API 参考与最佳实践问答。3. 默认浏览器懒启动会话createBrowserTools(browser)用bedrock-agentcore/browser/playwright的PlaywrightBrowser封装出四个 LangChain 工具browser_navigate跳转 URLwaitUntil: domcontentloadedbrowser_get_text抽取整页或指定 CSS 选择器的文本省略选择器即全文经truncateOutput截断至 8000 字符并注明原文总长度browser_click按 CSS 选择器点击元素browser_screenshot截取当前页base64返回字符数而非图片本身避免向 LLM 输出超大内容。关键工程点浏览器会话采用首次使用才启动的懒初始化ensureSession会话启动/停止分别对应browser.startSession()与browser.stopSession()避免每次调用都支付冷启动成本。4. 默认代码解释器懒启动沙箱createCodeInterpreterTools(codeInterpreter)把bedrock-agentcore/code-interpreter的CodeInterpreter包成两个工具execute_code在安全沙箱中执行代码语言支持python、javascript、typescriptzod enum 约束缺省 pythonexecute_command在沙箱内执行 shell 命令。同样采用首次使用才startSession()的懒初始化结束时stopSession()。5. 记忆list_events 工具 自动保存记忆是综合示例中最值得研读的部分它由两块组成回忆工具list_events该 LangChain 工具内部通过BedrockAgentCoreClient.send(new ListEventsCommand({ memoryId, actorId, sessionId, includePayloads: true, maxResults: 10 }))拉取最近事件并遍历event.payload中的conversational项把 role/content 拼接为可读历史文本。工具描述引导模型“当用户问起此前对话、要求回忆或引用过往上下文时使用”。自动上下文注入loadRecentHistory每次调用先用ListEventsCommand拉取最近至多 3 条事件转成{role, content}格式的 LangChain 消息作为历史前缀拼接在本次prompt之前再交给模型——这是示例在“显式工具回忆”之外的“隐式上下文”手段。自动保存saveToMemory每轮响应结束后通过CreateEventCommand把本轮 USER/ASSISTANT 两条conversational事件连同eventTimestamp写入 Memory并打印确认日志。关于 session/actor 的约定actorId取自context.sessionId前 8 个字符拼成user-prefixsessionId缺省为default。这一约定配合 test-invoke 中的独立 memory 会话构成了对记忆“写入→读取”闭环的验证。6. Agent 组装与流式输出process(request, context)中先用Promise.all并行加载 Gateway 与 Knowledge 两组 MCP 工具随后组装浏览器、代码解释器与MEMORY_ID 存在时的记忆工具合并后交给createAgent({ model: llm, tools: allTools })。响应阶段使用了agent.stream(..., { streamMode: messages })逐 token 流式输出迭代中仅转发AIMessageChunk的文本内容跳过 tool-call chunk 与 ToolMessage文本以yield推给 Runtime同时累积到response供保存。全部完成后finally中通过Promise.allSettled并行回收浏览器、代码解释器、Gateway、Knowledge 四路会话。应用入口为new BedrockAgentCoreApp({ invocationHandler: {...} })后调用app.run()。自动构建无 Dockerfile 的镜像生产方式该示例特意不提供 Dockerfile以演示框架的自动构建能力。README 指出框架在缺少 Dockerfile 时使用 Heroku buildpacks 构建镜像——读取package.json把scripts.start字段此处为node agents/index.js作为启动命令。自动构建的两个硬性前提是package.json中存在start脚本存在锁文件package-lock.json。在插件源码侧docker 构建相关的 docker/builder.js 通过DockerClient检查 Docker 是否可用ensureIsRunning()、获取 AWS 账户 ID 与区域、向 ECR 申请授权令牌完成“本地构建 推送到 ECR”的流水线从侧面印证了serverless deploy阶段“构建 → ECR → 部署”的完整路径。示例依赖为 ESM 工程type: module锁定了 Node 24使用bedrock-agentcore运行时包、langchain/*全家桶与playwright、zod等见 package.json。验证每一种工具test-invoke.js测试套件test-invoke.js 是官方验证脚本核心用法为RUNTIME_ARNyour-runtime-arn node test-invoke.js # 全部用例 RUNTIME_ARNarn node test-invoke.js calculator # 单项工具 RUNTIME_ARNarn node test-invoke.js knowledge RUNTIME_ARNarn node test-invoke.js browser RUNTIME_ARNarn node test-invoke.js code RUNTIME_ARNarn node test-invoke.js memory RUNTIME_ARNarn node test-invoke.js combined测试内部通过InvokeAgentRuntimeCommand调用 Runtime ARNpayload 为{ prompt }JSONaccept: text/event-stream, application/json优先请求 SSE 流式响应。脚本实现了两层鲁棒解析readResponseStream兼容 Buffer、Uint8Array 与嵌套{chunk:{bytes}}的多种流形态extractResponse依次处理 SSEdata:行、[DONE]、JSONresult/error字段与纯文本兜底。每个用例预设了可直接运行的 prompt用例行为说明代表性 promptcalculator验证 Gateway 的 Lambda 工具What is 12 75?knowledge验证直连 AWS Knowledge MCP用 2-3 句话解释 DynamoDBbrowser验证网页导航与文本抽取访问某文档页并复述主标题code验证沙箱代码执行Python 计算 1 到 100 平方和memory独立 session 中先写后读先“记住我的名字与偏好语言”3 秒后反问combined单轮内多工具接力先算200*0.125再算0.0000002*1000000注意 memory 用例使用needsSeparateSession: true会生成test-memory-uuid独立会话并在两步之间等待 3 秒以等待持久化完成这正好验证了agents/index.js中 actor/session 维度的记忆隔离逻辑。所有用例结束后脚本打印passed/failed统计任一项失败即以非零码退出便于接入 CI。清理资源serverless remove该命令将一并删除部署阶段创建的 Lambda、Gateway、Memory 与 AgentCore Runtime避免产生不必要的云资源计费。横向参考同一示例族中的能力切片综合示例的价值在于“合”若只想研究单一能力同目录下还有对应的最小化版本链接均已从文档局部相对路径换算为仓库根目录全局路径langgraph-gateway —— 仅 Gateway 工具langgraph-browser —— 仅浏览器langgraph-code-interpreter —— 仅代码解释器langgraph-memory —— 仅记忆langgraph-multi-gateway —— 多种授权方式的多个 Gateway对照阅读时建议顺序为先看单一能力示例理解最小配置再回到本综合示例观察多路工具如何在同一个BedrockAgentCoreApp中合流、如何通过环境变量注入发现各自依赖最终形成“从最小集到全能力”的完整认知。【免费下载链接】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），仅供参考