agents-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

deploy

部署

Deploy your AgentCore agent to AWS, or diagnose why a deploy failed.

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

When to use

使用场景

You're ready to deploy and want to validate config first
```
agentcore deploy
```
failed with an error
You want to preview what deploy will create without actually deploying
You want to deploy to a specific target (staging, production)
You need to roll back to a previous version, pin to a specific version, or set up canary deployments

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

Input

输入参数

$ARGUMENTS

is optional:

/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

$ARGUMENTS

为可选参数：

/agents-deploy                     # 交互式模式——预部署检查或诊断部署失败
/agents-deploy preflight           # 部署前验证配置和IAM权限
/agents-deploy diagnose            # 诊断部署失败（粘贴错误信息或读取日志）
/agents-deploy preview             # 预览部署将创建的资源，但不实际执行部署
/agents-deploy rollback            # 回滚到之前的版本

Process

流程

Step 0: Verify CLI version

步骤0：验证CLI版本

Run

agentcore --version

. This skill requires v0.9.0 or later. If the version is older, tell the developer to run

agentcore update

before proceeding.

运行

agentcore --version

。该技能需要v0.9.0或更高版本。如果版本较旧，请告知开发者先运行

agentcore update

再继续。

Step 1: Determine the situation

步骤1：确定当前场景

Read

agentcore/agentcore.json

and

agentcore/aws-targets.json

if they exist.

Ask (or infer from context):

"Are you:

About to deploy and want to check everything first

Dealing with a failed deploy — what error did you see?

Needing to roll back or pin a specific version?"

If the developer needs versioning, rollback, or canary deployment, load

references/versioning.md

and follow its instructions.

读取

agentcore/agentcore.json

和

agentcore/aws-targets.json

（如果存在）。

询问（或从上下文推断）：

"你当前的情况是：

即将部署，想要先检查所有配置

正在处理部署失败——你遇到了什么错误？

需要回滚或固定到特定版本？"

如果开发者需要版本管理、回滚或金丝雀部署，请加载

references/versioning.md

并按照其中的说明操作。

Path A: Pre-flight validation

路径A：预部署验证

Run these checks before

agentcore deploy

在执行

agentcore deploy

前运行以下检查：

Check 1: Validate config files

检查1：验证配置文件

Show the developer this command to run:

bash

agentcore validate

This catches malformed

agentcore.json

before CDK even starts.

告知开发者运行以下命令：

bash

agentcore validate

这会在CDK启动前捕获格式错误的

agentcore.json

。

Check 2: Verify region alignment

检查2：验证区域一致性

The most common deploy failure is a region mismatch. Show the developer these commands to verify:

bash

undefined

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

bash

undefined

Your configured AWS region

你配置的AWS区域

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


The `region` in `aws-targets.json` must match your `aws configure` default region. The `account` must match the account ID from `sts get-caller-identity`.

aws sts get-caller-identity


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

Check 3: Verify Bedrock model access

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

Show the developer this command to check enabled models in their region:

bash

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

Cross-region inference profile IDs use a geographic prefix (

us.

eu.

apac.

) or

global.

to control where inference runs. The CLI scaffolds

global.

by default (e.g.,

global.anthropic.claude-sonnet-4-5-20250929-v1:0

), which routes to any commercial region. Geographic prefixes keep inference within that geography (e.g.,

eu.

stays in EU regions). All prefixes require model access enabled in every destination region the profile covers. Check the Bedrock docs for which regions are included in each profile prefix.

告知开发者运行以下命令检查其区域内已启用的模型：

bash

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文档了解每个配置文件前缀包含哪些区域。

Check 4: Preview what will be deployed

检查4：预览将部署的资源

bash

agentcore deploy --dry-run
agentcore deploy --diff

--dry-run

shows what resources will be created.

--diff

shows the CDK diff against what's currently deployed.

bash

agentcore deploy --dry-run
agentcore deploy --diff

--dry-run

会显示将创建的资源。

--diff

会显示CDK与当前已部署资源的差异。

Check 5: Verify IAM permissions

