企业官网建设流程全解析

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 Framework（AWS 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 的多种能力，而非把每项能力拆成独立工程。对应到示例目录，其能力清单如下：

除了以上功能点，示例还体现了 AgentCore 的目录组织约定——业务 Agent 代码放在agents/子目录、Lambda handler 放在handlers/子目录。示例完整文件清单见下表，与源码目录examples/javascript/langgraph-comprehensive/一一对应：

架构：从用户请求到多路工具调度

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。六路工具按来源可分为三类：

1. 经由 Gateway 的工具：calculator Lambda，通过BEDROCK_AGENTCORE_GATEWAY_URL环境变量以 MCP 协议 + SigV4 签名发现；
2. 智能体直连的工具：AWS Knowledge MCP（https://knowledge-mcp.global.api.aws），公共端点、无需网关与认证；
3. 进程内封装的工具：浏览器（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的默认值）；
• 本机安装 Docker；
• Serverless Framework v4+（即本仓库packages/serverless对应的 CLI 版本）；
• 已配置 AWS 凭证。

1. 部署

serverless deploy

框架在此过程中会自动完成（对应 README 描述并经插件源码佐证）：从源码自动构建 Docker 镜像（无需 Dockerfile）→ 推送至 Amazon ECR → 部署 Calculator Lambda 函数 → 创建带 calculator 工具的 AgentCore Gateway → 创建 AgentCore Memory（30 天过期）→ 部署 AgentCore Runtime。

2. 端到端测试

RUNTIME_ARN=<your-runtime-arn> node test-invoke.js

RUNTIME_ARN从serverless info输出中获取。同时示例还给出了更轻量的交互入口：

serverless invoke -a assistant -d "Hello"

3. 本地开发

serverless dev

配置详解：serverless.yml中的 AI 编排

示例serverless.yml的ai:配置块是 AgentCore 能力编排的核心语法，完整内容见 serverless.yml：

service: 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 Lambda（Node.js 24 运行时），handler 指向handlers/calculator.handler。它并不直接暴露给用户，而是作为工具被 AI 网关代理；
• ai.tools.calculator：定义一个名为calculator的 AI 工具，其类型为 Lambda 函数工具，靠toolSchema描述给 LLM 看的结构化入参。校验实现（validators/schema.js）说明该层合法来源包括function（须带toolSchema）与mcp（MCP 服务端点）两类；
• 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.tools+sharedTools引用模型的应用场景。

工具来源逐路拆解：agents/index.js实现剖析

Agent 主逻辑约 500 行，位于 agents/index.js，其顶部注释与代码共同描述了三条由框架自动注入的环境变量：

• BEDROCK_AGENTCORE_GATEWAY_URL：Gateway 工具的 MCP 端点；
• BEDROCK_AGENTCORE_MEMORY_ID：记忆持久化标识；
• AWS_REGION：AWS 区域。

1. Gateway 工具（Calculator Lambda）

loadGatewayTools()的完整链路为：

1. 读取BEDROCK_AGENTCORE_GATEWAY_URL，未配置则跳过（不影响其他工具加载）；
2. 通过@aws-sdk/credential-provider-node的defaultProvider取得临时凭证；
3. 用aws4fetch的AwsV4Signer构造签名 fetch，服务名bedrock-agentcore；
4. 以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. 直连 MCP：AWS Knowledge

loadKnowledgeMcpTools()演示了“无认证公共 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：跳转 URL，waitUntil: 'domcontentloaded'；
• browser_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、typescript（zod enum 约束），缺省 python；
• execute_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-<prefix>，sessionId缺省为'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_ARN=<your-runtime-arn> node test-invoke.js # 全部用例 RUNTIME_ARN=<arn> node test-invoke.js calculator # 单项工具 RUNTIME_ARN=<arn> node test-invoke.js knowledge RUNTIME_ARN=<arn> node test-invoke.js browser RUNTIME_ARN=<arn> node test-invoke.js code RUNTIME_ARN=<arn> node test-invoke.js memory RUNTIME_ARN=<arn> node test-invoke.js combined

测试内部通过InvokeAgentRuntimeCommand调用 Runtime ARN，payload 为{ prompt }JSON；accept: 'text/event-stream, application/json'优先请求 SSE 流式响应。脚本实现了两层鲁棒解析：readResponseStream兼容 Buffer、Uint8Array 与嵌套{chunk:{bytes}}的多种流形态；extractResponse依次处理 SSE（data:行、[DONE]）、JSON（result/error字段）与纯文本兜底。每个用例预设了可直接运行的 prompt：

注意 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