Serverless Framework 部署 AgentCore Runtime 时 Docker 镜像部署与 Python 代码部署怎么选？

Serverless Framework 部署 AgentCore Runtime 时 Docker 镜像部署与 Python 代码部署怎么选？

【免费下载链接】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 把一个 AI Agent 部署到 AWS Bedrock AgentCore 时，serverless.yml里的ai.agents配置决定了走哪条部署路径：Docker/Image 部署（支持任意语言）或Code 部署（仅 Python）。两者部署命令完全相同（都是serverless deploy），但配置写法、依赖管理方式、前置条件和 IAM 权限都不同，选错会导致部署失败或白装依赖。这篇文章基于仓库中的 Runtime Configuration 文档、AI Agents 指南 和两个可直接运行的 Python 示例（Docker 部署示例、代码部署示例），给出两者的选择依据和完整配置。

适用的前提（来自文档 Prerequisites 一节）：

• AWS 账号，并已开通所需 Bedrock 模型的访问权限（示例中使用的是 US 推理 profileus.anthropic.claude-sonnet-4-5-20250929-v1:0）；
• Serverless Framework v4+；
• AWS 凭证已配置；
• 仅走 Docker/Image 路径时需要本地安装 Docker（含 auto-build 模式）；JavaScript 项目还需 Node.js 20+。

先弄清两种方式的机制差异

IAM 角色方面，框架会自动创建角色并按部署方式追加权限：使用容器部署时自动加入 ECR 镜像拉取权限；使用自定义 S3 位置时自动加入 S3 制品访问权限。也就是说两条路径的权限差异由框架处理，不需要手动补。

按什么条件选

文档对两条路径各自给出了明确的适用场景，直接对应你的项目特征：

选 Docker/Image 部署，当：

• 项目不是 Python（这是 Code 部署不支持的硬性边界，Code 部署仅限 Python）；
• 依赖复杂，或需要完全控制运行时环境（多语言项目、复杂依赖）；
• 已有 CI/CD 流水线构建镜像、需要跨服务共享镜像、或使用其他 AWS 账号的镜像——这三种情况用"预构建镜像"方式，见下文。

选 Code 部署，当：

• 就是简单的 Python agent，依赖是标准 PyPI 包（simple agents with standard dependencies）；
• 希望迭代更快，不想维护 Dockerfile。

两种方式的官方示例 README 还有一张对比表，结论一致：

一句话判断：非 Python 或环境特殊就 Docker；Python + 标准依赖 + 想快速迭代就 Code。

路径 A：Docker 镜像部署

最小配置（Dockerfile 自动检测）

serverless.yml：

service: my-ai-service provider: name: aws region: us-east-1 ai: agents: myAgent: {}

注意 YAML 要求空配置必须写显式空花括号{}。框架会自动检测当前目录的Dockerfile，然后依次完成：构建镜像、创建 ECR 仓库、推送镜像、部署 AgentCore。仓库中的 Docker 示例就是这个最小配置，配合一个标准 Dockerfile（Python 3.12 slim 基础镜像、从pyproject.toml安装依赖、CMD ["python", "agent.py"]）。

也可以参考文档给出的 Node.js 模板：

FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY . . CMD ["node", "index.js"]

显式指定 Dockerfile

ai: agents: myAgent: artifact: image: file: Dockerfile.agent # 自定义 Dockerfile 名称 path: ./agent # 构建上下文目录 repository: my-agent-repo # 自定义 ECR 仓库名 buildArgs: PYTHON_VERSION: '3.12' ENV: production

使用已有镜像（可选分支）

如果你的镜像已经由 CI/CD 流水线构建，或需要跨账号使用，直接填 ECR 镜像地址，框架跳过本地构建：

ai: agents: myAgent: artifact: image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest

路径 B：Python 代码部署

最小配置

ai: agents: myAgent: handler: agent.py runtime: python3.12

handler属性是触发代码部署模式的开关，runtime只能是python3.10、python3.11、python3.12、python3.13之一（不写runtime时默认python3.13）。agent 入口用bedrock-agentcoreSDK 的BedrockAgentCoreApp声明：