检查5：验证IAM权限

Show the developer the permissions needed and this verification command:

bash

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*"

告知开发者所需的权限以及以下验证命令：

bash

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*"

Run the deploy

执行部署

bash

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

Memory provisioning note: If your project includes memory, deploy takes 2–5 minutes longer while the memory resource becomes ACTIVE. This is normal — not an error. Check status:

bash

agentcore status --type memory

bash

agentcore deploy -y          # 自动确认（别名：agentcore dp -y）
agentcore deploy -y -v       # verbose模式——显示资源级别的事件
agentcore deploy --target staging -y   # 部署到特定目标环境

内存配置说明： 如果你的项目包含内存资源，部署时间会增加2-5分钟，直到内存资源变为ACTIVE状态。这是正常现象，并非错误。可通过以下命令检查状态：

bash

agentcore status --type memory

Path B: Diagnose a failed deploy

路径B：诊断部署失败

Step B1: Read the error

步骤B1：读取错误信息

If the developer pasted an error, diagnose it directly. If not, read the deploy logs:

bash

undefined

如果开发者粘贴了错误信息，直接进行诊断。否则，读取部署日志：

bash

undefined

View recent deploy logs

查看最近的部署日志

ls -lt agentcore/.cli/logs/ cat agentcore/.cli/logs/deploy-*.log 2>/dev/null | tail -100

undefined

ls -lt agentcore/.cli/logs/ cat agentcore/.cli/logs/deploy-*.log 2>/dev/null | tail -100

undefined

Step B2: Match to known failure patterns

步骤B2：匹配已知失败模式

IAM permission error:

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

Fix: Attach the required IAM permissions (see Check 5 above). The deploying identity needs IAM write access scoped to

*BedrockAgentCore*

roles.

CDK bootstrap not run:

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

Fix:

bash

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

ECR authorization error:

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

Fix:

bash

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

Model access denied during deploy:

ValidationException: The provided model identifier is invalid

Fix: Enable the model in the Bedrock console → Model access. Ensure the model ID in

agentcore.json

matches an enabled model in your target region.

Region mismatch:

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

Fix: Update

agentcore/aws-targets.json

to match your

aws configure

default region, or run

aws configure set region <REGION>

Memory stuck in CREATING:

Memory resource is in CREATING state after 10 minutes

This is unusual — normal provisioning takes 2–5 minutes. Check:

bash

agentcore status --type memory --json

If stuck, try removing and re-adding the memory resource.

Service quota exceeded:

LimitExceededException: Account limit for AgentCore runtimes exceeded

Fix: Request a quota increase in the AWS console → Service Quotas → Amazon Bedrock AgentCore.

IAM权限错误：

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

修复方法：附加所需的IAM权限（参见上述检查5）。执行部署的身份需要对

*BedrockAgentCore*

角色的IAM写入权限。

CDK未执行bootstrap：

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

修复方法：

bash

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/..."

修复方法：

bash

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分钟。检查状态：

bash

agentcore status --type memory --json

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

服务配额超出：

LimitExceededException: Account limit for AgentCore runtimes exceeded

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

Step B3: After fixing, re-run

步骤B3：修复后重新执行

bash

agentcore deploy -y

If the same error recurs, check

agentcore status

to see the current state of all resources:

bash

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

bash

agentcore deploy -y

如果重复出现相同错误，检查

agentcore status

查看所有资源的当前状态：

bash

agentcore status
agentcore status --state pending-removal  # 查看标记为删除的资源

Deploying to multiple targets

部署到多个目标环境

Define targets in

agentcore/aws-targets.json

json

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

Deploy to a specific target:

bash

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

在

agentcore/aws-targets.json

中定义目标环境：

json

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

部署到特定目标环境：

bash

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

Output

输出

Pre-flight check results with specific fixes for any issues found
Diagnosis of deploy failure with the specific fix
Deploy command to run after fixes are applied

预部署检查结果，包含针对发现问题的具体修复方案
部署失败的诊断结果及具体修复方法
修复完成后可执行的部署命令