Serverless Framework AgentCore Dev Mode本地开发 AI Agent 的完整实战指南【免费下载链接】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 的 AgentCore 集成能力为基础系统讲解serverless dev本地开发模式的完整技术方案如何在不重复部署的前提下让运行在本机的 AI Agent 借用云端已部署 IAM 角色权限访问 gateway、memory、Bedrock 模型等资源并享受热重载与交互式聊天。读完本文你将掌握 Dev Mode 的两种执行模式Docker 与 Python Code的选择依据、IAM 临时凭证的自动注入与刷新机制、环境变量清单、交互式调用协议及文件监视行为并能够据此搭建一套高效的 Agent 本地迭代工作流。Dev Mode 是什么AgentCore Dev Mode 是 Serverless Framework 为 AI Agent 提供的一键式本地开发模式。你只需要在项目目录执行一条命令serverless dev它就会在你的本机运行 Agent同时复用云端部署阶段创建的IAM 执行角色来获得 AWS 权限。这意味着你可以在不重新serverless deploy的前提下持续迭代 Agent 代码却依然能够访问全部已部署的 AWS 资源——包括 gateway 工具、会话记忆Memory、Bedrock 模型等。按官方文档的说法它的核心价值是 run your agent on your local machine while using the deployed IAM role for AWS permissions想改 Agent 代码就改代码、保存即重启而权限与云资源始终与线上版本保持一致。关联文档agents/dev.mdAgent 整体能力参见 agents/README.md。快速上手Dev Mode 的前提是 Agent 已经完成过一次云端部署部署过程会创建 IAM 角色与 CloudFormation 云资源然后分三步走1. 先部署 Agent创建 IAM 角色与云资源serverless deploy2. 启动 Dev Modeserverless dev3. 与 Agent 对话——当 Agent 就绪后终端会出现如下交互界面Dev mode running on http://localhost:8080 Session ID: a1b2c3d4-... Type your message and press Enter to chat with the agent. Press CtrlC to stop. You: What can you help me with? Agent: Im an AI assistant that can help you with... You:此后修改 Agent 源码并保存文件Dev Mode 会自动重新构建并重启无需手工干预。在仓库源码中整个流程由AgentCoreDevMode类统一编排对应实现位于 dev/index.js。其中关键的状态字段包括会话 IDrandomUUID()生成、端口、模式docker/code、容器/进程句柄、文件监视器、是否正在重建#isRebuilding与是否正在关闭#isShuttingDown等。工作原理当执行serverless dev时框架按以下步骤工作获取已部署资源——从 CloudFormation 读取 IAM 角色 ARN、gateway URL、memory ID 等栈输出配置 IAM 信任策略——自动把你的本地身份加入该角色的信任策略使你能对其执行 AssumeRole获取临时凭证——调用 STS AssumeRole 获得 60 分钟有效期的凭证探测执行模式——根据项目配置判断使用 Docker 还是 Code 模式在本地启动 Agent——启动 Docker 容器或 Python 进程并注入凭证与环境变量监听文件变化——源文件变更时自动重建/重启启动交互式聊天——提供支持流式响应的 readline CLI。官方文档给出的一张流程图可以直观概括整个链路serverless dev │ ├── Read CloudFormation stack outputs (Role ARN, Gateway URL, Memory ID) ├── Update IAM trust policy for local AssumeRole ├── Get STS temporary credentials (60 min) │ ├── [Docker Mode] Build image → Run container on port 8080 │ OR ├── [Code Mode] Spawn Python process on PORT │ ├── Start file watcher └── Start interactive chat CLI │ ├── User types message ├── HTTP POST http://localhost:8080/invocations ├── Agent responds (SSE stream or JSON) └── Display response从源码实现上看start()方法见 dev/index.js的顺序与文档完全对应先探测模式 → 初始化 IAM/STS 客户端 → 通过GetCallerIdentityCommand获取本地身份 → 调用#ensureLocalDevTrustPolicy更新信任策略 → 调用#getTemporaryCredentials获取临时凭证 → 按模式启动#startDockerMode或#startCodeMode→ 启动文件监视器#startWatcher→ 输出 Dev mode running on... 提示 → 进入交互式聊天#startChat。需要强调的一个设计要点是Agent 是本地进程直接调用 AWS 服务注入的临时凭证来自本机链路中不存在 tunnel 或云端代理。命令选项# 自动探测第一个 runtime 类型的 Agent serverless dev # 指定要运行的 Agent当定义了多个 Agent 时必须使用 serverless dev --agent myAgent # 使用自定义端口默认8080 serverless dev --port 9000 # 强制进入 Agents Dev Mode见下方说明 serverless dev --agents关于--agents标志当你的serverless.yml中同时定义了 Lambda 函数和 Agent时serverless dev默认进入 Lambda 函数的 Dev Mode。此时需要显式加--agents选择 Agent 的 Dev Mode# 默认行为当存在函数时运行的是 Lambda 的 Dev Mode serverless dev # 显式切换为 Agent 的 Dev Mode serverless dev --agents如果配置中只有 Agent没有函数则会自动选择 Agent 的 Dev Mode无需手动指定。两种执行模式Dev Mode 支持Docker与Code仅 Python两种执行模式并会根据项目配置自动探测。仓库源码中#detectMode()见 dev/index.js的实现与文档完全一致。模式探测优先级优先级条件模式1配置了artifact.image对象形式Docker2配置了handler且 image 非字符串Code仅 Python3项目根目录存在DockerfileDocker4默认无显式配置按镜像自动构建处理Docker源码中的判断顺序依次是artifact.image为对象 →handler且非字符串 image → 项目根目录存在Dockerfile→ 默认 Docker。其中最后的默认分支在实现中明确注释为与serverless deploycoordinator.js 默认走 Buildpacks行为保持一致即没有显式声明时按 Docker 处理。Docker 模式在本地构建 Docker 镜像并在容器中运行是大多数项目的默认模式ai: agents: myAgent: {} # 自动探测项目中的 Dockerfile特点与行为构建的镜像命名为service-agent:local源码中容器名固定为sls-dev-service-agent的小写形式把容器内的 8080 端口映射到宿主机端口监视 Dockerfile 所在目录的文件变化文件变更后自动重建容器与生产环境的运行行为最为接近完整隔离。从源码看Docker 模式复用了部署期一致的DockerBuilder构建逻辑#buildImage()读取artifact.image.path/platform/file/buildArgs/buildOptions/cacheFrom配置并通过DockerClient.createContainer创建容器端口绑定被显式设置为127.0.0.1仅回环地址可达避免 Docker 默认发布到所有网卡接口同时容器会打上com.serverless.agentcore.dev-mode与com.serverless.agentcore.agent标签。启动后会自动跟随容器 stdout/stderr 日志并剥离 Docker 流的 8 字节多路复用头保证输出可读。Code 模式仅 Python不使用 Docker直接运行 Python 进程。启动与迭代更快适合快速原型开发ai: agents: myAgent: handler: agent.py runtime: python3.13特点与行为从项目目录直接 spawn Python 进程仅监视.py文件的变化文件变化时重启 Python 进程强烈建议配合虚拟环境使用以获得凭证隔离。重要你的 handler 必须读取PORT环境变量才能让 Code 模式可用if __name__ __main__: port int(os.getenv(PORT, 8080)) app.run(portport, host0.0.0.0)Code 模式的进程管理实现在 dev/code-mode.js。它把handler解析为项目下的绝对路径用spawn拉起 Python 子进程进程退出时若非正常关闭会打印退出码stop()先发SIGTERM等待最多 2 秒优雅退出超时再用SIGKILL强制结束。如果 Python 可执行文件不存在ENOENT会给出明确的安装提示。资源自动发现Dev Mode 会自动从 CloudFormation 栈输出中读取已部署的云资源并把它们作为环境变量注入本地 Agent从而使本地版本连接到与线上完全相同的 gateway 工具、记忆等资源资源环境变量注入条件Gateway URLBEDROCK_AGENTCORE_GATEWAY_URL已部署 gateway/工具Memory IDBEDROCK_AGENTCORE_MEMORY_IDAgent 上已配置记忆整个过程完全自动无需手工配置运行serverless dev时框架读取 CloudFormation 栈输出并注入取值。这正是本文开头所说复用已部署资源能力的关键——本地代码与云端共享同一套 gateway、memory 基础设施引用。凭证管理Dev Mode 通过已部署的 IAM 角色自动管理 AWS 凭证整个过程无需你手动拷贝任何 AccessKey。工作流程信任策略设置——Dev Mode 向 Agent 所在 IAM 角色的信任策略追加一个名为ServerlessAgentCoreLocalDevPolicy的 statement允许你的本地 AWS 身份 AssumeRole 该角色该机制同时覆盖 SSO 会话、被 Assume 的中间角色以及普通 IAM 用户。源码中该 SID 常量定义于 dev/credentials.js追加的 statement 形如{ Sid: ServerlessAgentCoreLocalDevPolicy, Effect: Allow, Principal: { AWS: [userArn] }, Action: sts:AssumeRole }。由于采用固定 SID框架在重复运行时能够识别并复用同一 statement不会干扰角色信任策略中的其它条目如果本地用户 ARN 尚未在其中则会以追加主体验的方式更新addPrincipalToPolicy。STS AssumeRole——获得临时凭证AccessKeyId、SecretAccessKey、SessionToken有效期 60 分钟。自动刷新——当凭证剩余时间不足 10 分钟且又有文件变更触发重建时会自动重新获取凭证。判断阈值实现在areCredentialsExpiring()默认阈值 10 分钟每次重建前#refreshCredentialsIfNeeded()都会检查凭证是否即将过期。重试逻辑——凭证获取最多重试 10 次采用指数退避以应对 IAM 传播延迟。退避计算见calculateBackoffDelay()基础延迟 5 秒、指数递增、上限 30 秒。一个值得注意的工程细节信任策略传播源码在更新信任策略后有一段明确的等待逻辑IAM 信任策略传播大约需要 1020 秒而第一次 AssumeRole 调用必须等传播完成——因为一次过早调用返回的AccessDenied会被 STS 负向缓存数分钟导致后续所有重试都失败。因此 dev/index.js 中在调用UpdateAssumeRolePolicyCommand后固定等待TRUST_POLICY_PROPAGATION_WAIT_MS 1000010 秒。此外源码还专门处理了 SSO 场景的身份归一化GetCallerIdentity返回的可能是arn:aws:sts::…:assumed-role/AWSReservedSSO_xxx/…会话 ARN而信任策略需要 IAM 角色 ARN 才能可靠工作。对以AWSReservedSSO_开头的角色代码会调用iam:GetRole拿权威 ARN解决权限集按 region 路径存放导致的 Invalid principal in policy 问题其他场景则通过normalizeAssumedRoleArn()做字符串归一化。凭证隔离Code 模式对于 Python Code 模式强烈建议创建虚拟环境python3 -m venv venv source venv/bin/activate pip install -r requirements.txt serverless dev这样做的目的是防止 boto3 读取你系统级的~/.aws/config或 SSO 缓存确保 Agent 只使用注入的临时凭证。Dev Mode 会通过VIRTUAL_ENV环境变量自动探测虚拟环境。从源码看虚拟环境激活后Code 模式会把 venv 的bin/Windows 下为Scripts/目录前置到PATH中并向 Python 子进程透传VIRTUAL_ENV与VIRTUAL_ENV_PROMPT。如果VIRTUAL_ENV已设置但目录不存在则会告警并回退到系统 Python。环境变量清单Dev Mode 会向 Agent 进程/容器注入以下环境变量。总是注入变量说明AWS_ACCESS_KEY_ID临时 STS 凭证AWS_SECRET_ACCESS_KEY临时 STS 凭证AWS_SESSION_TOKEN临时 STS 凭证AWS_REGION取自 provider 配置AWS_DEFAULT_REGION与AWS_REGION相同AGENTCORE_DEV_MODE恒为true——可在 Agent 代码中据此识别 Dev 模式PYTHONUNBUFFERED恒为1——保证日志实时输出SLS_SERVICEserverless.yml中的服务名SLS_STAGE当前 stageSLS_AGENTAgent 名称模式专属变量模式说明PORT仅 CodeHandler 应当监听的端口号自动发现若已部署变量说明BEDROCK_AGENTCORE_GATEWAY_URLGateway 端点 URLBEDROCK_AGENTCORE_MEMORY_IDMemory 资源 ID用户自定义在serverless.yml的environment中定义的任何变量也会一并注入ai: agents: myAgent: environment: MODEL_ID: us.anthropic.claude-sonnet-4-20250514-v1:0 MY_API_KEY: ${ssm:/my/api/key}值得一提上述变量列表在 Docker 与 Code 两种模式下由不同代码路径实现容器环境 vs 子进程 env但两条路径都刻意保持一致且用户定义的environment会覆盖同名的内置变量行为由 dev/index.js 与 dev/code-mode.js 中注释标明与 Docker 模式保持一致来保证。交互式聊天Dev Mode 内置了一个与本地 Agent 对话的 CLI输入在You:提示符下输入消息流式输出通过 Server-Sent EventsSSE实时流式渲染响应会话每次启动 Dev Mode 都会生成新的会话 IDUUID当文件变化触发重建时会话自动重置源码在每次重建完成后重新randomUUID()退出按CtrlC优雅退出停止容器/进程并清理资源。从源码看聊天期间如果已有请求正在执行#isInvoking为 true再输入消息会得到 Please wait for the current request to complete. 的提示日志输出与聊天提示符之间也做了互斥处理避免打断输入。调用协议聊天 CLI 向本地 Agent 发送 HTTP POST 请求POST http://localhost:port/invocations Content-Type: application/json Accept: text/event-stream X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid { prompt: Your message here }Agent 可以返回 SSE 流或普通 JSON。源码中的#invokeAgent()正是按此协议fetch本地端点并把X-Amzn-Bedrock-AgentCore-Runtime-Session-Id设置为当前会话 ID随后根据响应的content-type分流到 SSE 流式处理#handleStreamingResponse或 JSON 处理#handleJsonResponse。在流式解析上框架兼容多种 Agent 事件格式既支持 AgentCore 原生的contentBlockDelta.delta.text增量文本也能识别 LangGraph 式的init/start/messageStart/messageStop/contentBlockStop等控制事件跳过不展示还能兼容 Strands 的{data: …}增量与delta.text等格式。错误事件、JSON 响应中的result、response、message、error字段也都有对应的输出处理。文件监视与热重载Dev Mode 会监视源文件并在变化时自动重建/重启。监视行为Docker 模式监视整个 Dockerfile 所在目录若配置了artifact.image.path则监视该目录Code 模式只监视项目中的.py文件防抖使用 300ms 稳定阈值避免写入过程中的无效重建源码对应awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 }重建流程停止 Agent → 若凭证即将过期则刷新凭证 → 按模式重启 → 重置会话。为避免重建风暴源码引入了重建中标记 待重建队列机制#isRebuilding/#pendingRebuild重建期间的新事件只排一次队。排除路径以下路径永远不参与监视node_modules/、.git/、.serverless/venv/、.venv/__pycache__/、*.pyc.pytest_cache/、.mypy_cache/、coverage/测试文件*_test.py、*.test.py、*.test.js、*.spec.js这些排除规则连同 Code 模式只监视 .py在 dev/index.js 与 dev/code-mode.js 中各有一份等价实现。Code 模式的需求与前置条件Python 版本映射Dev Mode 会把 runtime 配置转换成对应的 Python 命令Runtime 配置执行的 Python 命令python3.13python3.13python3.12python3.12若本机安装的 Python 版本与配置的 runtime 不一致Dev Mode 会输出版本不匹配警告。从仓库的配置校验源码看AgentCore code 部署所支持的 Python runtime 为python3.10python3.14见 validators/schema.js这些版本会统一映射为对应的python3.x可执行命令。在 Windows 上无论 runtime 如何配置都会使用python.exe。虚拟环境Code 模式强烈建议使用虚拟环境python3 -m venv venv source venv/bin/activate # Linux/macOS # 或: venv\Scripts\activate # Windows pip install -r requirements.txtDev Mode 通过VIRTUAL_ENV环境变量探测虚拟环境并自动完成以下工作将 venv 的bin/目录前置到PATH向 Python 进程透传VIRTUAL_ENV与VIRTUAL_ENV_PROMPT提供相对系统级 AWS 配置的凭证隔离。推荐的文件结构my-agent/ ├── agent.py # 入口点handler ├── requirements.txt # 依赖 ├── serverless.yml # 配置 └── venv/ # 虚拟环境推荐常见问题排查Failed to gather deployed agent resources在使用 Dev Mode 之前必须先部署 Agent。IAM 角色与云资源必须存在serverless deploy对话时提示 Connection refusedAgent 仍在启动中。等待数秒待容器/进程完成初始化并开始监听端口后再试。源码中对这类ECONNREFUSED错误会提示 Container is not responding. It may be restarting.Python 版本不匹配警告Dev Mode 检测到的 Python 版本与配置不一致。可以安装正确的版本或更新serverless.yml中的runtime# 检查本机已安装版本 python3.13 --version # 或更新 serverless.yml ai: agents: myAgent: runtime: python3.12 # 与本机安装版本保持一致更新信任策略后凭证获取失败IAM 信任策略的变更需要几秒钟才能传播。Dev Mode 会自动等待 10 秒源码中为TRUST_POLICY_PROPAGATION_WAIT_MS 10000但极少数情况下仍需重试——此时内置的 10 次指数退避重试会兜底避免因 STS 负向缓存导致长时间失败。boto3 使用了错误的凭证Code 模式如果你的 Agent 使用了系统级 AWS 凭证而不是注入的临时凭证请激活虚拟环境python3 -m venv venv source venv/bin/activate pip install -r requirements.txt serverless dev这样可以隔离 boto3 对~/.aws/config与 SSO 会话缓存的读取。文件变更后 Agent 崩溃Dev Mode 不会在崩溃后自动重启。修复代码中的问题后保存文件即可再次触发自动重建。验证与测试仓库为 Dev Mode 提供了单元测试可作为行为契约来阅读credentials.test.js覆盖信任策略 SID 常量、角色名提取、凭证过期判定阈值默认 10 分钟、策略语句的查找/创建/主体验权/追加以及退避延迟与 ARN 归一化逻辑同目录下的code-mode.test.js覆盖 Code 模式进程管理相关行为。对每个行为都可以在 dev/index.js、dev/credentials.js 与 dev/code-mode.js 找到对应的实现入口。进一步探索AgentCore 是一个完整的部署运行时体系Dev Mode 只是其中一个环节。要继续深入可参考同一目录下的系列文档Runtime Configuration — 部署与运行参数Gateway Configuration — 通过 Lambda、OpenAPI、MCP 提供自定义工具Memory Configuration — 会话持久化Browser Configuration — Web 自动化能力Code Interpreter — 沙箱化代码执行【免费下载链接】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），仅供参考 Serverless Framework AgentCore Dev Mode：本地开发 AI Agent 的完整实战指南
Serverless Framework AgentCore Dev Mode本地开发 AI Agent 的完整实战指南【免费下载链接】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 的 AgentCore 集成能力为基础系统讲解serverless dev本地开发模式的完整技术方案如何在不重复部署的前提下让运行在本机的 AI Agent 借用云端已部署 IAM 角色权限访问 gateway、memory、Bedrock 模型等资源并享受热重载与交互式聊天。读完本文你将掌握 Dev Mode 的两种执行模式Docker 与 Python Code的选择依据、IAM 临时凭证的自动注入与刷新机制、环境变量清单、交互式调用协议及文件监视行为并能够据此搭建一套高效的 Agent 本地迭代工作流。Dev Mode 是什么AgentCore Dev Mode 是 Serverless Framework 为 AI Agent 提供的一键式本地开发模式。你只需要在项目目录执行一条命令serverless dev它就会在你的本机运行 Agent同时复用云端部署阶段创建的IAM 执行角色来获得 AWS 权限。这意味着你可以在不重新serverless deploy的前提下持续迭代 Agent 代码却依然能够访问全部已部署的 AWS 资源——包括 gateway 工具、会话记忆Memory、Bedrock 模型等。按官方文档的说法它的核心价值是 run your agent on your local machine while using the deployed IAM role for AWS permissions想改 Agent 代码就改代码、保存即重启而权限与云资源始终与线上版本保持一致。关联文档agents/dev.mdAgent 整体能力参见 agents/README.md。快速上手Dev Mode 的前提是 Agent 已经完成过一次云端部署部署过程会创建 IAM 角色与 CloudFormation 云资源然后分三步走1. 先部署 Agent创建 IAM 角色与云资源serverless deploy2. 启动 Dev Modeserverless dev3. 与 Agent 对话——当 Agent 就绪后终端会出现如下交互界面Dev mode running on http://localhost:8080 Session ID: a1b2c3d4-... Type your message and press Enter to chat with the agent. Press CtrlC to stop. You: What can you help me with? Agent: Im an AI assistant that can help you with... You:此后修改 Agent 源码并保存文件Dev Mode 会自动重新构建并重启无需手工干预。在仓库源码中整个流程由AgentCoreDevMode类统一编排对应实现位于 dev/index.js。其中关键的状态字段包括会话 IDrandomUUID()生成、端口、模式docker/code、容器/进程句柄、文件监视器、是否正在重建#isRebuilding与是否正在关闭#isShuttingDown等。工作原理当执行serverless dev时框架按以下步骤工作获取已部署资源——从 CloudFormation 读取 IAM 角色 ARN、gateway URL、memory ID 等栈输出配置 IAM 信任策略——自动把你的本地身份加入该角色的信任策略使你能对其执行 AssumeRole获取临时凭证——调用 STS AssumeRole 获得 60 分钟有效期的凭证探测执行模式——根据项目配置判断使用 Docker 还是 Code 模式在本地启动 Agent——启动 Docker 容器或 Python 进程并注入凭证与环境变量监听文件变化——源文件变更时自动重建/重启启动交互式聊天——提供支持流式响应的 readline CLI。官方文档给出的一张流程图可以直观概括整个链路serverless dev │ ├── Read CloudFormation stack outputs (Role ARN, Gateway URL, Memory ID) ├── Update IAM trust policy for local AssumeRole ├── Get STS temporary credentials (60 min) │ ├── [Docker Mode] Build image → Run container on port 8080 │ OR ├── [Code Mode] Spawn Python process on PORT │ ├── Start file watcher └── Start interactive chat CLI │ ├── User types message ├── HTTP POST http://localhost:8080/invocations ├── Agent responds (SSE stream or JSON) └── Display response从源码实现上看start()方法见 dev/index.js的顺序与文档完全对应先探测模式 → 初始化 IAM/STS 客户端 → 通过GetCallerIdentityCommand获取本地身份 → 调用#ensureLocalDevTrustPolicy更新信任策略 → 调用#getTemporaryCredentials获取临时凭证 → 按模式启动#startDockerMode或#startCodeMode→ 启动文件监视器#startWatcher→ 输出 Dev mode running on... 提示 → 进入交互式聊天#startChat。需要强调的一个设计要点是Agent 是本地进程直接调用 AWS 服务注入的临时凭证来自本机链路中不存在 tunnel 或云端代理。命令选项# 自动探测第一个 runtime 类型的 Agent serverless dev # 指定要运行的 Agent当定义了多个 Agent 时必须使用 serverless dev --agent myAgent # 使用自定义端口默认8080 serverless dev --port 9000 # 强制进入 Agents Dev Mode见下方说明 serverless dev --agents关于--agents标志当你的serverless.yml中同时定义了 Lambda 函数和 Agent时serverless dev默认进入 Lambda 函数的 Dev Mode。此时需要显式加--agents选择 Agent 的 Dev Mode# 默认行为当存在函数时运行的是 Lambda 的 Dev Mode serverless dev # 显式切换为 Agent 的 Dev Mode serverless dev --agents如果配置中只有 Agent没有函数则会自动选择 Agent 的 Dev Mode无需手动指定。两种执行模式Dev Mode 支持Docker与Code仅 Python两种执行模式并会根据项目配置自动探测。仓库源码中#detectMode()见 dev/index.js的实现与文档完全一致。模式探测优先级优先级条件模式1配置了artifact.image对象形式Docker2配置了handler且 image 非字符串Code仅 Python3项目根目录存在DockerfileDocker4默认无显式配置按镜像自动构建处理Docker源码中的判断顺序依次是artifact.image为对象 →handler且非字符串 image → 项目根目录存在Dockerfile→ 默认 Docker。其中最后的默认分支在实现中明确注释为与serverless deploycoordinator.js 默认走 Buildpacks行为保持一致即没有显式声明时按 Docker 处理。Docker 模式在本地构建 Docker 镜像并在容器中运行是大多数项目的默认模式ai: agents: myAgent: {} # 自动探测项目中的 Dockerfile特点与行为构建的镜像命名为service-agent:local源码中容器名固定为sls-dev-service-agent的小写形式把容器内的 8080 端口映射到宿主机端口监视 Dockerfile 所在目录的文件变化文件变更后自动重建容器与生产环境的运行行为最为接近完整隔离。从源码看Docker 模式复用了部署期一致的DockerBuilder构建逻辑#buildImage()读取artifact.image.path/platform/file/buildArgs/buildOptions/cacheFrom配置并通过DockerClient.createContainer创建容器端口绑定被显式设置为127.0.0.1仅回环地址可达避免 Docker 默认发布到所有网卡接口同时容器会打上com.serverless.agentcore.dev-mode与com.serverless.agentcore.agent标签。启动后会自动跟随容器 stdout/stderr 日志并剥离 Docker 流的 8 字节多路复用头保证输出可读。Code 模式仅 Python不使用 Docker直接运行 Python 进程。启动与迭代更快适合快速原型开发ai: agents: myAgent: handler: agent.py runtime: python3.13特点与行为从项目目录直接 spawn Python 进程仅监视.py文件的变化文件变化时重启 Python 进程强烈建议配合虚拟环境使用以获得凭证隔离。重要你的 handler 必须读取PORT环境变量才能让 Code 模式可用if __name__ __main__: port int(os.getenv(PORT, 8080)) app.run(portport, host0.0.0.0)Code 模式的进程管理实现在 dev/code-mode.js。它把handler解析为项目下的绝对路径用spawn拉起 Python 子进程进程退出时若非正常关闭会打印退出码stop()先发SIGTERM等待最多 2 秒优雅退出超时再用SIGKILL强制结束。如果 Python 可执行文件不存在ENOENT会给出明确的安装提示。资源自动发现Dev Mode 会自动从 CloudFormation 栈输出中读取已部署的云资源并把它们作为环境变量注入本地 Agent从而使本地版本连接到与线上完全相同的 gateway 工具、记忆等资源资源环境变量注入条件Gateway URLBEDROCK_AGENTCORE_GATEWAY_URL已部署 gateway/工具Memory IDBEDROCK_AGENTCORE_MEMORY_IDAgent 上已配置记忆整个过程完全自动无需手工配置运行serverless dev时框架读取 CloudFormation 栈输出并注入取值。这正是本文开头所说复用已部署资源能力的关键——本地代码与云端共享同一套 gateway、memory 基础设施引用。凭证管理Dev Mode 通过已部署的 IAM 角色自动管理 AWS 凭证整个过程无需你手动拷贝任何 AccessKey。工作流程信任策略设置——Dev Mode 向 Agent 所在 IAM 角色的信任策略追加一个名为ServerlessAgentCoreLocalDevPolicy的 statement允许你的本地 AWS 身份 AssumeRole 该角色该机制同时覆盖 SSO 会话、被 Assume 的中间角色以及普通 IAM 用户。源码中该 SID 常量定义于 dev/credentials.js追加的 statement 形如{ Sid: ServerlessAgentCoreLocalDevPolicy, Effect: Allow, Principal: { AWS: [userArn] }, Action: sts:AssumeRole }。由于采用固定 SID框架在重复运行时能够识别并复用同一 statement不会干扰角色信任策略中的其它条目如果本地用户 ARN 尚未在其中则会以追加主体验的方式更新addPrincipalToPolicy。STS AssumeRole——获得临时凭证AccessKeyId、SecretAccessKey、SessionToken有效期 60 分钟。自动刷新——当凭证剩余时间不足 10 分钟且又有文件变更触发重建时会自动重新获取凭证。判断阈值实现在areCredentialsExpiring()默认阈值 10 分钟每次重建前#refreshCredentialsIfNeeded()都会检查凭证是否即将过期。重试逻辑——凭证获取最多重试 10 次采用指数退避以应对 IAM 传播延迟。退避计算见calculateBackoffDelay()基础延迟 5 秒、指数递增、上限 30 秒。一个值得注意的工程细节信任策略传播源码在更新信任策略后有一段明确的等待逻辑IAM 信任策略传播大约需要 1020 秒而第一次 AssumeRole 调用必须等传播完成——因为一次过早调用返回的AccessDenied会被 STS 负向缓存数分钟导致后续所有重试都失败。因此 dev/index.js 中在调用UpdateAssumeRolePolicyCommand后固定等待TRUST_POLICY_PROPAGATION_WAIT_MS 1000010 秒。此外源码还专门处理了 SSO 场景的身份归一化GetCallerIdentity返回的可能是arn:aws:sts::…:assumed-role/AWSReservedSSO_xxx/…会话 ARN而信任策略需要 IAM 角色 ARN 才能可靠工作。对以AWSReservedSSO_开头的角色代码会调用iam:GetRole拿权威 ARN解决权限集按 region 路径存放导致的 Invalid principal in policy 问题其他场景则通过normalizeAssumedRoleArn()做字符串归一化。凭证隔离Code 模式对于 Python Code 模式强烈建议创建虚拟环境python3 -m venv venv source venv/bin/activate pip install -r requirements.txt serverless dev这样做的目的是防止 boto3 读取你系统级的~/.aws/config或 SSO 缓存确保 Agent 只使用注入的临时凭证。Dev Mode 会通过VIRTUAL_ENV环境变量自动探测虚拟环境。从源码看虚拟环境激活后Code 模式会把 venv 的bin/Windows 下为Scripts/目录前置到PATH中并向 Python 子进程透传VIRTUAL_ENV与VIRTUAL_ENV_PROMPT。如果VIRTUAL_ENV已设置但目录不存在则会告警并回退到系统 Python。环境变量清单Dev Mode 会向 Agent 进程/容器注入以下环境变量。总是注入变量说明AWS_ACCESS_KEY_ID临时 STS 凭证AWS_SECRET_ACCESS_KEY临时 STS 凭证AWS_SESSION_TOKEN临时 STS 凭证AWS_REGION取自 provider 配置AWS_DEFAULT_REGION与AWS_REGION相同AGENTCORE_DEV_MODE恒为true——可在 Agent 代码中据此识别 Dev 模式PYTHONUNBUFFERED恒为1——保证日志实时输出SLS_SERVICEserverless.yml中的服务名SLS_STAGE当前 stageSLS_AGENTAgent 名称模式专属变量模式说明PORT仅 CodeHandler 应当监听的端口号自动发现若已部署变量说明BEDROCK_AGENTCORE_GATEWAY_URLGateway 端点 URLBEDROCK_AGENTCORE_MEMORY_IDMemory 资源 ID用户自定义在serverless.yml的environment中定义的任何变量也会一并注入ai: agents: myAgent: environment: MODEL_ID: us.anthropic.claude-sonnet-4-20250514-v1:0 MY_API_KEY: ${ssm:/my/api/key}值得一提上述变量列表在 Docker 与 Code 两种模式下由不同代码路径实现容器环境 vs 子进程 env但两条路径都刻意保持一致且用户定义的environment会覆盖同名的内置变量行为由 dev/index.js 与 dev/code-mode.js 中注释标明与 Docker 模式保持一致来保证。交互式聊天Dev Mode 内置了一个与本地 Agent 对话的 CLI输入在You:提示符下输入消息流式输出通过 Server-Sent EventsSSE实时流式渲染响应会话每次启动 Dev Mode 都会生成新的会话 IDUUID当文件变化触发重建时会话自动重置源码在每次重建完成后重新randomUUID()退出按CtrlC优雅退出停止容器/进程并清理资源。从源码看聊天期间如果已有请求正在执行#isInvoking为 true再输入消息会得到 Please wait for the current request to complete. 的提示日志输出与聊天提示符之间也做了互斥处理避免打断输入。调用协议聊天 CLI 向本地 Agent 发送 HTTP POST 请求POST http://localhost:port/invocations Content-Type: application/json Accept: text/event-stream X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid { prompt: Your message here }Agent 可以返回 SSE 流或普通 JSON。源码中的#invokeAgent()正是按此协议fetch本地端点并把X-Amzn-Bedrock-AgentCore-Runtime-Session-Id设置为当前会话 ID随后根据响应的content-type分流到 SSE 流式处理#handleStreamingResponse或 JSON 处理#handleJsonResponse。在流式解析上框架兼容多种 Agent 事件格式既支持 AgentCore 原生的contentBlockDelta.delta.text增量文本也能识别 LangGraph 式的init/start/messageStart/messageStop/contentBlockStop等控制事件跳过不展示还能兼容 Strands 的{data: …}增量与delta.text等格式。错误事件、JSON 响应中的result、response、message、error字段也都有对应的输出处理。文件监视与热重载Dev Mode 会监视源文件并在变化时自动重建/重启。监视行为Docker 模式监视整个 Dockerfile 所在目录若配置了artifact.image.path则监视该目录Code 模式只监视项目中的.py文件防抖使用 300ms 稳定阈值避免写入过程中的无效重建源码对应awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 }重建流程停止 Agent → 若凭证即将过期则刷新凭证 → 按模式重启 → 重置会话。为避免重建风暴源码引入了重建中标记 待重建队列机制#isRebuilding/#pendingRebuild重建期间的新事件只排一次队。排除路径以下路径永远不参与监视node_modules/、.git/、.serverless/venv/、.venv/__pycache__/、*.pyc.pytest_cache/、.mypy_cache/、coverage/测试文件*_test.py、*.test.py、*.test.js、*.spec.js这些排除规则连同 Code 模式只监视 .py在 dev/index.js 与 dev/code-mode.js 中各有一份等价实现。Code 模式的需求与前置条件Python 版本映射Dev Mode 会把 runtime 配置转换成对应的 Python 命令Runtime 配置执行的 Python 命令python3.13python3.13python3.12python3.12若本机安装的 Python 版本与配置的 runtime 不一致Dev Mode 会输出版本不匹配警告。从仓库的配置校验源码看AgentCore code 部署所支持的 Python runtime 为python3.10python3.14见 validators/schema.js这些版本会统一映射为对应的python3.x可执行命令。在 Windows 上无论 runtime 如何配置都会使用python.exe。虚拟环境Code 模式强烈建议使用虚拟环境python3 -m venv venv source venv/bin/activate # Linux/macOS # 或: venv\Scripts\activate # Windows pip install -r requirements.txtDev Mode 通过VIRTUAL_ENV环境变量探测虚拟环境并自动完成以下工作将 venv 的bin/目录前置到PATH向 Python 进程透传VIRTUAL_ENV与VIRTUAL_ENV_PROMPT提供相对系统级 AWS 配置的凭证隔离。推荐的文件结构my-agent/ ├── agent.py # 入口点handler ├── requirements.txt # 依赖 ├── serverless.yml # 配置 └── venv/ # 虚拟环境推荐常见问题排查Failed to gather deployed agent resources在使用 Dev Mode 之前必须先部署 Agent。IAM 角色与云资源必须存在serverless deploy对话时提示 Connection refusedAgent 仍在启动中。等待数秒待容器/进程完成初始化并开始监听端口后再试。源码中对这类ECONNREFUSED错误会提示 Container is not responding. It may be restarting.Python 版本不匹配警告Dev Mode 检测到的 Python 版本与配置不一致。可以安装正确的版本或更新serverless.yml中的runtime# 检查本机已安装版本 python3.13 --version # 或更新 serverless.yml ai: agents: myAgent: runtime: python3.12 # 与本机安装版本保持一致更新信任策略后凭证获取失败IAM 信任策略的变更需要几秒钟才能传播。Dev Mode 会自动等待 10 秒源码中为TRUST_POLICY_PROPAGATION_WAIT_MS 10000但极少数情况下仍需重试——此时内置的 10 次指数退避重试会兜底避免因 STS 负向缓存导致长时间失败。boto3 使用了错误的凭证Code 模式如果你的 Agent 使用了系统级 AWS 凭证而不是注入的临时凭证请激活虚拟环境python3 -m venv venv source venv/bin/activate pip install -r requirements.txt serverless dev这样可以隔离 boto3 对~/.aws/config与 SSO 会话缓存的读取。文件变更后 Agent 崩溃Dev Mode 不会在崩溃后自动重启。修复代码中的问题后保存文件即可再次触发自动重建。验证与测试仓库为 Dev Mode 提供了单元测试可作为行为契约来阅读credentials.test.js覆盖信任策略 SID 常量、角色名提取、凭证过期判定阈值默认 10 分钟、策略语句的查找/创建/主体验权/追加以及退避延迟与 ARN 归一化逻辑同目录下的code-mode.test.js覆盖 Code 模式进程管理相关行为。对每个行为都可以在 dev/index.js、dev/credentials.js 与 dev/code-mode.js 找到对应的实现入口。进一步探索AgentCore 是一个完整的部署运行时体系Dev Mode 只是其中一个环节。要继续深入可参考同一目录下的系列文档Runtime Configuration — 部署与运行参数Gateway Configuration — 通过 Lambda、OpenAPI、MCP 提供自定义工具Memory Configuration — 会话持久化Browser Configuration — Web 自动化能力Code Interpreter — 沙箱化代码执行【免费下载链接】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），仅供参考