Setting the file. One moment.
Subchapter 17.1
references/versioning.mdMarkdown4 KBView on GitHub
Every agentcore deploy creates a new version of your agent runtime. This reference covers how versions work, how to pin to a specific version, and how to roll back when a deploy goes wrong.
agentcore deploy produces a new runtime versionDEFAULT) points to the currently-live versionagentcore dev) always runs the current code — no version conceptThe AgentCore CLI currently manages the project config (agentcore.json → agentcore deploy) but doesn’t expose version/alias operations directly. For those, use the AWS CLI against the bedrock-agentcore-control data plane.
# List all versions of your agent
aws bedrock-agentcore-control list-agent-runtime-versions \
--agent-runtime-id <AGENT_RUNTIME_ID>
# Get details on a specific version
aws bedrock-agentcore-control get-agent-runtime \
--agent-runtime-id <AGENT_RUNTIME_ID> \
--qualifier <VERSION>The <AGENT_RUNTIME_ID> comes from agentcore status --json | jq '.runtimes[0].agentRuntimeId'.
By default, callers hit the alias (current version). To pin a call to a specific version, pass qualifier in the invoke request:
response = client.invoke_agent_runtime(
agentRuntimeArn="<AGENT_RUNTIME_ARN>",
qualifier="3", # invoke version 3 specifically
payload=payload,
runtimeSessionId=session_id,
)This is useful for:
If a deploy breaks something, roll back by redeploying the previous known-good code:
# Option 1: git checkout the previous commit and redeploy
git checkout <PREVIOUS_COMMIT>
agentcore deploy -y
# Option 2: point the alias at an older version (no code rollback needed)
aws bedrock-agentcore-control update-agent-runtime-alias \
--agent-runtime-id <AGENT_RUNTIME_ID> \
--alias-name DEFAULT \
--routing-configuration agentRuntimeVersion=<OLDER_VERSION>Option 2 is faster — no rebuild or redeploy, just a pointer swap. Option 1 is cleaner because your code matches what’s running.
Split traffic between two versions to validate a new deploy before full rollout:
aws bedrock-agentcore-control update-agent-runtime-alias \
--agent-runtime-id <AGENT_RUNTIME_ID> \
--alias-name DEFAULT \
--routing-configuration \
agentRuntimeVersion=<NEW_VERSION>,weight=10 \
agentRuntimeVersion=<OLD_VERSION>,weight=90This routes 10% of traffic to the new version. Monitor agents-optimize eval scores and error rates before increasing the weight.
AgentCore retains versions indefinitely — they don’t auto-delete. If you’ve deployed hundreds of times, consider periodically deleting old versions:
aws bedrock-agentcore-control delete-agent-runtime-version \
--agent-runtime-id <AGENT_RUNTIME_ID> \
--version <OLD_VERSION>Never delete the current live version.
For teams that want separate dev/staging/prod environments, use deployment targets:
// agentcore/aws-targets.json
[
{"name": "default", "account": "<DEV_ACCOUNT>", "region": "us-east-1"},
{"name": "staging", "account": "<STAGING_ACCOUNT>", "region": "us-east-1"},
{"name": "production", "account": "<PROD_ACCOUNT>", "region": "us-west-2"}
]agentcore deploy --target staging -y
agentcore deploy --target production -yEach target gets its own runtime — versions are separate per target.
agents-debug to diagnose firstagents-hardenagents-optimize/references/evals.md (opens in a new tab)