mcpField
A
agents-deploy

agents-deploy

github.com/aws云与 DevOps3.3k2.0k 次安装1 天前更新
代码仓库

关于 agents-deploy

agents-deploy 是用于部署 AgentCore Agent，或排查部署失败的开发者技能。它涵盖部署前检查、预览、目标环境选择以及版本回滚。

主要功能

  1. 01验证配置与 IAM 权限
  2. 02预览部署资源和差异
  3. 03排查部署错误
  4. 04部署到指定目标
  5. 05回滚或固定版本

适用场景

  1. 01部署前检查 AWS 区域和模型访问
  2. 02查看部署将创建的资源
  3. 03根据日志诊断部署失败
  4. 04将 Agent 部署到暂存或生产目标

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aws/agent-toolkit-for-aws --skill agents-deploy

安装后在 Claude Code 中输入/agents-deploy确认已加载。

附带文件references/versioning.md

详细介绍

deploy

将 AgentCore Agent 部署到 AWS，或诊断部署失败的原因。

适用场景

  • 你已准备好部署，想先验证配置
  • agentcore deploy 执行失败并报错
  • 你想预览部署将创建的内容，但不实际执行部署
  • 你想部署到特定目标（暂存环境、生产环境）
  • 你需要回滚到之前的版本、固定到特定版本，或设置金丝雀部署

输入

$ARGUMENTS 为可选项：

/agents-deploy                     # interactive — pre-flight check or diagnose failure
/agents-deploy preflight           # validate config and IAM before deploying
/agents-deploy diagnose            # diagnose a failed deploy (paste error or read logs)
/agents-deploy preview             # show what deploy will create without deploying
/agents-deploy rollback            # roll back to a previous version

流程

步骤 0：验证 CLI 版本

运行 agentcore --version。此技能要求版本为 v0.9.0 或更高。如果版本较旧，请告知开发者先运行 agentcore update。

步骤 1：确定情况

如果 agentcore/agentcore.json 和 agentcore/aws-targets.json 存在，请读取它们。

询问（或根据上下文推断）：

“你目前是：

  1. 即将部署，想先检查所有内容
  2. 遇到部署失败——你看到的错误是什么？
  3. 需要回滚或固定到特定版本？”

如果开发者需要版本管理、回滚或金丝雀部署，请加载 references/versioning.md 并遵循其中的说明。

路径 A：部署前验证

运行 agentcore deploy 前，执行以下检查：

检查 1：验证配置文件

向开发者提供以下命令：

agentcore validate

这可以在 CDK 启动前捕获格式错误的 agentcore.json。

检查 2：验证区域一致性

部署失败最常见的原因是区域不匹配。向开发者提供以下命令以进行验证：

# Your configured AWS region
aws configure get region

# The region in your deployment target
cat agentcore/aws-targets.json

# The account you're actually authenticated as
aws sts get-caller-identity

aws-targets.json 中的 region 必须与 aws configure 的默认区域一致。account 必须与 sts get-caller-identity 返回的账户 ID 一致。

检查 3：验证 Bedrock 模型访问权限

向开发者提供以下命令，以检查其所在区域已启用的模型：

aws bedrock list-foundation-models --region $(aws configure get region) \
  --query 'modelSummaries[?modelLifecycle.status==`ACTIVE`].modelId' \
  --output table

跨区域推理配置文件 ID 使用地理区域前缀（us.、eu.、apac.）或 global. 来控制推理运行的位置。CLI 默认生成 global.（例如，global.anthropic.claude-sonnet-4-5-20250929-v1:0），该前缀会将请求路由到任何商业区域。地理区域前缀可将推理限制在相应地理区域内（例如，eu. 只会在欧盟区域内运行）。所有前缀都要求在配置文件涵盖的每个目标区域中启用模型访问权限。请查阅 Bedrock 文档，了解每个配置文件前缀包含哪些区域。

检查 4：预览待部署内容
agentcore deploy --dry-run
agentcore deploy --diff

--dry-run 会显示将要创建的资源。--diff 会显示 CDK 与当前已部署内容之间的差异。

检查 5：验证 IAM 权限

向开发者说明所需权限，并提供以下验证命令：

aws iam simulate-principal-policy \
  --policy-source-arn $(aws sts get-caller-identity --query Arn --output text) \
  --action-names iam:CreateRole \
  --resource-arns "arn:aws:iam::*:role/*BedrockAgentCore*"
执行部署
agentcore deploy -y          # auto-confirm (alias: agentcore dp -y)
agentcore deploy -y -v       # verbose — shows resource-level events
agentcore deploy --target staging -y   # deploy to a specific target

内存预置说明： 如果项目包含内存资源，部署所需时间会增加 2–5 分钟，以等待内存资源变为 ACTIVE。这是正常现象，并非错误。请检查状态：

agentcore status --type memory

路径 B：诊断部署失败

步骤 B1：查看错误

如果开发者粘贴了错误，请直接进行诊断。如果没有，请读取部署日志：

# View recent deploy logs
ls -lt agentcore/.cli/logs/
cat agentcore/.cli/logs/deploy-*.log 2>/dev/null | tail -100
步骤 B2：匹配已知故障模式

IAM 权限错误：

User: arn:aws:iam::123456789012:user/dev is not authorized to perform: iam:CreateRole

修复方法：附加所需的 IAM 权限（参见上文的检查 5）。部署身份需要对作用域限定为 *BedrockAgentCore* 的角色具有 IAM 写入权限。

未运行 CDK 引导：

This stack uses assets, so the toolkit stack must be deployed to the environment

修复方法：

npx cdk bootstrap aws://<YOUR_ACCOUNT_ID>/<REGION>

ECR 授权错误：

no basic auth credentials
Error response from daemon: Head "https://<YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/..."

修复方法：

aws ecr get-login-password --region <REGION> | \
  docker login --username AWS --password-stdin <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com

部署期间模型访问被拒绝：

ValidationException: The provided model identifier is invalid

修复方法：在 Bedrock 控制台 → 模型访问中启用该模型。确保 agentcore.json 中的模型 ID 与目标区域中已启用的模型一致。

区域不匹配：

Stack ... is in region us-east-1 but the target is us-west-2

修复方法：更新 agentcore/aws-targets.json，使其与 aws configure 的默认区域一致，或运行 aws configure set region <REGION>。

内存卡在 CREATING 状态：

Memory resource is in CREATING state after 10 minutes

这并不常见——正常配置需要 2–5 分钟。请检查：

agentcore status --type memory --json

如果卡住，请尝试移除并重新添加内存资源。

超出服务配额：

LimitExceededException: Account limit for AgentCore runtimes exceeded

修复方法：在 AWS 控制台 → 服务配额 → Amazon Bedrock AgentCore 中申请提高配额。

步骤 B3：修复后重新运行
agentcore deploy -y

如果再次出现相同错误，请检查 agentcore status，查看所有资源的当前状态：

agentcore status
agentcore status --state pending-removal  # resources marked for deletion

部署到多个目标

在 agentcore/aws-targets.json 中定义目标：

[
  {
    "name": "staging",
    "description": "Staging environment",
    "account": "123456789012",
    "region": "us-east-1"
  },
  {
    "name": "production",
    "description": "Production environment",
    "account": "987654321098",
    "region": "us-west-2"
  }
]

部署到特定目标：

agentcore deploy --target staging -y
agentcore deploy --target production -y

输出

  • 预检结果，以及针对发现问题的具体修复方法
  • 部署失败诊断及相应的具体修复方法
  • 修复后要运行的部署命令

评论

支持 Markdown