Serverless Framework 实现 LangGraph 多网关 Bedrock AgentCore 代理：基于授权隔离的 NONE / AWS_IAM 双网关实战

Serverless Framework 实现 LangGraph 多网关 Bedrock AgentCore 代理基于授权隔离的 NONE / AWS_IAM 双网关实战【免费下载链接】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 v4 部署 AWS Bedrock AgentCore 的开发者。文中示例 langgraph-multi-gateway 演示了如何在单个 Service 中同时创建NONE公开与AWS_IAM私有两种授权的 AgentCore Gateway并将不同工具子集分配给不同代理使公开用户与内部用户共享一套基础设施、却处于互相隔离的安全边界内。读完本文你将掌握多网关声明式配置、LangGraph 代理对接带鉴权网关的两种 MCP 客户端接入方式以及从部署、验证到清理的完整闭环。这个示例在解决什么问题在真实的 Agent 应用中工具往往具有不同的敏感度计算器、天气查询等可以开放给匿名用户而用户档案查询、数据库写入等则必须要求调用方是经过认证的 AWS Principal。若把所有工具挂在一个入口上要么过度开放、要么给外部用户强加不必要的认证成本。该示例展示的多网关设计用一个 Serverless Frameworkai配置块同时描述多个网关每个网关拥有独立的授权类型与工具子集再让每个 Agent 只关联其对应的网关。这样隔离的好处包括差异化授权级别公开工具与内部工具分别挂在NONE与AWS_IAM网关下工具分片Tool Segmentation不同 Agent 只拿到自己的工具子集不互相暴露清晰的安全边界敏感操作必须经过 IAM 认证才能调用合规诉求不同数据类型可配置独立的访问控制。架构总览示例的完整部署拓扑引自其 README.md如下┌─────────────────────────────────────────────┐ │ AgentCore Service │ ├─────────────────────────────────────────────┤ ┌──────────┐ │ ┌─────────────┐ ┌─────────────────┐ │ │ Public │───────▶│ │Public Agent │─────▶│ Public Gateway │ │ │ User │ │ │ │ │ (auth: NONE) │ │ └──────────┘ │ └─────────────┘ └────────┬────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Calculator │ │ │ │ Lambda │ │ │ └─────────────────┘ │ │ │ ┌──────────┐ │ ┌──────────────┐ ┌─────────────────┐ │ │ Internal │───────▶│ │Private Agent │────▶│ Private Gateway │ │ │ User │ (IAM) │ │ │ │ (auth: AWS_IAM) │ │ └──────────┘ │ └──────────────┘ └────────┬────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Internal Lookup │ │ │ │ Lambda │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────┘两条链路清晰分离Public User → Public Agent → Public Gateway (NONE) → Calculator Lambda与Internal User (IAM) → Private Agent → Private Gateway (AWS_IAM) → Internal Lookup Lambda。从源码结构看Agent 本身是容器化运行由 Dockerfile.public / Dockerfile.private 构建工具则是两个独立的 Lambda 函数通过 Gateway 以 MCP 方式暴露给 Agent。前置条件示例 README.md 列出的准备项如下已开通 Bedrock 模型访问权限的 AWS 账号示例使用 Claude Sonnet 4.5启用美国推理配置档US inference profileus.anthropic.claude-sonnet-4-5-20250929-v1:0本地安装 Docker用于构建 Agent 容器镜像Serverless Framework v4已配置 AWS 凭证aws configure或环境变量均可。一份声明式 serverless.yml工具、网关与代理的分层模型完整的 serverless.yml 以ai顶层块组织三层资源这一结构逻辑与示例 README 的骨架完全对应service: langgraph-multi-gateway provider: name: aws region: us-east-1 functions: calculatorFunction: handler: handlers/calculator.handler runtime: python3.13 internalLookupFunction: handler: handlers/internal_lookup.handler runtime: python3.13 ai: # 定义将被分配到不同网关的工具 tools: calculator: function: calculatorFunction toolSchema: - name: calculate description: Evaluate a mathematical expression. Supports basic arithmetic and functions like sqrt, sin, cos. inputSchema: type: object properties: expression: type: string description: Mathematical expression to evaluate (e.g., 2 2 * 3, sqrt(16)) required: - expression internalLookup: function: internalLookupFunction toolSchema: - name: lookup_user description: Look up internal user information by user ID. Returns name, email, and department. inputSchema: type: object properties: userId: type: string description: The user ID to look up (e.g., USR001) required: - userId # 定义多个具有不同授权的网关 gateways: # 公开网关 —— 无需认证仅用于不访问敏感数据的工具 publicGateway: authorizer: NONE tools: - calculator # 私有网关 —— 需要 AWS IAM 认证用于访问内部/敏感数据的工具 privateGateway: authorizer: AWS_IAM tools: - internalLookup # 公开代理 —— 使用公开网关含计算器工具无需额外 IAM 权限即可调用 agents: publicAgent: artifact: image: file: Dockerfile.public gateway: publicGateway # 私有代理 —— 使用私有网关含内部查询工具工具调用要求 AWS IAM 认证 privateAgent: artifact: image: file: Dockerfile.private gateway: privateGateway三个层次的职责拆解ai.tools把 Lambda 函数包装成带 JSON Schema 描述的工具。每个工具通过function指向 functions 中定义的处理器toolSchema里的name、description、inputSchema会作为模型调用该函数时的结构化契约这也是模型决定何时调用、传什么参数的依据注释越精确、模型决策越稳定。ai.gateways网关是工具暴露给外部含 Agent的端口authorizer决定谁能调用其下的工具。同一个工具可以只归属一个网关本示例刻意把calculator与internalLookup拆到两个网关避免公开工具与内部工具混用入口。ai.agents代理由容器镜像构建通过artifact.image.file指向本地 Dockerfile并通过gateway字段绑定到唯一网关。示例 README 明确说明一次serverless deploy会产出两个 Lambda、两个网关与两个代理。Gateway 授权类型速查类型适用场景典型示例NONE公开工具无需认证计算器、天气查询AWS_IAM内部工具要求调用方具备 IAM 权限用户信息查询、数据库访问CUSTOM_JWT经由第三方签发的 JWT 做认证由 OAuth 保护的 APICUSTOM_JWT 网关示例当需要把工具暴露给携带外部身份令牌如 Cognito 用户池签发的 JWT的调用方时README 给出了如下结构ai: gateways: jwtGateway: authorizer: type: CUSTOM_JWT jwt: discoveryUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx/.well-known/openid-configuration allowedAudience: - my-client-id allowedScopes: - openid tools: [protectedTool]discoveryUrl指向 OIDC 发现端点供网关校验令牌签名allowedAudience声明可接受的 audienceallowedScopes限定令牌所需 scope——三者共同决定了谁的令牌能通过。两种鉴权模式下的 Agent 接入HTTP 直连与 SigV4 签名示例最有价值的对比在于两个 Agent 的 Python 实现只差一行客户端选择却对应了完全不同的鉴权路径。公开代理无需认证的 streamablehttp_clientpublic_agent.py 针对NONE网关使用普通的streamablehttp_clientfrom mcp.client.streamable_http import streamablehttp_client from mcp import ClientSession from langchain_mcp_adapters.tools import load_mcp_tools GATEWAY_URL os.environ.get(BEDROCK_AGENTCORE_GATEWAY_URL) async with streamablehttp_client(urlGATEWAY_URL) as (read, write, session_id_callback): async with ClientSession(read, write) as session: await session.initialize() tools await load_mcp_tools(session) # 将 MCP 工具转成 LangChain 工具 llm_with_tools llm.bind_tools(tools)工作链路为通过 MCP 握手从网关动态发现calculate工具 → 绑定到 LLM → 构建带ToolNode与tools_condition的 LangGraph 状态机 → 模型自主决策调用工具完成计算。若环境变量BEDROCK_AGENTCORE_GATEWAY_URL未配置代码会退化为不带工具的纯聊天图见同文件 run_agent_with_gateway 的 fallback 分支方便本地调试。私有代理SigV4 签名的 mcp-proxy-for-awsprivate_agent.py 针对AWS_IAM网关换成mcp-proxy-for-aws提供的客户端为每个请求附加 AWS SigV4 签名from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client GATEWAY_URL os.environ.get(BEDROCK_AGENTCORE_GATEWAY_URL) AWS_REGION os.environ.get(AWS_REGION, us-east-1) mcp_client aws_iam_streamablehttp_client( endpointGATEWAY_URL, aws_regionAWS_REGION, aws_servicebedrock-agentcore ) async with mcp_client as (read, write, session_id_callback): # 之后与公开代理完全相同ClientSession → load_mcp_tools → 构图执行 ...两版 Agent 的其余部分State定义、chatbot_node、ToolNode/tools_condition构图、app.entrypoint入口完全一致差异被收敛在用什么 MCP 传输客户端这一处——这正是把鉴权收敛到网关层带来的收益应用代码几乎不用感知安全实现。两个镜像的 Dockerfile 同样只有一行CMD不同python public_agent.pyvspython private_agent.py依赖统一收敛在 pyproject.toml 中其中除 LangGraph/LangChain 生态外重点包括运行时框架bedrock-agentcore1.3.0与用于 SigV4 的mcp-proxy-for-aws1.1.5。两个工具函数的实现要点calculator用 AST 白名单做安全求值handlers/calculator.py 没有使用eval而是先ast.parse(expression, modeeval)解析表达式再用自定义求值器递归遍历 AST只放行白名单内的运算符、函数与常量OPERATORS { ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Pow: operator.pow, ast.Mod: operator.mod, ast.USub: operator.neg, ast.UAdd: operator.pos, } FUNCTIONS { sqrt: math.sqrt, sin: math.sin, cos: math.cos, log: math.log, ... }输入既支持直接 JSON也兼容网关包裹的{body: {...}}形式两版 handler 均做了该容错见 calculator handler。这保证了表达式sqrt(144) 10这类自然语言诉求能被模型正确翻译为{expression: sqrt(144) 10}并安全执行。任何未知函数、变量或操作符都会抛出ValueError并被 handler 捕获返回 400。internal_lookup模拟受保护的企业数据服务handlers/internal_lookup.py 内置了仅含 4 条记录的模拟用户库USR001~USR004含姓名、邮箱、部门、角色等字段按userId返回用户信息找不到时返回 404 并附上availableUsers便于排查。其 docstring 明确指出该工具通过网关的AWS_IAM授权保护确保只有经过认证的调用方才可访问内部数据。生产环境中这里应替换为对内部数据库或内部 API 的真实查询。从部署到验证的完整操作闭环1. 部署serverless deploy一次部署即创建两个 Lambda 函数、两个网关与两个 Agent构建镜像需本地 Docker 就绪。若需要查看运行时 ARN 等输出信息可使用serverless info2. 验证公开代理calculator 工具使用 boto3 调用bedrock-agentcore的运行时接口README 中的核心用法import boto3 import json import uuid client boto3.client(bedrock-agentcore, region_nameus-east-1) response client.invoke_agent_runtime( agentRuntimeArnYOUR_PUBLIC_AGENT_ARN, # 部署输出 / serverless info 获取 runtimeSessionIdstr(uuid.uuid4()), # 每次调用传入新会话 ID payloadjson.dumps({prompt: What is sqrt(144) 10?}).encode() ) print(json.loads(response[response].read()))3. 验证私有代理internal_lookup 工具response client.invoke_agent_runtime( agentRuntimeArnYOUR_PRIVATE_AGENT_ARN, # 私有代理的运行时 ARN runtimeSessionIdstr(uuid.uuid4()), payloadjson.dumps({prompt: Look up user USR001 and tell me their department}).encode() ) print(json.loads(response[response].read()))4. 一键联测仓库自带的 test-invoke.py除手工调用外示例还提供了现成的 test-invoke.py通过环境变量注入运行时 ARN 即可分代理批量测试其 docstring 已给出完整用法# 只测公开代理计算器类题目 PUBLIC_RUNTIME_ARNarn:aws:bedrock-agentcore:... python3 test-invoke.py public # 只测私有代理用户查询类题目 PRIVATE_RUNTIME_ARNarn:aws:bedrock-agentcore:... python3 test-invoke.py private # 同时测试两者 PUBLIC_RUNTIME_ARN... PRIVATE_RUNTIME_ARN... python3 test-invoke.py该脚本对两类响应形态做了兼容text/event-stream流式响应会逐行解析data:前缀application/json响应则按 chunk 拼接后json.loads方便直接观察模型调用工具后的最终结论。ARN 未设置时会跳过对应测试而非报错便于分阶段验证。5. 清理资源serverless remove移除整个 Service 下由本次部署创建的 Lambda、网关与 Agent避免持续产生费用。安全最佳实践综合 README 的建议与本例的实现多网关架构落地时应遵守内部工具一律使用AWS_IAM只有经过认证的 AWS Principal 才能调用私有代理通过 SigV4 签名自动满足这一要求按敏感度切分工具不要把公开与私有工具塞进同一个网关否则等于在边界上开了口子最小权限每个 Agent 只获得其任务所需的工具子集——本例公开代理永远无法触达lookup_user可观测借助 CloudWatch Logs 追踪各网关的工具调用记录示例中两版 handler 与 Agent 都保留了关键路径的print日志正是为配合该实践。示例文件清单文件用途serverless.yml声明多网关、多工具与多代理的基础设施public_agent.py走公开网关NONE的 LangGraph 代理private_agent.py走私有网关AWS_IAM的 LangGraph 代理handlers/calculator.py公开的计算器工具AST 安全求值handlers/internal_lookup.py私有的内部用户查询工具Dockerfile.public公开代理容器镜像Dockerfile.private私有代理容器镜像pyproject.tomlPython 依赖bedrock-agentcore、langgraph、mcp-proxy-for-aws 等test-invoke.py一键联测公开/私有代理的脚本下一步进阶方向如果你希望从更简单的形态逐步理解或在本例基础上继续增强可直接对照同目录下的相邻示例继续阅读单网关基础形态langgraph-gateway —— 先掌握一个 Agent 一个网关的最小闭环再对比本示例的双网关差异对话持久化langgraph-memory —— 在网关与工具之上叠加会话记忆能力。整套示例位于 examples/python 目录 下可作为后续扩展如为同一工具同时开放公开与私有入口、接入更多CUSTOM_JWT身份源的参照起点。【免费下载链接】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），仅供参考