Serverless Framework AgentCore 运行时配置完全指南从部署到认证的ai.agents深度解析【免费下载链接】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本指南以 Runtime Configuration 文档 为骨架系统讲解如何在 Serverless Framework v4 中配置 AWS Bedrock AgentCore 的Runtime运行时——即承载你 AI Agent 业务逻辑的容器或 Python 代码。你将掌握两种部署方式Docker/镜像与纯 Python 代码、网络模式、JWT 认证、会话生命周期、协议选择、命名端点、环境变量注入以及 IAM 角色定制等完整配置能力并了解 Framework 如何在serverless deploy时把这些配置编译为AWS::BedrockAgentCore::Runtime与AWS::BedrockAgentCore::RuntimeEndpoint等 CloudFormation 资源。在 Serverless Framework 的 AI Agent 体系中Runtime 是最核心的组成部分——它是你真正运行 Agent 逻辑的那个进程。在serverless.yml的顶层ai配置块中每个ai.agents下的键名都对应一个 Runtime 资源。Framework 负责为你构建、打包并部署该运行时到 AWS Bedrock AgentCore代码层面你几乎可以使用任何 Agent 框架——LangGraph、Strands Agents、CrewAI或完全自定义的编排代码。其余配套组件则分别由 Gateway把 Lambda/API/MCP 转成 Agent 工具、Memory会话持久化、BrowserWeb 自动化与 Code InterpreterPython 沙箱执行承担。部署方式两种官方受支持的形态AgentCore Runtime 支持两种部署形态Docker/镜像部署任意语言与代码部署仅 Python。配置中如何选择由artifact与handler属性驱动这一点可以在源码中得到直接印证ai.agents的 schema见 schema.js同时接受artifact.image、artifact.s3与根级handler/runtime而编译逻辑见 compilers/runtime.js在buildArtifact内部按优先级依次识别这三种形态并映射到 CloudFormation 的ContainerConfiguration或CodeConfiguration。Docker/Image 部署多语言Docker 适合多语言项目、复杂依赖、或需要完全掌控运行环境的场景。最小配置自动探测ai: agents: myAgent: {}当配置为空对象时Framework 会在当前目录自动探测Dockerfile并自动完成四件事构建 Docker 镜像创建 ECR 仓库推送镜像到 ECR部署到 AgentCore显式指定 Dockerfileai: agents: myAgent: artifact: image: file: Dockerfile.agent # 自定义 Dockerfile 文件名 path: ./agent # 构建上下文目录 repository: my-agent-repo # 自定义 ECR 仓库名 buildArgs: # Docker 构建参数 PYTHON_VERSION: 3.12 ENV: productionimage为对象形式时schema 中的可选子字段包括file默认Dockerfile、path构建上下文默认.、repositoryECR 仓库名与buildArgs键值均为字符串。从 schema.js 可见它甚至还支持builder字段用于指定 Buildpack 构建器镜像。使用预构建镜像ai: agents: myAgent: artifact: image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest当artifact.image是字符串而非对象时buildArtifact会直接把它当作镜像 URI 编译为ContainerConfiguration.ContainerUri不会触发任何本地构建流程。此时 Framework 只做引用若镜像位于他人账号的 ECR会由 IAM 层面按解析出的仓库 ARN 授予拉取权限见 iam/policies.js它从{account}.dkr.ecr.{region}.amazonaws.com/{repo}形式的 URI 中解析出精确的 ECR 仓库 ARN解析失败才退化为通配 ARN。预构建镜像适合以下场景已有独立的镜像构建 CI/CD 流水线希望镜像在多个服务间共享需要使用其他 AWS 账号中的镜像代码部署仅 Python不经过 Docker直接把 Python 代码部署上去。适合依赖标准、结构简单的 Agent迭代更快。基础代码部署ai: agents: myAgent: handler: agent.py runtime: python3.12出现handler属性即触发代码部署模式Framework 会打包你的 Python 代码并上传到 S3。底层编译时代码部署的EntryPoint会取artifact.entryPoint || [main.py]handler: agent.py在解析阶段被归一化为 entryPoint而Runtime默认值为PYTHON_3_13。支持的 Python 运行时来自 schema 的SUPPORTED_AGENT_RUNTIMES常量见 schema.js也即 AgentCore 的 Managed Runtimespython3.10python3.11python3.12python3.13默认python3.14需要说明的是原文档只列出前四项并以python3.13为默认从当前仓库 schema 常量看代码层面同时放开了python3.14的校验比较时大小写不敏感例如Python3.13也能通过。具体能否使用请以 AWS 账号实际开放的受管运行时为准。自定义 S3 位置ai: agents: myAgent: handler: main.py runtime: python3.12 artifact: s3: bucket: my-artifacts-bucket key: agents/my-agent.zip versionId: abc123 # 可选指定具体版本一旦同时给出artifact.s3.bucket与keybuildArtifact会采用用户自管理 S3分支直接引用你提供的桶、前缀Prefix取s3.key并在提供versionId时附带VersionId见 runtime.js。注意这里的s3与下面要讲的代码自动打包互斥。自定义 S3 位置适合以下场景已有预打包好的 Agent 代码希望把产物与部署过程分开管理生产环境需要版本固定version pinning打包选项代码部署模式下的文件选择控制与 Lambda 函数打包 完全一致ai: agents: myAgent: handler: agent.py package: patterns: - !tests/** - !docs/** include: - lib/** exclude: - *.pycpackage支持patterns、include、exclude与artifact四个子字段。代码部署时如果用户没有指定s3.bucketFramework 会把代码自动打包上传到部署桶ServerlessDeploymentBucket并用package.artifact的 basename 拼出上传 key见 runtime.js最终以CodeConfiguration形式编译成 CloudFormation——这个自动打包分支就是多数代码部署示例实际走的路径。网络配置PUBLIC 与 VPCai.agents.name.network控制运行时如何接入网络。schema 采用扁平化结构mode 可选的subnets、securityGroups见 schema.js。编译端buildNetworkConfiguration会把mode归一化为大写默认PUBLIC并在VPC模式下把subnets、securityGroups组装进NetworkModeConfig见 runtime.js。PUBLIC 模式默认Agent 通过互联网访问并由 AWS 认证保护。ai: agents: myAgent: network: mode: PUBLIC适合使用 PUBLIC 模式的场景Agent 需要调用外部 API希望网络配置尽量简单正在构建面向公网的 AgentVPC 模式将 Agent 部署到 VPC 内部以获得更强安全隔离。ai: agents: myAgent: network: mode: VPC subnets: - subnet-0123456789abcdef0 - subnet-0123456789abcdef1 securityGroups: - sg-0123456789abcdef0适合使用 VPC 模式的场景Agent 需要访问私有资源数据库、内部 API存在网络隔离的合规要求希望管控出口流量VPC 模式的前提要求子网必须能经 NAT Gateway 发起外部调用安全组需放行到 AWS 服务的出站 HTTPS443可考虑为 AWS 服务配置 VPC Endpoint 以降低流量成本认证方式IAM 与 JWT认证配置位于authorizer决定谁能调用你的运行时。从 schema 看Runtime 的authorizer与 Gateway 共用同一结构支持字符串速记NONE/AWS_IAM/CUSTOM_JWT大小写不敏感或{ type, jwt }对象两种写法见 schema.js。需要留意Runtime 场景实际受支持的是默认 IAM 与CUSTOM_JWT。默认AWS IAMSigV4不配置authorizer时运行时使用 AWS SigV4 认证——调用方必须持有有效的 AWS 凭证并具备相应 IAM 权限。ai: agents: myAgent: {} # 默认即使用 AWS IAMJWT 认证用来自 OIDC 兼容身份提供方Cognito、Auth0、Okta 等的 JWT 令牌保护运行时。ai: agents: myAgent: authorizer: type: CUSTOM_JWT jwt: discoveryUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxx/.well-known/openid-configuration allowedAudience: - my-app-client-id allowedClients: - my-app-client-id allowedScopes: - openid - profileJWT 配置选项属性必填说明discoveryUrl是OIDC discovery 端点 URLallowedAudience否合法aud声明取值列表allowedClients否合法client_id取值列表allowedScopes否需要校验的 scope 列表customClaims否自定义声明校验规则编译端buildAuthorizerConfiguration要求jwt.discoveryUrl必须存在否则直接抛错JWT authorizer requires discoveryUrl并把上述字段映射为 CloudFormation 的CustomJWTAuthorizer见 runtime.js。schema 对discoveryUrl还要求匹配^./.well-known/openid-configuration$结尾。自定义声明校验ai: agents: myAgent: authorizer: type: CUSTOM_JWT jwt: discoveryUrl: https://.../.well-known/openid-configuration customClaims: - inboundTokenClaimName: department inboundTokenClaimValueType: STRING authorizingClaimMatchValue: claimMatchOperator: EQUALS claimMatchValue: matchValueString: engineeringcustomClaims在编译前会经过 utils/authorizer.js 的transformCustomClaims把 camelCase 的 user-friendly 配置逐字段转成 CloudFormation 需要的 PascalCase 结构。schema 中合法取值为inboundTokenClaimValueType∈STRING/STRING_ARRAYclaimMatchOperator∈EQUALS/CONTAINS/CONTAINS_ANY匹配值既可用matchValueString单值也可用matchValueStringList多值。上述 JWT 配置可以与下方任一部署示例自由组合。生命周期会话超时与运行时长上限会话层面的两个时间参数直接决定空闲内存的开销与任务最长的存活时间。ai: agents: myAgent: lifecycle: idleRuntimeSessionTimeout: 900 # 秒60-28800 maxLifetime: 3600 # 秒60-28800属性取值范围默认值说明idleRuntimeSessionTimeout60-28800900空闲会话被终止前的秒数maxLifetime60-2880028800无论是否活跃会话的最大存活时长schema 对这两个属性都做了minimum: 60, maximum: 28800的数值约束编译端buildLifecycleConfiguration只在显式配置时才输出对应 CFN 字段未配置时交给 AWS 侧默认值见 runtime.js。何时调整这些值调低idleRuntimeSessionTimeout减少空闲期的内存成本会话存活期间内存按秒计费即使空闲调高idleRuntimeSessionTimeoutAgent 需要支撑长会话对话时调低maxLifetime安全敏感型应用需要定期轮换会话调高maxLifetime需要长时间运行的批处理或分析任务协议配置HTTP、MCP 与 A2A通过protocol声明运行时的对外通信协议。在serverless.yml里可以写字符串protocol: HTTP编译端也兼容对象写法{ type: MCP }最终统一归为大写字符串作为 CFN 的ProtocolConfiguration见 runtime.js。ai: agents: myAgent: protocol: HTTP # HTTP、MCP 或 A2A协议说明适用场景HTTP标准 HTTP 请求默认通用 Agent、REST 式交互MCPModel Context Protocol模型上下文协议通过 MCP 暴露工具的 AgentA2AAgent-to-AgentAgent 间通信多 Agent 编排Runtime 的protocol是纯枚举HTTP/MCP/A2A与 Gateway 侧结构化的protocolSchema含instructions、supportedVersions、searchType等扩展项是两套不同 schema注意不要混淆。仓库中另有一个现成的 MCP 形态示例可供对照examples/javascript/mcp-server配置见 serverless.yml。命名端点Endpoints版本化访问入口端点用于管理带版本的访问入口——例如 production 端点始终跟踪最新版本staging 端点钉住某个特定版本。ai: agents: myAgent: endpoints: - name: production description: Production endpoint, always tracks latest - name: staging version: 1 description: Staging endpoint pinned to version 1属性必填说明name否端点名省略时自动生成默认名为defaultversion否钉住到某个特定运行时版本省略则跟踪最新description否人类可读的描述最长 256 字符每个端点都会编译成一个独立的AWS::BedrockAgentCore::RuntimeEndpointCloudFormation 资源拥有自己的 ARN并作为 Stack Output 暴露。从 compilers/runtimeEndpoint.js 可以看到实现细节该资源通过DependsOn指向 Runtime 逻辑 ID并用Fn::GetAtt把 Runtime 的AgentRuntimeId注入AgentRuntimeId属性提供config.version时映射为AgentRuntimeVersion。环境变量注入通过environment给运行时传配置。值必须全部是字符串。ai: agents: myAgent: environment: MODEL_ID: us.anthropic.claude-sonnet-4-5-20250929-v1:0 LOG_LEVEL: INFO MAX_TOKENS: 4096 API_ENDPOINT: https://api.example.com最佳实践按需模型on-demand建议使用带区域前缀的推理配置档案 IDinference profile ID例如us.anthropic.claude-sonnet-...形态密钥请放进 AWS Secrets Manager 或 Parameter Store不要写入环境变量Framework 底层会自动把 memory ID、gateway URL 等内部引用注入 Agent 环境上限环境变量最多50 个部署时由 AWS 强制校验CloudFormation 侧EnvironmentVariables定义为maxProperties: 50请求头透传Request Headers控制哪些 HTTP 请求头会透传给运行时。这一机制对分布式追踪、自定义认证与请求关联很有价值。ai: agents: myAgent: requestHeaders: allowlist: - X-Trace-Id - X-Request-Id - X-Correlation-Id典型用途分布式追踪传递 trace ID自定义认证透传附加令牌跨服务请求关联correlation限制allowlist 最多20 个请求头schema 中minItems: 1, maxItems: 20。编译端buildRequestHeaderConfiguration把 allowlist 直接映射为 CFN 的RequestHeaderAllowlist见 runtime.js。IAM 角色配置Framework 默认会自动创建执行角色并附带所需权限你也可以用已有角色或在此之上追加权限。自动生成角色默认ai: agents: myAgent: {} # 角色自动创建角色生成策略可以在 iam/policies.js 的shouldGenerateRole中看到完全省略role或role是带statements/managedPolicies的定制对象时Framework 都会生成角色而role为字符串 ARN 或 CF 内建函数对象时则直接复用不再生成。自动生成的角色权限分为两层始终包含CloudWatch Logs创建日志组、写日志Bedrock 模型调用InvokeModel、InvokeModelWithResponseStreamAWS Marketplace 订阅自动启用第三方模型X-Ray 追踪与 CloudWatch 指标Browser 与 Code Interpreter 访问条件附加按配置追加ECR 镜像拉取使用容器部署时S3 产物访问使用自定义 S3 位置时内存访问配置了memory时Gateway 调用配置了gateway时使用已有角色 ARNai: agents: myAgent: role: arn:aws:iam::123456789012:role/MyCustomAgentRole角色定制在自动生成角色上追加权限ai: agents: myAgent: role: name: my-agent-role # 可选自定义角色名 statements: - Effect: Allow Action: - s3:GetObject - s3:PutObject Resource: arn:aws:s3:::my-bucket/* - Effect: Allow Action: secretsmanager:GetSecretValue Resource: arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-* managedPolicies: - arn:aws:iam::aws:policy/AmazonDynamoDBReadOnlyAccess permissionsBoundary: arn:aws:iam::123456789012:policy/MyPermissionsBoundary tags: CostCenter: AI-Team属性说明name自定义角色名最长 64 字符statements追加的 IAM policy statement 数组managedPolicies要附加的托管策略 ARN 列表permissionsBoundary权限边界策略 ARNtags应用到角色上的标签statement 结构与 IAM Policy 对齐每条支持Sid、EffectAllow/Deny、Action/NotAction字符串或数组、Resource/NotResource、Condition等字段且Effect必填见 schema.js。标签与描述为运行时附加元数据便于组织管理与成本追踪。ai: agents: myAgent: description: Production customer service agent with memory and tools tags: Team: AI Project: CustomerService Environment: production CostCenter: CC-1234属性限制说明description最长 1200 字符人类可读的描述tags遵循标准 AWS 标签限制用于资源打标的键值对description的minLength: 1, maxLength: 1200约束直接出现在runtimeAgentSchema中CFN 注释同样标明Description: string, maxLength: 1200。完整配置参考把所有选项组合起来一份全量示例长这样注意memory 与 gateway 的具体语义见各自的专题文档这里仅展示它们如何挂载到 Runtime 上service: my-ai-service provider: name: aws region: us-east-1 ai: agents: myAgent: # Description description: Production AI agent with full configuration # Deployment (choose one approach) artifact: image: file: Dockerfile path: ./agent repository: my-agent-repo buildArgs: ENV: production # OR for code deployment: # handler: agent.py # runtime: python3.12 # Protocol protocol: HTTP # Endpoints (named access points for the runtime) endpoints: - name: production description: Tracks latest version - name: staging version: 1 description: Pinned to version 1 # Networking network: mode: PUBLIC # For VPC: # mode: VPC # subnets: [subnet-xxx] # securityGroups: [sg-xxx] # Authentication 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 allowedClients: - my-client-id # Lifecycle lifecycle: idleRuntimeSessionTimeout: 900 maxLifetime: 3600 # Environment environment: MODEL_ID: us.anthropic.claude-sonnet-4-5-20250929-v1:0 LOG_LEVEL: INFO # Headers requestHeaders: allowlist: - X-Trace-Id # Memory - enables conversation persistence (see memory.md) # Automatically adds memory read/write permissions to the runtime role memory: myMemory # Gateway - connects tools to your agent (see gateway.md) # Automatically adds gateway invocation permissions to the runtime role gateway: myGateway # IAM Role role: statements: - Effect: Allow Action: s3:GetObject Resource: arn:aws:s3:::my-bucket/* # Metadata tags: Team: AI Environment: production从配置到部署编译链路的快速对照理解 Framework 如何消费上述配置有助于排查问题。整条链路大致是Schema 校验defineAgentsSchema通过 schema.js 注册顶层ai属性ai.agents.name使用runtimeAgentSchema逐字段校验非法枚举、越界数值在部署前就会被拦截比较对大小写不敏感。资源编译每个 agent 经 compileRuntime 编译为一个AWS::BedrockAgentCore::Runtime每声明一个端点则额外产生一个AWS::BedrockAgentCore::RuntimeEndpoint二者由编译编排器 compilation/orchestrator.js 统一调度。权限组装自动生成的 IAM 角色按部署方式与是否挂载 memory/gateway 等条件追加最小权限 statement。动手验证仓库内的可运行示例本仓库在packages/serverless/lib/plugins/aws/bedrock-agentcore/examples下自带一整套可部署示例分别覆盖 JavaScript 与 Python 两条技术栈非常适合直接对照本节配置练习JavaScriptlanggraph-basic-dockerfile —— LangGraph Dockerfile 部署langgraph-basic —— LangGraph 自动构建buildpack无需 Dockerfilelanggraph-memory —— LangGraph 会话持久化langgraph-streaming —— LangGraph SSE 流式响应mcp-server —— 以 MCP Server 形态部署为 AgentCore 运行时Pythonlanggraph-basic-docker —— LangGraph Docker 部署langgraph-basic-code —— LangGraph 代码部署handlerruntimelanggraph-memory —— LangGraph 会话持久化每个示例目录都自带serverless.yml与入口代码index.js/agent.py多数还配有test-invoke脚本可直接用serverless deploy上线并用serverless invoke --agent name验证。部署与调试命令速查完整的上线、调用与排障命令可参考 AI Agents 快速上手文档其要点包括# 部署自动完成镜像构建/代码打包与资源编排 serverless deploy # 本地开发模式Docker 中运行 热重载 交互式聊天 CLI serverless dev # 调用已部署 Agent支持 --data / --path / --session-id serverless invoke --agent myAgent --data {prompt: Hello!} # 查看与实时跟踪日志支持 --tail / --startTime / --filter / --interval serverless logs --agent myAgent serverless logs --agent myAgent --tail总结Runtime 配置的核心是把你的 Agent 代码 部署方式翻译成 AWS Bedrock AgentCore 能托管的基础设施部署上分清 Docker/镜像、纯代码与自动打包三种形态网络与认证决定了谁能访问以及如何访问生命周期、环境变量与请求头透传负责运行态行为命名端点与 IAM 角色定制则分别解决版本化入口和最小权限问题。结合 runtime.md 原文、编译实现compilers/runtime.js、配置校验validators/schema.js与开箱即用的示例你就能在 Serverless Framework 中稳定落地生产级 AI Agent。延伸阅读配置好 Runtime 之后下一步通常是给它接上工具网关Gateway、开启会话记忆Memory或是挂载 Browser 工具 与 Code Interpreter日常开发则可配合本地开发模式Dev Mode实现热重载调试。【免费下载链接】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），仅供参考