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.md；Agent 整体能力参见 agents/README.md。

快速上手

Dev Mode 的前提是 Agent 已经完成过一次云端部署（部署过程会创建 IAM 角色与 CloudFormation 云资源），然后分三步走：

1. 先部署 Agent（创建 IAM 角色与云资源）：

serverless deploy

2. 启动 Dev Mode：

serverless dev

3. 与 Agent 对话——当 Agent 就绪后，终端会出现如下交互界面：

Dev mode running on http://localhost:8080 Session ID: a1b2c3d4-... Type your message and press Enter to chat with the agent. Press Ctrl+C to stop. You: What can you help me with? Agent: I'm an AI assistant that can help you with... You:

此后修改 Agent 源码并保存文件，Dev Mode 会自动重新构建并重启，无需手工干预。

在仓库源码中，整个流程由AgentCoreDevMode类统一编排，对应实现位于 dev/index.js。其中关键的状态字段包括会话 ID（randomUUID()生成）、端口、模式（docker/code）、容器/进程句柄、文件监视器、是否正在重建（#isRebuilding）与是否正在关闭（#isShuttingDown）等。

工作原理

当执行serverless dev时，框架按以下步骤工作：

1. 获取已部署资源——从 CloudFormation 读取 IAM 角色 ARN、gateway URL、memory ID 等栈输出；
2. 配置 IAM 信任策略——自动把你的本地身份加入该角色的信任策略，使你能对其执行 AssumeRole；
3. 获取临时凭证——调用 STS AssumeRole 获得 60 分钟有效期的凭证；
4. 探测执行模式——根据项目配置判断使用 Docker 还是 Code 模式；
5. 在本地启动 Agent——启动 Docker 容器或 Python 进程，并注入凭证与环境变量；
6. 监听文件变化——源文件变更时自动重建/重启；
7. 启动交互式聊天——提供支持流式响应的 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）的实现与文档完全一致。

模式探测优先级

源码中的判断顺序依次是：artifact.image为对象 →handler且非字符串 image → 项目根目录存在Dockerfile→ 默认 Docker。其中最后的默认分支在实现中明确注释为与serverless deploy（coordinator.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(port=port, host='0.0.0.0')

Code 模式的进程管理实现在 dev/code-mode.js。它把handler解析为项目下的绝对路径，用spawn拉起 Python 子进程，进程退出时若非正常关闭会打印退出码；stop()先发SIGTERM等待最多 2 秒优雅退出，超时再用SIGKILL强制结束。如果 Python 可执行文件不存在（ENOENT），会给出明确的安装提示。

资源自动发现

Dev Mode 会自动从 CloudFormation 栈输出中读取已部署的云资源，并把它们作为环境变量注入本地 Agent，从而使本地版本连接到与线上完全相同的 gateway 工具、记忆等资源：

整个过程完全自动，无需手工配置：运行serverless dev时，框架读取 CloudFormation 栈输出并注入取值。这正是本文开头所说"复用已部署资源"能力的关键——本地代码与云端共享同一套 gateway、memory 基础设施引用。

凭证管理

Dev Mode 通过已部署的 IAM 角色自动管理 AWS 凭证，整个过程无需你手动拷贝任何 AccessKey。

工作流程

1. 信任策略设置——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）。

2. STS AssumeRole——获得临时凭证（AccessKeyId、SecretAccessKey、SessionToken），有效期 60 分钟。

3. 自动刷新——当凭证剩余时间不足 10 分钟，且又有文件变更触发重建时，会自动重新获取凭证。判断阈值实现在areCredentialsExpiring()（默认阈值 10 分钟）；每次重建前#refreshCredentialsIfNeeded()都会检查凭证是否即将过期。

4. 重试逻辑——凭证获取最多重试 10 次，采用指数退避，以应对 IAM 传播延迟。退避计算见calculateBackoffDelay()：基础延迟 5 秒、指数递增、上限 30 秒。

一个值得注意的工程细节：信任策略传播

源码在更新信任策略后有一段明确的等待逻辑：IAM 信任策略传播大约需要 10～20 秒，而第一次 AssumeRole 调用必须等传播完成——因为一次过早调用返回的AccessDenied会被 STS 负向缓存数分钟，导致后续所有重试都失败。因此 dev/index.js 中在调用UpdateAssumeRolePolicyCommand后固定等待TRUST_POLICY_PROPAGATION_WAIT_MS = 10000（10 秒）。

此外，源码还专门处理了 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 进程/容器注入以下环境变量。

总是注入

模式专属

自动发现（若已部署）

用户自定义

在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 Events（SSE）实时流式渲染响应；
• 会话：每次启动 Dev Mode 都会生成新的会话 ID（UUID）；当文件变化触发重建时，会话自动重置（源码在每次重建完成后重新randomUUID()）；
• 退出：按Ctrl+C优雅退出（停止容器/进程并清理资源）。

从源码看，聊天期间如果已有请求正在执行（#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 命令：

若本机安装的 Python 版本与配置的 runtime 不一致，Dev Mode 会输出版本不匹配警告。从仓库的配置校验源码看，AgentCore code 部署所支持的 Python runtime 为python3.10～python3.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.txt

Dev 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 refused"

Agent 仍在启动中。等待数秒，待容器/进程完成初始化并开始监听端口后再试。源码中对这类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