用 Bedrock AgentCore CLI 把 Agent 部署成全托管服务：configure/launch/invoke 与可观测实操

mkdir agentcore-runtime-quickstart
cd agentcore-runtime-quickstart
python3 -m venv .venv
# Windows 用：.venv\Scripts\activate
source .venv/bin/activate

pip install --upgrade pip
pip install bedrock-agentcore strands-agents bedrock-agentcore-starter-toolkit

# 验证 CLI 可用：
agentcore --help

三个包各司其职：bedrock-agentcore 是运行时 SDK（提供智能体与平台之间的 HTTP 契约），strands-agents 是 AWS 自家的智能体框架（本篇示例用它，换成 LangGraph 等其他框架契约不变），bedrock-agentcore-starter-toolkit 就是 agentcore CLI。装完先跑 aws configure 确认凭证有效，再确认 Bedrock 控制台里模型访问已开通——模型没开通的话，部署上去调用也会报错。

# my_agent.py
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()   # 默认模型，也可指定与工具

@app.entrypoint
def invoke(payload):
    """智能体入口函数"""
    user_message = payload.get("prompt", "Hello!")
    result = agent(user_message)
    return {"result": result.message}

if __name__ == "__main__":
    app.run()

# requirements.txt 两行：
#   bedrock-agentcore
#   strands-agents

契约很简单：用 BedrockAgentCoreApp 包一层，@app.entrypoint 声明入口函数，函数收 payload、返回可序列化的 dict。平台与你的智能体之间就是这套 HTTP 协议，所以无论里面跑的是 Strands 还是 LangGraph 还是裸调模型 API，外层包装一致即可。给智能体加工具也很直接：Strands 的 Agent(tools=[...]) 传入工具函数，工具内部可以用 boto3 访问 AWS 服务。

# 终端 1：启动本地服务
python my_agent.py

# 终端 2：模拟平台调用
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello!"}'
# 预期返回：{"result": "Hello! I\'m here to help..."}

本地服务默认监听 8080，注意先确认端口没被占用。这一步的意义是把「智能体逻辑错误」和「部署问题」分开：本地跑不通就去改代码，别把 bug 带到云上再排查——云上的排查路径要绕经镜像构建与日志检索，反馈循环长得多。工具调用、多轮逻辑、返回结构都在这一步定型。

# 按默认值配置（区域默认 us-west-2）：
agentcore configure -e my_agent.py
#   -e 指定入口文件
#   交互提示一路回车接受默认值即可
#
# 想换区域：
agentcore configure -e my_agent.py -r us-east-1
#
# 产物：隐藏配置文件 .bedrock_agentcore.yaml
#   （区域、执行角色、镜像仓库等都在里面）

configure 做的事：确定入口文件、生成 .bedrock_agentcore.yaml 配置、约定 IAM 执行角色与 ECR 仓库名。真正的资源创建发生在下一步 launch 时——工具会自动创建执行角色、镜像仓库等 AWS 资源，你的账号需要有相应权限（官方建议 AgentCore 相关托管策略加 Bedrock 权限）。区域选择离你的用户近的，模型可用性因区域而异，切换前查一下目标区域的模型支持表。

# 部署（云上 CodeBuild 构建 ARM64 容器，无需本机 Docker）：
agentcore launch
# 输出里记下两样东西：
#   智能体 ARN（形如 arn:aws:bedrock-agentcore:...）
#   CloudWatch 日志组位置

# CLI 调用验证：
agentcore invoke \'{"prompt": "给我讲个笑话"}\'

# 程序化调用（业务后端里这样接）：
import json, uuid, boto3
client = boto3.client(\'bedrock-agentcore\')
resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:...",   # 你的 ARN
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": "你好"}).encode(),
    qualifier="DEFAULT")

launch 的输出 ARN 是后续一切调用的钥匙。程序化调用时 runtimeSessionId 是会话隔离的关键——同一会话 ID 的调用共享上下文，不同 ID 各自独立 microVM，这就是「每会话隔离」在调用方的体现。业务系统接入就是把这段 boto3 调用包进你的服务接口，鉴权、限流、审计都按你们现有的后端规范做，AgentCore 在 AWS 侧兜住运行时的隔离与扩缩。

# 查部署状态：
agentcore status

# 日志在 CloudWatch：
#   /aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT
# 深度追踪：按官方文档开启 CloudWatch
#   Transaction Search 后，可在控制台看
#   每步决策与工具调用的全链路轨迹

# 练习完毕，清理资源：
agentcore destroy

可观测是 AgentCore 相对自建容器最省心的部分：智能体每步推理与工具调用都有轨迹可查，「它为什么调了这个工具」不再靠猜。十月的更新进一步补强治理面：Runtime 新增工具调用前后的生命周期钩子（before/after tool-call，可以做同步的放行或拦截决策）、Identity 新增 Consent Portal（用户同意管理），Gateway 侧增加了私有 CA 证书与可配置限流——这些项以 AWS 十月发行说明为准，按需启用。