End-to-End Deploy with the AgentCore CLI

Before any command, fix this in your head: there are two different CLIs, both of which install a binary called agentcore, and they have different verbs. This single ambiguity is the most common source of copy-paste failures when following tutorials.

Both deploy to the same Runtime, and both wrap your agent with the same bedrock-agentcore Python SDK (BedrockAgentCoreApp, @app.entrypoint, app.run()). The toolkit README now marks itself (legacy) and points at the AgentCore CLI. New work should use @aws/agentcore; you learn the legacy verbs only so you can read older content.

A further trap lives even inside the legacy world: the AWS devguide and the Python Runtime API use the verb launch / .launch(), but the current starter-toolkit CLI (v0.3.x) renamed that verb to deploy (with destroy for teardown) — the same operation, two names. The Python method is always .launch().

The new CLI deploys through AWS CDK → CloudFormation, so the toolchain is heavier than the legacy CodeBuild path.

Toolchain prerequisites (new CLI):

• Node.js 20+ (the CLI itself) and Python 3.10+ (your agent runs Python).
• AWS credentials configured (aws configure / SSO / env vars).
• AWS CDK bootstrapped in the target account+region — run cdk bootstrap once. If you skip this, agentcore deploy fails at the CloudFormation stage.

node --version        # v20+
python --version      # 3.10+
aws sts get-caller-identity
cdk bootstrap aws://<account-id>/us-east-1

Two distinct IAM identities are involved — don't conflate them.

