Build and deploy your first Strands agent on AgentCore Runtime

Most AgentCore tutorials on the internet still use the Python bedrock-agentcore-starter-toolkit, which AWS classified as legacy when the @aws/agentcore CLI went GA in April 2026. This Recipe walks the modern path. The end state: a deployed agent runtime on AWS Bedrock AgentCore, invoked over HTTP, returning real Claude completions through a Strands agent definition you wrote in Python.

Prerequisites

These are the exact versions and approvals you need before the Recipe will work. If any of them are missing, the Recipe will fail at a predictable step.

• AWS account with IAM credentials configured locally (aws sts get-caller-identity returns your identity).
• AWS CLI 2.27 or newer. Older CLIs do not have the bedrock or bedrock-agentcore-control subcommands. Check with aws --version. Upgrade with brew install awscli on macOS, or replace your install with the current bundled installer per AWS docs.
• Node 20 or newer, npm 10 or newer. @aws/agentcore will not install on older runtimes.
• CDK bootstrap on the target account and region, or pass --yes to agentcore deploy so the CLI bootstraps for you. The CDK toolkit stack is a one-time setup per account+region.
• Bedrock model access for Anthropic Claude submitted at the account level. This is the use-case details form. The Model Access page in the Bedrock console was retired in 2026. The form now appears the first time you open any Anthropic model in the Bedrock Playground. Submit it once and access is effectively instant across commercial regions. For org-level submission use aws bedrock put-use-case-for-model-access.
• A specific Claude inference profile that does not require AWS Marketplace permissions on your IAM user. This is the surprise gotcha. Some Claude model IDs on Bedrock are still served via AWS Marketplace and require aws-marketplace:Subscribe on the invoking principal. Section in Gotchas below.

Estimated cost for the verification path: a few cents in CloudFormation operations and one Claude invocation. AgentCore Runtime itself has no idle cost beyond the CloudFormation resources.

The flow

1. Install the modern CLI locally

Scope the CLI to your Recipe directory rather than installing globally. Readers get a reproducible env, and your global npm does not collect stale CLIs over time.

mkdir -p recipes/R-001 && cd recipes/R-001
npm init -y
npm install --save-dev @aws/agentcore
npx agentcore --version

The first run prints a telemetry notice. Opt out if you want to:

npx agentcore telemetry disable

2. Scaffold the project

npx agentcore create \
  --defaults \
  --project-name rec001 \
  --name helloagent

--defaults selects Python + Strands + Bedrock with no memory layer, which is the right floor for a first Recipe. The scaffold writes a Python Strands agent in app/helloagent/, a CDK project in agentcore/cdk/, and an AgentCore config in agentcore/agentcore.json. It also initialises its own git repo inside the project, which you can safely delete if you are working inside a parent repo.

The generated Strands agent is small and worth reading before deploying:

from strands import Agent, tool
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from model.load import load_model

app = BedrockAgentCoreApp()

@tool
def add_numbers(a: int, b: int) -> int:
    """Return the sum of two numbers"""
    return a + b

_agent = None
def get_or_create_agent():
    global _agent
    if _agent is None:
        _agent = Agent(model=load_model(), tools=[add_numbers])
    return _agent

@app.entrypoint
async def invoke(payload, context):
    agent = get_or_create_agent()
    stream = agent.stream_async(payload.get("prompt"))
    async for event in stream:
        if "data" in event and isinstance(event["data"], str):
            yield event["data"]

The model is loaded from model/load.py. The scaffold defaults to global.anthropic.claude-sonnet-4-5-20250929-v1:0, which on a fresh account hits the AWS Marketplace permission gate described in Gotchas. The Recipe uses global.anthropic.claude-sonnet-4-6 instead, which on the same account works without Marketplace ops:

from strands.models.bedrock import BedrockModel

def load_model() -> BedrockModel:
    return BedrockModel(model_id="global.anthropic.claude-sonnet-4-6")

3. Configure a deployment target

[
  {
    "name": "default",
    "description": "R-001 tutorial deployment target",
    "account": "YOUR_AWS_ACCOUNT_ID",
    "region": "us-east-1"
  }
]

Validate the project state before pushing anything to AWS:

npx agentcore validate

A clean run prints Valid.

4. Deploy

npx agentcore deploy --yes -v

The --yes flag handles CDK bootstrap if the account+region is not bootstrapped yet, and skips the interactive confirm. The verified deploy creates one CloudFormation stack, AgentCore-rec001-default, containing one nested resource: ApplicationAgentHelloagentRuntime*. On a clean account the full timeline is roughly:

• Load deployment target: 3ms
• Validate project: 1.7s
• Build CDK project (tsc): 1.9s
• Synthesize CloudFormation: 9.5s
• Check bootstrap status: 1.3s
• CDK bootstrap (first run only): about 1 minute
• Stack create on AgentCore-rec001: about 1 minute

Total under 3 minutes on a fresh account, under 2 minutes on a previously bootstrapped one.

Once the stack is CREATE_COMPLETE:

npx agentcore status

You should see your agent listed as Deployed - Runtime: READY with an ARN and an invocation URL.

5. Submit the Anthropic use-case form (one-time per account)

On a fresh account, the deploy succeeds but the first invoke fails with:

ResourceNotFoundException: Model use case details have not been submitted
for this account. Fill out the Anthropic use case details form before
using the model.

The fix is one form, submitted once per AWS account. Open the AWS Console in your target region, navigate to Bedrock -> Model catalog, click any Anthropic Claude model, and choose Open in Playground. On the first attempt, AWS prompts the use-case details form with six fields:

Submit. Access is effectively instant. The error message says up to 15 minutes; in practice the next invoke works within a minute.

For organisation-wide submission, use the CLI from the org management account: aws bedrock put-use-case-for-model-access --form-data <Base64EncodedFormData>. Submission auto-extends to child accounts.

6. Invoke the deployed agent

npx agentcore invoke "What is 17 plus 25? Use the add_numbers tool."

Expected behaviour: a Strands agent loop runs in the AgentCore Runtime, the model decides to call add_numbers(17, 25), the tool returns 42, and the agent streams the final answer back. Total round-trip on the verified path: 10.4 seconds for a fresh container start. Subsequent invokes against the same session are faster.

To resume an existing session:

npx agentcore invoke --session-id <session-id> "follow-up question"

To stream and watch tokens arrive:

npx agentcore invoke --stream "your prompt"

Gotchas

The failure modes that will cost you an afternoon. Specific, with the symptom and the fix.

Verification

How you know it actually works.

npx agentcore status

Expected output, abridged:

AgentCore Status (target: default, us-east-1)

Agents
  helloagent: Deployed - Runtime: READY
    ARN: arn:aws:bedrock-agentcore:us-east-1:<account>:runtime/rec001_helloagent-<id>
    URL: https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/.../invocations

npx agentcore invoke "What is 17 plus 25? Use the add_numbers tool."

Expected response: a streamed answer that includes 42, with the Strands tool call visible in the runtime logs (agentcore logs).

The deploy works in two minutes. The Anthropic use-case form and the Marketplace permission gate are what will cost you an afternoon if no one warned you.

Sample code

The full working code is in recipes/R-001/ in the companion repo, including the modified model/load.py and the populated agentcore/aws-targets.json. Clone the recipe directory, set your AWS account ID and region in aws-targets.json, then run through sections 1 through 6 above.

The deployed stack will charge nothing while idle. To remove it later:

npx agentcore remove agent --name helloagent --yes

Or destroy the CloudFormation stack directly: aws cloudformation delete-stack --stack-name AgentCore-rec001-default --region us-east-1.