from bedrock_agentcore.runtime import BedrockAgentCoreApp app = BedrockAgentCoreApp() @app.entrypoint def agent_invocation(payload, context): # 你的 agent 逻辑 result = agent.invoke(payload.get("prompt")) return {"result": result} app.run()

控制打包内容

打包规则与 Lambda 函数打包相同，用package控制哪些文件进入代码包：

ai: agents: myAgent: handler: agent.py package: patterns: - '!tests/**' - '!docs/**' include: - 'lib/**' exclude: - '*.pyc'

使用自定义 S3 位置（可选分支）

当制品已提前打包、需要与部署流程分离管理、或生产环境要锁定版本时，指向自己上传好的 S3 对象：

ai: agents: myAgent: handler: main.py runtime: python3.12 artifact: s3: bucket: my-artifacts-bucket key: agents/my-agent.zip versionId: abc123 # 可选：锁定具体版本

一个需要注意的文档不一致

代码部署示例的 README 在 Prerequisites 中写明 "No Docker required(unlike container deployment)"，但该示例的serverless.yml开启了custom.pythonRequirements.dockerizePip: true，示例注释将其描述为 "Code deployment (uses Docker only for dependency packaging)"——即依赖打包环节仍可能借助 Docker 来为 Linux 运行时编译依赖。这两处说法并存于仓库文档中：如果你的依赖含需要编译的包，建议本地准备 Docker；纯标准依赖项目可按"无需 Docker"理解。

部署与验证

两条路径的部署命令完全一致：

serverless deploy

文档描述的框架行为：Docker 路径会构建镜像并推送到 ECR，Code 路径会打包代码并上传 S3；两条路径部署成功后都会输出 invocation URL。

部署后按以下顺序验证（均来自文档给出的命令）：

# 查看部署信息（含输出的 URL/ARN） serverless info # 调用已部署的 agent serverless invoke --agent myAgent --data '{"prompt": "Hello!"}' # 查看 / 实时跟踪 agent 日志 serverless logs --agent myAgent serverless logs --agent myAgent --tail

--agent指定的名字要与serverless.yml中的 agent 键一致；invoke还支持--path（文件输入）和--session-id（多轮会话）。

需要程序化验证时，文档特别强调：不能用 curl 直接调用 AgentCore runtime，必须用 AWS SDK 的bedrock-agentcore客户端调用invoke_agent_runtime：

import boto3 import json import uuid client = boto3.client('bedrock-agentcore', region_name='us-east-1') response = client.invoke_agent_runtime( agentRuntimeArn='YOUR_RUNTIME_ARN', # 替换为 deploy 输出的 runtime ARN runtimeSessionId=str(uuid.uuid4()), payload=json.dumps({"prompt": "What is 25 multiplied by 4?"}).encode() ) result = json.loads(response['response'].read()) print(result)

两个官方示例也都附带了test-invoke.py脚本作为替代验证手段，运行前需先把部署输出的 runtime ARN 填入脚本。

已知限制与后续操作

• 网络默认 PUBLIC 模式：agent 通过 AWS 认证对互联网可访问；需要访问私有资源或做网络隔离时改为network.mode: VPC，并满足文档列出的要求（子网需 NAT Gateway、安全组放行出站 443）。
• 环境变量的上限：最多 50 个环境变量（AWS 在部署时强制）；密钥应放 Secrets Manager 或 Parameter Store，不要直接写进environment。
• 本地迭代：部署后可以用serverless dev在本地跑 agent。注意 dev mode 的执行模式自动检测逻辑是：配置了artifact.image走 Docker 模式（与生产行为最接近），配置了handler走 Code 模式（仅监视.py文件、直接起 Python 进程）。所以两条部署路径在本地开发时的行为也不同，Code 模式下 handler 需要读取PORT环境变量来监听端口。
• 清理：serverless remove移除全部资源（会删除 CloudFormation 栈及 Runtime 等资源，执行前确认 stage 无误）。

如果 agent 之后要加工具或会话记忆，对应的文档是 Gateway Configuration 和 Memory Configuration，以及 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