1. The execution role — the role the agent assumes at runtime. Abbreviated, it needs: CloudWatch Logs (CreateLogGroup/CreateLogStream/PutLogEvents/Describe* on /aws/bedrock-agentcore/runtimes/*), X-Ray (PutTraceSegments/PutTelemetryRecords/GetSamplingRules/GetSamplingTargets), cloudwatch:PutMetricData (scoped to the bedrock-agentcore namespace), workload tokens (bedrock-agentcore:GetWorkloadAccessToken*), and — if your agent calls Bedrock — bedrock:InvokeModel / bedrock:InvokeModelWithResponseStream. ECR read actions (BatchGetImage/GetDownloadUrlForLayer/GetAuthorizationToken) are needed only for Container deploys.

   Its trust policy must let the service assume it: principal bedrock-agentcore.amazonaws.com, action sts:AssumeRole, with aws:SourceAccount and aws:SourceArn (arn:aws:bedrock-agentcore:<region>:<account>:*) conditions to prevent the confused-deputy problem.

   json Copy

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
       "Action": "sts:AssumeRole",
       "Condition": {
         "StringEquals": { "aws:SourceAccount": "123456789012" },
         "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*" }
       }
     }]
   }

2. The caller/developer identity — your permissions to run the deploy. The quickest path is the managed policy BedrockAgentCoreFullAccess. The new CLI additionally needs CloudFormation/CDK permissions (and cdk bootstrap done). The legacy CodeBuild path instead needs IAM (CreateRole/PassRole on *BedrockAgentCore*), CodeBuild, ECR, S3, and Logs permissions.

The @aws/agentcore CLI gives you a tight, scaffold-first loop. Install it globally, scaffold a project, iterate locally, then ship.

npm install -g @aws/agentcore

# Scaffold a project (interactive flags shown; or use --defaults)
agentcore create --name MyAgent \
  --framework Strands \
  --protocol HTTP \
  --model-provider Bedrock \
  --memory none
# or simply: agentcore create --name MyAgent --defaults

cd MyAgent

create flags worth knowing:

• --name — alphanumeric, must start with a letter, ≤ 36 chars.
• --framework — Strands | LangChain_LangGraph | GoogleADK | OpenAIAgents.
• --protocol — HTTP (default) | MCP | A2A.
• --build — CodeZip (default) | Container.
• --model-provider — Bedrock | Anthropic | OpenAI | Gemini.
• --memory — none | shortTerm | longAndShortTerm.

Iterate locally with hot reload. agentcore dev runs a hot-reloading server plus an agent inspector on port 8080:

agentcore dev                 # hot-reload server + inspector on :8080
agentcore dev -p 3000         # if 8080 is already taken

You can hit the same service contract the cloud will use:

curl -X POST http://localhost:8080/invocations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"What is the weather?"}'

Deploy packages the agent, synthesizes a CDK stack, and applies it via CloudFormation:

agentcore deploy              # package → CDK synth → CloudFormation deploy

Invoke the deployed Runtime, optionally streaming or pinning a session:

agentcore invoke "Tell me a joke"
agentcore invoke "Tell me a joke" --stream --session-id <id> --runtime <runtime>

Observe and tear down:

agentcore status              # ARN, endpoint, log group
agentcore logs                # CloudWatch logs
agentcore traces list         # observability traces

agentcore remove all && agentcore deploy   # teardown / clean redeploy

Attach capabilities without leaving the CLI — each add wires the corresponding AgentCore service into your project:

agentcore add memory      # AgentCore Memory
agentcore add gateway     # AgentCore Gateway (governed MCP tools)
agentcore add agent       # compose another agent
agentcore add credential  # AgentCore Identity credential provider
agentcore add evaluator   # AgentCore Evaluations

A large fraction of existing AgentCore content uses the legacy bedrock-agentcore-starter-toolkit. Here is the equivalent loop so you can follow it. Note that the default build path uses AWS CodeBuild — no local Docker required.

pip install bedrock-agentcore-starter-toolkit

# 1. configure — generates .bedrock_agentcore.yaml + a Dockerfile
agentcore configure -e my_agent.py --name my_agent

# 2. launch (a.k.a. deploy) — default builds ARM64 via CodeBuild, pushes to ECR,
#    creates the Runtime, and prints the agent runtime ARN
agentcore launch

# 3. invoke — session id must be >= 33 chars
agentcore invoke '{"prompt":"What is the weather?"}'

# 4. status — agent ARN, endpoint, log group
agentcore status -v

# 5. teardown
agentcore destroy --delete-ecr-repo

Key configure flags: -e/--entrypoint (required), -n/--name, -er/--execution-role, -ecr/--ecr, -dt/--deployment-type (direct_code_deploy | container), -rf/--requirements-file, -do/--disable-otel, -ac/--authorizer-config (inbound JWT JSON), --vpc/--subnets/--security-groups, -p/--protocol (HTTP | MCP | A2A), -r/--region, -ni/--non-interactive. Useful launch flags: -l/--local (build + run locally; needs Docker/Finch/Podman), -lb/--local-build (build locally, deploy to cloud), -env/--env KEY=VALUE, -auc/--auto-update-on-conflict.

Verb mapping at a glance:

The Python Runtime API never renames the verb — it is always .launch():

from bedrock_agentcore_starter_toolkit import Runtime
runtime = Runtime()
runtime.configure(
    entrypoint="my_agent.py",
    auto_create_execution_role=True,
    auto_create_ecr=True,
    requirements_file="requirements.txt",
    region="us-east-1",
    agent_name="my_agent",
)
runtime.launch()                       # same operation the CLI calls "deploy"
runtime.invoke({"prompt": "What is the weather?"})

Whichever CLI you use, deployment ultimately packages your agent one of two ways. The choice matters for Docker requirements, size limits, and which IAM actions you need.

CodeZip is the default and the path of least resistance — no Docker, no ECR, just a zip to S3. Reach for Container only when you need system-level dependencies the zip can't carry.

The Runtime runs on AWS Graviton (ARM64). CodeZip and the CLIs handle the architecture for you, but a hand-built container must target linux/arm64. An amd64 image is one of the most common deploy failures — and it fails silently at invoke time, not at build time:

# Container build MUST be ARM64
docker buildx build --platform linux/arm64 -t my-agent:arm64 .

In the legacy toolkit, the default launch builds ARM64 in CodeBuild (no local Docker); only --local / --local-build need a local container runtime (Docker, Finch, or Podman). In the new CLI, pick the mode at scaffold time with agentcore create --build CodeZip|Container.

Most failed first deploys are one of a short, well-known list. Run through it before you debug anything exotic.

• Wrong agentcore binary. Two CLIs, different verbs. configure/launch is legacy; create/dev/deploy is new. Confirm which is on your PATH.
• launch vs deploy. Match your CLI version (Python API is always .launch()).
• amd64 image. The Runtime is ARM64 (Graviton). A wrong-arch container fails silently at invoke. Build with docker buildx build --platform linux/arm64, or use CodeZip.
• Docker assumed but not needed. CodeZip (default) needs no Docker; the legacy default builds via CodeBuild. Don't install Docker chasing a problem you don't have.
• Bedrock model access not enabled. If you call Bedrock models, you must enable model access in the Bedrock console for that account/region first — otherwise invokes return access-denied.
• Session ID too short. runtimeSessionId must be ≥ 33 characters. A short ID (e.g. "abc") is rejected. Use a UUID. (The exact 33-char minimum is commonly cited — confirm in the live API reference.)
• Missing iam:PassRole. The deployer needs to pass the execution role to the service.
• CDK not bootstrapped (new CLI). Run cdk bootstrap aws://<account>/<region> once per account+region.
• Container vs direct-code role mismatch. Container deploys need ECR read actions on the execution role; CodeZip does not. Using a CodeZip role for a Container deploy fails on image pull.
• Forgetting aws-opentelemetry-distro. Add it to requirements.txt to get built-in tracing; without it your traces are empty.
• Port 8080 in use. agentcore dev binds 8080. Free the port or run agentcore dev -p 3000.

When invoking from boto3 directly (the SigV4 data-plane path), the session-ID rule shows up concretely:

import json, uuid, boto3
client = boto3.client("bedrock-agentcore")            # data plane
resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/MyAgent-XXXX",
    runtimeSessionId=str(uuid.uuid4()),               # >= 33 chars; reuse for context/affinity
    payload=json.dumps({"prompt": "Tell me a joke"}).encode(),
    qualifier="DEFAULT",
)
print(json.loads("".join(c.decode("utf-8") for c in resp.get("response", []))))