序言
在智能体的开发实践中，一个常见现象是，在本地运行流畅的智能体，部署到生产环境后却频繁暴露出工程层面的不确定性问题，如执行时长不足、会话状态不稳定、算力资源分配困难、模型访问方式不统一，以及可观测性体系欠缺等。这类问题往往并非源于智能体自身的逻辑缺陷，而是由运行环境与模型平台之间的差异所引发。
随着快时尚电商企业对于自主式智能体的研发需求与日俱增，Claude Agent SDK 逐渐成为了智能体工具箱的重要组成部分，为构建具备多步推理与工具调用能力的自主式智能体提供了良好的开发体验，而 Amazon Bedrock 作为主流大模型的托管平台，为 Nova、Claude、DeepSeek、Qwen、Mistral 等系列模型提供了统一、安全且可控的推理服务。若将二者结合，并依托 AgentCore Runtime 环境，开发者便可在保留本地开发流畅度的同时，让智能体以较低的改造成本适应生产环境对稳定性、隔离性与可观测性的要求。
本文旨在通过一条务实的技术路径，介绍如何基于 AgentCore Runtime 与 Bedrock 模型平台，搭建能够直接承载 Claude Agent SDK 智能体的生产级运行环境。内容将涵盖本地开发、模型调用、环境配置、部署流程及常见问题排查等关键环节，以期帮助开发者更顺畅地将自主式智能体应用于实际业务场景。
希望本文能为正在或计划实施智能体生产落地的团队提供一份可行的技术参考，助力智能体部署过程更加可控、结果更可预期。
Amazon Bedrock AgentCore Runtime
在本地让智能体运行成功后，下一步是将其部署到一个稳定、可扩展、可观测的生产环境中。Amazon Bedrock AgentCore 正是为此设计的运行底座，它为智能体应用提供了统一的开发模型、工具集与托管执行环境。其中，AgentCore Runtime 是一个专为智能体工作负载构建的无服务器执行环境。
与传统容器不同，AgentCore Runtime 采用基于 microVM 的隔离方式，为智能体运行提供安全、可靠、高效、并行且可预测的执行环境。其核心能力包括：
- 每次调用拥有独立的 microVM 环境，确保不同用户、任务和智能体之间完全隔离；
- 单次执行最长可达 8 小时，适合需要长时间推理、分析或外部工具调用的智能体；
- 框架无关的运行方式：无论你使用 Strands Agents、Claude Agent SDK、LangGraph、CrewAI 或自定义框架，均可通过 AgentCore Runtime 运行，只需提供符合规范的入口脚本。
AgentCore SDK 目前支持 Python、TypeScript等，使智能体能够在无服务器环境中运行，而无需自行构建或维护底层基础设施，从而有效降低部署与运维的复杂度。
Claude Agent SDK
Claude Agent SDK 是智能体开发引擎与模块化基础设施，其定位既非简单的提示词封装工具，也非低代码拖拽平台，而是一个用于构建生产就绪具备自主探索与执行能力的智能体应用的完整方案和技术底座。
它提供了包括上下文管理（记忆/会话）、工具调用、任务执行、权限与安全以及状态管理在内的核心支持，帮助开发者系统化地搭建稳定、可扩展的智能体应用。
该 SDK 同时提供 Python 和 TypeScript 版本，适用于后端服务、脚本自动化、Web 应用等多种场景。
借助 Claude Agent SDK，开发者可以大幅减少在“底层架构组件（如状态机、工作流引擎、上下文持久化、工具调用链路等）”上的实现负担，从而更专注于业务逻辑与智能体行为设计（如规划、决策、工具使用策略），能够更快速地从原型阶段推进到生产部署。
对于需要长上下文支持、复杂交互、多工具调用、严格安全权限控制或高稳定性部署的应用场景，例如代码生成与执行、文档分析、自动化流程、报告生成、RAG 与长文档理解等，Claude Agent SDK 提供了非常适宜的基础设施支持。
简而言之，Claude Agent SDK 的核心价值在于它是一个代码优先、面向生产、功能全面（涵盖工具调用、记忆、安全与可扩展性） 的智能体开发基础框架，帮助团队高效构建、迭代并交付可靠的企业级智能体应用。
Bedrock 模型平台
Bedrock 模型平台是 AWS 提供的全托管生成式 AI 服务，能够统一访问多家领先模型，并内置了企业级的安全、治理与扩展能力。
它让开发者无需自建基础设施即可灵活调用 Nova、Claude、DeepSeek、Qwen、Mistral 等前沿大模型，并支持针对私有数据的定制化微调与检索增强（RAG）。
Claude Agent SDK 结合 Bedrock 模型平台使用时，能直接依托其高可用、合规且全球部署的推理基础设施，确保智能体服务的稳定与低延迟。
Claude Agent SDK 可通过 Bedrock 无缝切换或组合不同模型（如 Nova、Claude、DeepSeek、Qwen、Mistral 等），从而根据任务场景优化成本与效果，提升智能体策略的灵活性。
借助 Bedrock 内置的监控、审计与权限控制，使用 Claude Agent SDK 开发的智能体可自然符合企业安全规范，实现工具调用与数据访问的可追踪、可管控。
该组合大幅降低了生产级智能体的运维门槛，让开发者更专注于智能体的行为逻辑，而将模型部署、扩缩容与合规保障交由平台托管。
Global CRIS vs GEO CRIS
使用Global CRIS（例如 global.anthropic.claude-sonnet-4-5-20250929-v1:0），可以实现在任意支持 Bedrock 的 AWS 区域调用同一模型，无需为不同区域维护多个模型 ID，简化了全球部署的管理复杂度。
该特性提升了 AI 推理服务的全球可扩展性和弹性，当一个区域出现服务中断或延迟时，请求可以路由至其他可用区域，保障了应用程序的高可用性。
它降低了在全球多个区域部署和维护 AI 应用的成本与运营负担，开发者只需使用一个统一的模型标识，即可构建具备跨区域容灾和低延迟推理能力的全球化应用架构。
|
特性 |
Global CRIS (全球跨区域推理) |
GEO CRIS (特定地域跨区域推理配置) |
| 1 |
路由范围 |
全球所有AWS区域 |
特定的地理范围内（如美国、欧洲等） |
| 2 |
配置前缀 |
global.anthropic.claude… |
地理前缀（如 us., eu., ap.）+ anthropic.claude… |
| 3 |
主要优势 |
容量最大、弹性最强、吞吐量最高 |
在特定地理边界内提供容灾和流量分发 |
| 4 |
适用场景 |
对全球可用性、处理峰值流量有极高要求的应用 |
需要遵守数据驻留法规、将流量限制在大洲内的应用 |
| 5 |
使用成本 |
通常比单区域或地理CRIS更具成本效益 |
根据具体区域定价 |
它们是如何工作的？
无论 Global CRIS 还是 GEO CRIS，都属于AWS的“跨区域推理”功能。当你从某个“源区域”发出请求时，Amazon Bedrock会自动根据你选择的配置文件，将请求路由到其“目标区域”列表中的一个最佳区域进行处理，以此提升性能、可用性和吞吐量。
如何选择使用哪一种？
选择哪种方式主要取决于具体需求：
选择Global CRIS：如果应用需要最高的全球可用性、应对突发流量峰值的能力，并且数据可以在全球范围内路由。
选择GEO CRIS：如果业务有严格的数据驻留或合规要求，必须将数据处理限制在某个地理边界内（如欧盟境内），同时仍需要在该区域内具备高可用性。
总而言之，你可以将 GEO CRIS 视为在一个大洲或国家内进行负载均衡和容灾，而 Global CRIS 则是在全球范围内进行资源调配和优化，本文的操作示例将选用Global CRIS。
操作示例
1.架构说明
┌─────────────────────────────────────────────────────┐
│ 用户请求
│ User Request
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AgentCore Runtime
│ （托管基础设施、自动扩缩容、监控）
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ BedrockAgentCoreApp实例
│ • 接收HTTP/MCP请求
│ • 管理会话状态
│ • 处理内存（STM）
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ main函数入口
│ （@app.entrypoint装饰的异步入口点）
│ • 解析payload参数
│ • 调度示例函数执行
│ • 处理异常和返回结果
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 函数调度
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Claude Agent SDK query函数
│ • 构造Claude请求参数
│ • 处理异步消息流
│ • 管理工具调用和结果
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Claude Agent SDK 处理层
│ • AssistantMessage: 助手响应
│ • ResultMessage: 结果和成本
│ • ToolMessage: 工具调用结果
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Bedrock Claude 模型
│ （Sonnet 4.5推理，Global CRIS）
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 工具执行层
│ • Read工具：文件读取
│ • Write工具：文件写入
│ • 其他自定义工具
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 响应处理
│ • 提取TextBlock内容
│ • 格式化输出
│ • 计算和显示成本
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 返回BedrockAgentCoreApp
│ • 异步函数执行完成
│ • 控制权返回给装饰器
│ • 生成HTTP/MCP响应
└────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 最终响应
│ • Bedrock AgentCore封装
│ • 返回给用户
└─────────────────────────────────────────────────────┘
2.本地运行
安装 Claude Agent SDK，并同时安装 Claude Code。
- claude-agent-sdk
- claude-code
验证 Claude Code 是否正常工作
Claude Agent SDK 依赖 Claude Code，支持订阅和 API 模式。下面将进行 Claude Code 与 Bedrock 集成，关键环境变量如下：
set AWS_BEARER_TOKEN_BEDROCK=<your_bedrock_api_key>
set CLAUDE_CODE_USE_BEDROCK=1
set AWS_REGION=<your_aws_region>
set ANTHROPIC_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0
set ANTHROPIC_SMALL_FAST_MODEL=global.anthropic.claude-haiku-4-5-20251001-v1:0
export AWS_BEARER_TOKEN_BEDROCK=<your_bedrock_api_key>
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=<your_aws_region>
export ANTHROPIC_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0
export ANTHROPIC_SMALL_FAST_MODEL=global.anthropic.claude-haiku-4-5-20251001-v1:0
可以通过 Claude Code CLI 的 /model 命令验证模型配置。
> /model
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Select model
Switch between Claude models. Applies to this session and future Claude Code sessions. For other/previous model names, specify with --model.
1. Default (recommended) Use the default model (currently Sonnet 4.5) · $3/$15 per Mtok
2. Opus Opus 4.5 · Most capable for complex work · $5/$25 per Mtok
3. Haiku Haiku 4.5 · Fastest for quick answers · $1/$5 per Mtok
> 4. global.anthropic.claude-sonnet-4-5-20250929-v1:0 Custom model √
运行本地示例代码
使用 Claude Agent SDK 运行后会输出 Claude 的回答结果。
claude_agent_sdk_on_local_machine.py
#!/usr/bin/env python3
import anyio
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
ResultMessage,
TextBlock,
query,
)
# 用来缓存 “示例二” 助理的输出内容
system_prompt_output = ""
async def demo_basic_query():
print("✨ 【示例一：基础问答】")
print("准备向智能体提一个经典勾股定理问题...\n")
async for message in query(prompt="勾如果是8，股如果是15，那么弦是多少?"):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"✨ 助理回答：{block.text}")
print("\n---\n")
async def demo_system_prompt():
global system_prompt_output
print("✨ 【示例二：系统提示与角色设定】")
print("让助理以“简单解释型”角色来说明一个概念...\n")
options = ClaudeAgentOptions(
system_prompt="你是一位擅长把复杂概念说得浅显易懂的老师，请用一句话回答。",
max_turns=1,
)
async for message in query(
prompt="请用一句话解释什么是勾股定理。",
options=options,
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"✨ 助理回答：{block.text}")
# 保存内容，用于写入 科普.txt
system_prompt_output = block.text
print("\n---\n")
async def demo_tool_usage():
print("✨ 【示例三：工具调用】")
print("让助理使用工具创建科普文件...\n")
options = ClaudeAgentOptions(
allowed_tools=["Read", "Write"],
system_prompt="你是一位贴心的文件小助手。",
)
# 直接创建科普.txt
global system_prompt_output
write_science_file_prompt = f"创建一个名为 科普.txt 的文件，内容为：'{system_prompt_output}'"
print("✨ 正在将示例二的输出写入 科普.txt...\n")
async for message in query(
prompt=write_science_file_prompt,
options=options,
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"✨ 助理消息：{block.text}")
elif isinstance(message, ResultMessage) and message.total_cost_usd > 0:
print(f"\n✨ 本次调用费用：${message.total_cost_usd:.4f}")
print("\n---\n")
async def main():
print("✨ Claude Agent SDK 示例开始运行！\n")
await demo_basic_query()
await demo_system_prompt()
await demo_tool_usage()
print("✨ 所有示例已执行完毕！")
if __name__ == "__main__":
anyio.run(main)
运行命令：
python claude_agent_sdk_on_local_machine.py
运行结果：
✨ Claude Agent SDK 示例开始运行！
✨ 【示例一：基础问答】
准备向智能体提一个经典勾股定理问题...
✨ 助理回答：这是一个勾股定理的问题。
已知：
- 勾（直角三角形的一条直角边）= 8
- 股（直角三角形的另一条直角边）= 15
- 弦（斜边）= ?
根据勾股定理：弦² = 勾² + 股²
计算：
弦² = 8² + 15²
弦² = 64 + 225
弦² = 289
弦 = √289 = 17
所以，**弦是 17**。
---
✨ 【示例二：系统提示与角色设定】
让助理以“简单解释型”角色来说明一个概念...
✨ 助理回答：勾股定理就是直角三角形两条直角边的平方和等于斜边的平方，用公式表示就是 a² + b² = c²。
---
✨ 【示例三：工具调用】
让助理使用工具创建科普文件...
✨ 正在将示例二的输出写入 科普.txt...
✨ 助理消息：我来帮你创建这个文件。
✨ 助理消息：已成功创建文件 `科普.txt`，内容为关于勾股定理的科普说明！文件已保存到 `/tmp/科普.txt`。
✨ 本次调用费用：$0.0196
---
✨ 所有示例已执行完毕！
2.本地包装
接下来，使用的 AgentCore Python SDK 为代码添加 AgentCore Runtime 包装，使其可以部署到 AgentCore Runtime，只需添加几行代码，即可让现有智能体支持 AgentCore Runtime。
claude_agent_sdk_on_agentcore_runtime.py
#!/usr/bin/env python3
import anyio
from bedrock_agentcore import BedrockAgentCoreApp
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
ResultMessage,
TextBlock,
query,
)
# 创建 AgentCore 应用实例
app = BedrockAgentCoreApp()
# 用来缓存 “示例二” 助理的输出内容
system_prompt_output = ""
async def demo_basic_query():
print("✨ 【示例一：基础问答】")
print("准备向智能体提一个经典勾股定理问题...\n")
async for message in query(prompt="勾如果是8，股如果是15，那么弦是多少?"):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"✨ 助理回答：{block.text}")
print("\n---\n")
async def demo_system_prompt():
global system_prompt_output
print("✨ 【示例二：系统提示与角色设定】")
print("让助理以“简单解释型”角色来说明一个概念...\n")
options = ClaudeAgentOptions(
system_prompt="你是一位擅长把复杂概念说得浅显易懂的老师，请用一句话回答。",
max_turns=1,
)
async for message in query(
prompt="请用一句话解释什么是勾股定理。",
options=options,
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"✨ 助理回答：{block.text}")
system_prompt_output = block.text
print("\n---\n")
async def demo_tool_usage():
print("✨ 【示例三：工具调用】")
print("让助理使用工具创建科普文件...\n")
options = ClaudeAgentOptions(
allowed_tools=["Read", "Write"],
system_prompt="你是一位贴心的文件小助手。",
)
global system_prompt_output
write_science_file_prompt = (
f"创建一个名为 科普.txt 的文件，内容为：'{system_prompt_output}'"
)
print("✨ 正在将示例二的输出写入 科普.txt...\n")
async for message in query(
prompt=write_science_file_prompt,
options=options,
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"✨ 助理消息：{block.text}")
elif isinstance(message, ResultMessage) and message.total_cost_usd > 0:
print(f"\n✨ 本次调用费用：${message.total_cost_usd:.4f}")
print("\n---\n")
# 使用 AgentCore 的 entrypoint
@app.entrypoint
async def main(payload: dict=None):
print("✨ Claude Agent SDK 示例开始运行！\n")
await demo_basic_query()
await demo_system_prompt()
await demo_tool_usage()
print("✨ 所有示例已执行完毕！")
# AgentCore Runtime 入口
if __name__ == "__main__":
app.run()
代码包装增加了以下内容，可以看出，几乎不需要修改原有代码，就可以将 Claude Agent SDK 应用包装成 AgentCore Runtime 应用：
from bedrock_agentcore import BedrockAgentCoreApp
app = BedrockAgentCoreApp()
@app.entrypoint
async def main(payload: dict=None):
...
运行命令：
python claude_agent_sdk_on_agentcore_runtime.py
此时服务将在本地 8080 端口启动，可通过以下命令进行测试：
curl -X POST http://localhost:8080/invocations -H "Content-Type:application/json" -d "{}"
运行结果：
✨ Claude Agent SDK 示例开始运行！
✨ 【示例一：基础问答】
准备向智能体提一个经典勾股定理问题...
✨ 助理回答：这是一个关于勾股定理的问题。
根据勾股定理：**勾² + 股² = 弦²**
已知：
- 勾 = 8
- 股 = 15
计算：
- 8² + 15² = 弦²
- 64 + 225 = 弦²
- 289 = 弦²
- 弦 = √289 = **17**
所以，**弦是17**。
这是一个经典的勾股数组合(8, 15, 17)。
---
✨ 【示例二：系统提示与角色设定】
让助理以“简单解释型”角色来说明一个概念...
✨ 助理回答：勾股定理是指在直角三角形中,两条直角边的平方和等于斜边的平方(即 a² + b² = c²)。
---
✨ 【示例三：工具调用】
让助理使用工具创建科普文件...
✨ 正在将示例二的输出写入 科普.txt...
✨ 助理消息：我来帮你创建这个文件。
✨ 助理消息：由于这是一个新文件，让我直接创建它：
✨ 助理消息：我需要在当前允许的工作目录中创建文件。让我在当前工作目录创建这个文件：
✨ 助理消息：完成了！我已经在当前工作目录（``）中成功创建了 **科普.txt** 文件，内容为：
```
勾股定理是指在直角三角形中,两条直角边的平方和等于斜边的平方(即 a² + b² = c²)。
```
文件已经创建好了！📝
✨ 本次调用费用：$0.0368
---
✨ 所有示例已执行完毕！
{"timestamp": "2025-12-07T17:43:33.983Z", "level": "INFO", "message": "Invocation completed successfully (38.683s)", "logger": "bedrock_agentcore.app", "requestId": "f68d3ed5-387b-432e-8810-cdc66ef0c79f"}
3.云端托管
AgentCore Starter Toolkit 是一个命令行工具，可显著简化部署流程。
前置条件
- Python 3.10 或更高版本
- 已配置 AWS 凭证
- 已安装 Amazon Bedrock AgentCore SDK
IAM 权限
部署智能体需要两组 IAM 权限：
- 开发者角色：允许创建与管理 AgentCore 资源；
- 执行角色：为运行时智能体授予必要权限。
设置 auto_create_execution_role=True 时，Toolkit 会自动创建执行角色，但开发者角色仍需手动配置。
开始部署
安装 Toolkit：
pip install bedrock-agentcore-starter-toolkit
agentcore --help
创建依赖文件 requirements.txt：
bedrock-agentcore==1.0.4
claude-agent-sdk==0.1.3
配置 AgentCore
运行命令
agentcore configure -e claude_agent_sdk_on_agentcore_runtime.py
-e (或 -entrypoint) 参数用于指定您智能体的入口点文件，即包含您智能体核心代码的 Python 文件。
此命令将为智能体创建用于部署到 AWS 的配置。
除非有特定需求，否则请接受所有默认值。
Configuring Bedrock AgentCore...
✓ Using file: claude_agent_sdk_on_agentcore_runtime.py
🏷️ Inferred agent name: claude_agent_sdk_on_agentcore_runtime
Press Enter to use this name, or type a different one (alphanumeric without '-')
Agent name [claude_agent_sdk_on_agentcore_runtime]:
✓ Using agent name: claude_agent_sdk_on_agentcore_runtime
🔍 Detected dependency file: requirements.txt
Press Enter to use this file, or type a different path (use Tab for autocomplete):
Path or Press Enter to use detected dependency file: requirements.txt
✓ Using requirements file: requirements.txt
🚀 Deployment Configuration
Warning: Direct Code Deploy deployment unavailable (zip utility not found). Falling back to Container deployment.
Select deployment type:
1. Container - Docker-based deployment
✓ Deployment type: Container
🔐 Execution Role
Press Enter to auto-create execution role, or provide execution role ARN/name to use existing
Execution role ARN/name (or press Enter to auto-create):
✓ Will auto-create execution role
🏗️ ECR Repository
Press Enter to auto-create ECR repository, or provide ECR Repository URI to use existing
ECR Repository URI (or press Enter to auto-create):
✓ Will auto-create ECR repository
🔐 Authorization Configuration
By default, Bedrock AgentCore uses IAM authorization.
Configure OAuth authorizer instead? (yes/no) [no]:
✓ Using default IAM authorization
🔒 Request Header Allowlist
Configure which request headers are allowed to pass through to your agent.
Common headers: Authorization, X-Amzn-Bedrock-AgentCore-Runtime-Custom-*
Configure request header allowlist? (yes/no) [no]:
✓ Using default request header configuration
Configuring BedrockAgentCore agent: claude_agent_sdk_on_agentcore_runtime
💡 No container engine found (Docker/Finch/Podman not installed)
✓ Default deployment uses CodeBuild (no container engine needed), For local builds, install Docker, Finch, or Podman
Memory Configuration
Tip: Use --disable-memory flag to skip memory entirely
✅ MemoryManager initialized for region: us-east-1
No existing memory resources found in your account
Options:
• Press Enter to create new memory
• Type 's' to skip memory setup
Your choice:
✓ Short-term memory will be enabled (default)
• Stores conversations within sessions
• Provides immediate context recall
Optional: Long-term memory
• Extracts user preferences across sessions
• Remembers facts and patterns
• Creates session summaries
• Note: Takes 120-180 seconds to process
Enable long-term memory? (yes/no) [no]: no
✓ Using short-term memory only
Will create new memory with mode: STM_ONLY
Memory configuration: Short-term memory only
Network mode: PUBLIC
Generated Dockerfile: .bedrock_agentcore\claude_agent_sdk_on_agentcore_runtime\Dockerfile
Setting 'claude_agent_sdk_on_agentcore_runtime' as default agent
┌────────────────────────────────── Configuration Success ─────────────────────────────────────────────┐
│ Agent Details │
│ Agent Name: claude_agent_sdk_on_agentcore_runtime │
│ Deployment: container │
│ Region: us-east-1 │
│ Account: │
│ │
│ Configuration │
│ Execution Role: Auto-create │
│ ECR Repository: Auto-create │
│ Network Mode: Public │
│ ECR Repository: Auto-create │
│ Authorization: IAM (default) │
│ │
│ │
│ Memory: Short-term memory (30-day retention) │
│ │
│ │
│ Config saved to: .bedrock_agentcore.yaml │
│ │
│ Next Steps: │
│ agentcore launch │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
配置后将生成 .bedrock_agentcore.yaml 文件。
修改 Dockerfile 以安装 Claude Code
在 .bedrock_agentcore/ 目录中，修改Dockerfile：
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
WORKDIR /app
# 所有环境变量集中在一个层中
ENV UV_SYSTEM_PYTHON=1 \
UV_COMPILE_BYTECODE=1 \
UV_NO_PROGRESS=1 \
PYTHONUNBUFFERED=1 \
DOCKER_CONTAINER=1 \
AWS_REGION=us-east-1 \
AWS_DEFAULT_REGION=us-east-1
# 安装 Node.js 和 npm (用于 CLAUDE CODE)
RUN apt-get update && apt-get install -y \
nodejs \
npm \
&& rm -rf /var/lib/apt/lists/*
# 全局安装 Claude Code CLI (用于 CLAUDE CODE)
RUN npm install -g @anthropic-ai/claude-code
COPY requirements.txt requirements.txt
# 从 requirements 文件安装依赖
RUN uv pip install -r requirements.txt
# 安装 AWS OpenTelemetry 发行版
RUN uv pip install aws-opentelemetry-distro>=0.10.1
# 设置环境变量以标识在 Docker 容器中运行，用于主机绑定逻辑
ENV DOCKER_CONTAINER=1
# 创建非 root 用户
RUN useradd -m -u 1000 bedrock_agentcore
USER bedrock_agentcore
# 暴露端口
EXPOSE 9000
EXPOSE 8000
EXPOSE 8080
# 复制整个项目 (遵循 .dockerignore 规则)
COPY . .
# 启动应用（带 OpenTelemetry 监控）
CMD ["opentelemetry-instrument", "python", "-m", "claude_agent_sdk_on_agentcore_runtime"]
这样，部署时会自动安装 Claude Code CLI 以及其他所需组件。
启动部署
运行命令：
agentcore launch -a claude_agent_sdk_on_agentcore_runtime \
--env CLAUDE_CODE_USE_BEDROCK=1 \
--env AWS_BEARER_TOKEN_BEDROCK=<your_bedrock_api_key> \
--env DEBUG=true \
--env ANTHROPIC_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0 \
--env ANTHROPIC_SMALL_FAST_MODEL=global.anthropic.claude-haiku-4-5-20251001-v1:0
部署完成后，检查AgentCore Runtime的环境变量是否正确：
检查相关组件是否均已创建：
- AgentCore Runtime
- Short-Term Memory
- ECR Repository
- IAM Roles and Policies
进行测试：
可以在 CloudWatch 日志中查看调用详情，点击“Logs”：
点击“Start tailing”
可以通过“Live Tail”辅助调试
经验总结
- 大多数无服务器平台只允许运行几分钟，而 AgentCore Runtime 允许运行 长达 8 小时！ 这意味着智能体可以执行深度研究、长时间工作流或大规模数据处理任务，而无需担心超时。
- 只需几行代码：导入、装饰、运行，无需重写智能体或调整架构，非常灵活。
- 本地环境和生产运行有所不同，生产环境中同时有多个用户请求时，microVM 隔离意味着每次调用都有独立环境， 没有共享状态，没有内存泄漏，没有相互干扰。
结语
通过本文介绍的方案，“本地应用开发”与“生产环境部署”之间的鸿沟得以显著缩小。部署过程变得简单，仅需少量代码调整与几条命令，即可将 Claude Agent SDK 智能体迁移至 AgentCore Runtime 上运行。AgentCore 的包装模式尊重原有代码结构，不强制开发者更换框架或改写业务逻辑，极大降低了生产化成本。
对于真正需要长时间推理、多步骤任务执行与工具链协作的智能体来说，会话隔离能力与最长 8 小时的执行窗口并非附加价值，而是支持“自主式探索型智能体”顺利运行的关键基础。依托 Bedrock 模型平台提供的统一、稳定、安全的模型调用体系，企业即可在一个可控、可观测、可扩展的环境中，让智能体真正走向生产级落地。
*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。
本篇作者
AWS 架构师中心： 云端创新的引领者
探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用
|
 |
