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（会话持久化）、Browser（Web 自动化）与 Code Interpreter（Python 沙箱执行）承担。
部署方式：两种官方受支持的形态
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
显式指定 Dockerfile：
ai: 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（构建上下文，默认.）、repository（ECR 仓库名）与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 Runtimes）：
python3.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与key，buildArtifact会采用"用户自管理 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: - '*.pyc'package支持patterns、include、exclude与artifact四个子字段。代码部署时如果用户没有指定s3.bucket，Framework 会把代码自动打包上传到部署桶（ServerlessDeploymentBucket），并用package.artifact的 basename 拼出上传 key（见 runtime.js），最终以CodeConfiguration形式编译成 CloudFormation——这个"自动打包"分支就是多数代码部署示例实际走的路径。
网络配置：PUBLIC 与 VPC
ai.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
- 希望网络配置尽量简单
- 正在构建面向公网的 Agent
VPC 模式
将 Agent 部署到 VPC 内部以获得更强安全隔离。
ai: agents: myAgent: network: mode: VPC subnets: - subnet-0123456789abcdef0 - subnet-0123456789abcdef1 securityGroups: - sg-0123456789abcdef0适合使用 VPC 模式的场景：
- Agent 需要访问私有资源（数据库、内部 API）
- 存在网络隔离的合规要求
- 希望管控出口流量
VPC 模式的前提要求：
- 子网必须能经 NAT Gateway 发起外部调用
- 安全组需放行到 AWS 服务的出站 HTTPS（443）
- 可考虑为 AWS 服务配置 VPC Endpoint 以降低流量成本
认证方式：IAM 与 JWT
认证配置位于authorizer，决定谁能调用你的运行时。从 schema 看，Runtime 的authorizer与 Gateway 共用同一结构，支持字符串速记（NONE/AWS_IAM/CUSTOM_JWT，大小写不敏感）或{ type, jwt }对象两种写法（见 schema.js）。需要留意：Runtime 场景实际受支持的是默认 IAM 与CUSTOM_JWT。
默认：AWS IAM（SigV4）
不配置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 端点 URL |
allowedAudience | 否 | 合法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_ARRAY，claimMatchOperator∈EQUALS/CONTAINS/CONTAINS_ANY，匹配值既可用matchValueString（单值）也可用matchValueStringList（多值）。
上述 JWT 配置可以与下方任一部署示例自由组合。
生命周期：会话超时与运行时长上限
会话层面的两个时间参数，直接决定空闲内存的开销与任务最长的存活时间。
ai: agents: myAgent: lifecycle: idleRuntimeSessionTimeout: 900 # 秒（60-28800） maxLifetime: 3600 # 秒（60-28800）| 属性 | 取值范围 | 默认值 | 说明 |
|---|---|---|---|
idleRuntimeSessionTimeout | 60-28800 | 900 | 空闲会话被终止前的秒数 |
maxLifetime | 60-28800 | 28800 | 无论是否活跃，会话的最大存活时长 |
schema 对这两个属性都做了minimum: 60, maximum: 28800的数值约束；编译端buildLifecycleConfiguration只在显式配置时才输出对应 CFN 字段，未配置时交给 AWS 侧默认值（见 runtime.js）。
何时调整这些值：
- 调低
idleRuntimeSessionTimeout：减少空闲期的内存成本（会话存活期间内存按秒计费，即使空闲） - 调高
idleRuntimeSessionTimeout：Agent 需要支撑长会话对话时 - 调低
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 式交互 |
MCP | Model Context Protocol（模型上下文协议） | 通过 MCP 暴露工具的 Agent |
A2A | Agent-to-Agent（Agent 间通信） | 多 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 | 否 | 端点名（省略时自动生成，默认名为default） |
version | 否 | 钉住到某个特定运行时版本（省略则跟踪最新） |
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）建议使用带区域前缀的推理配置档案 ID（inference 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、InvokeModelWithResponseStream） - AWS Marketplace 订阅（自动启用第三方模型）
- X-Ray 追踪与 CloudWatch 指标
- Browser 与 Code Interpreter 访问
条件附加（按配置追加）：
- ECR 镜像拉取（使用容器部署时）
- S3 产物访问（使用自定义 S3 位置时）
- 内存访问（配置了
memory时） - Gateway 调用（配置了
gateway时）
使用已有角色 ARN
ai: 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 | 权限边界策略 ARN |
tags | 应用到角色上的标签 |
statement 结构与 IAM Policy 对齐：每条支持Sid、Effect（Allow/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 两条技术栈，非常适合直接对照本节配置练习：
JavaScript：
- langgraph-basic-dockerfile —— LangGraph + Dockerfile 部署
- langgraph-basic —— LangGraph + 自动构建（buildpack，无需 Dockerfile）
- langgraph-memory —— LangGraph + 会话持久化
- langgraph-streaming —— LangGraph + SSE 流式响应
- mcp-server —— 以 MCP Server 形态部署为 AgentCore 运行时
Python：
- langgraph-basic-docker —— LangGraph + Docker 部署
- langgraph-basic-code —— LangGraph + 代码部署（
handler+runtime） - langgraph-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），仅供参考
