Get started with Amazon Bedrock AgentCore

This quickstart gets you from zero to a running agent in a few minutes using the AgentCore CLI. You will install the CLI, scaffold a project, test locally, deploy to AWS, and invoke your agent.

Two ways to build an agent on AgentCore, same CLI:

This page walks through the code-based flow. For harness, see What is the AgentCore harness.

Sign up for an AWS account

Sign up for an AWS account

To get started with AWS, you need an AWS account. For information about creating an AWS account, see Getting started with an AWS account in the AWS Account Management Reference Guide.

Prerequisites

This quickstart uses Amazon Bedrock and AgentCore Memory. The CLI’s default recipe does not apply to China Regions. For the CLI-specific alternatives and restrictions, see CLI project scope in China Regions.

Step 1: Install the AgentCore CLI

npm install -g @aws/agentcore

Verify:

agentcore --version

To update later, rerun the install command or agentcore update. Source and issues: agentcore-cli on GitHub.

Run agentcore without arguments to browse commands interactively. Type to filter the list, then select a command to open its workflow or command-line help.

Step 2: Create your project

agentcore create \
  --name MyProject \
  --template agent-python-strands

The --template agent-python-strands option creates a code-based Python agent that uses the Strands Agents SDK and Amazon Bedrock. The CLI also:

Run agentcore create without flags to use the interactive wizard. The wizard defaults to a managed harness. For a code-based project, choose code-based, a template, and, for templates that support it, a model provider and model before reviewing the configuration. Passing only --name creates a managed harness project, so specify --template when creating a code-based project non-interactively.

For all available commands and options, see AgentCore CLI.

Build types

The agent-python-strands template creates a CodeZip Runtime. This build type packages your code in a zip file and does not require Docker.

To create the same Strands agent as a container image instead, use the container template:

agentcore create \
  --name MyProject \
  --template agent-python-strands-container

The CDK application uploads the container source and uses AWS CodeBuild to build the image and push it to Amazon ECR during deployment. You need a running Docker, Podman, or Finch engine only when testing this container locally with agentcore dev.

Choose a Runtime model provider

The Python Strands, Python Strands container, A2A Python Strands, AG-UI Python Strands, and TypeScript Strands templates support model-provider choices in the interactive agentcore create wizard. Run agentcore create without flags, choose code-based, and then choose the template, provider, model, and API-key file.

The noninteractive agentcore create --template <template> command uses the template’s default model provider. It does not accept model-provider flags. The agentcore add runtime command is for code that you write yourself. It does not select a model provider or generate model integration code.

The wizard supports the following model providers for templates that implement them:

TypeScript Strands does not support LiteLLM. Use an OpenAI-compatible endpoint instead. Amazon Bedrock uses AWS credentials. For providers that need an API key, select a local key file or stdin in the wizard. The CLI stores the key in agentcore/.env.local. Do not commit that file or the source key file.

An OpenAI-compatible provider requires an endpoint URL, an explicit model ID served by that endpoint, and an API key. Use only a trusted endpoint because it receives the API key. The wizard shows provider defaults and model-catalog links. Confirm model access with your provider.

Harness model configuration uses a different set of options. See Models and instructions.

CLI project scope in China Regions

In cn-north-1 and cn-northwest-1, this CLI release supports the following project additions:

It blocks these project resources and templates:

In the interactive create wizard, you can choose an OpenAI-compatible endpoint with an explicit endpoint, model ID, and key. With Python templates, you can also choose LiteLLM with an explicit model ID that does not use the bedrock/ prefix. Provider-free templates such as agent-python-minimal and mcp-python-fastmcp are another alternative. The CLI omits default Memory when scaffolding an allowed template in a China Region.

You can also use agentcore add runtime to register Python or TypeScript code that you write yourself. Because the CLI does not generate or inspect your model integration, verify that your code calls a model or endpoint that is reachable from the target China Region.

These are CLI validation rules, not a guarantee of model or endpoint reachability from China or a complete list of regional service availability. Verify access to your chosen endpoint and the services that your application uses.

Project structure

The create command generates the following code-based project:

MyProject/
├── .gitignore
├── agentcore/
│   ├── .env.local
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── agent/
        ├── .gitignore
        ├── README.md
        ├── main.py
        ├── memory/
        │   ├── __init__.py
        │   └── session.py
        ├── model/
        │   ├── __init__.py
        │   └── load.py
        ├── parse.py
        └── pyproject.toml

Key files:

Step 3: Test locally

cd MyProject
agentcore dev --mode browser

The command starts the Runtime locally with hot reload and opens the agent inspector in your browser so you can chat with the agent and inspect local traces. The create command installed the dependencies and created the Python virtual environment in Step 2.

Without --mode browser, agentcore dev defaults to headless mode and streams the Runtime output to your terminal.

Step 4: Deploy your agent

Build the deployable artifacts and validate the project before deploying:

agentcore build

Deploy the project:

agentcore deploy

The deploy command does the following:

First deploy takes a few minutes while CDK bootstraps your account. Subsequent deploys are faster.

Check status:

agentcore status

Step 5: Invoke your deployed agent

agentcore invoke --runtime agent \
  --payload '{"prompt":"Hello, what can you do?"}'

To iterate, edit app/agent/main.py, test with agentcore dev --mode browser, deploy with agentcore deploy, and invoke with agentcore invoke --runtime agent.

Add capabilities to your project

agentcore add manages resources in agentcore.json. Run it without arguments for the interactive menu, or target a resource directly. Each resource opens a wizard when you run it without options.

For example, agentcore add runtime prompts for a name, language, and protocol, and then displays the configuration for review. It registers a Runtime for code that you write yourself. The command creates app/<name>/README.md and app/<name>/AGENTS.md with the selected protocol contract, but it does not generate application code or dependencies and does not overwrite files already in the directory.

agentcore add memory    # Store conversation context
agentcore add runtime   # Add another Runtime
agentcore add gateway   # Connect APIs and tools through Gateway

To add a Runtime without the wizard, pass its language and protocol:

agentcore add runtime \
  --name worker \
  --language python \
  --protocol HTTP

The Runtime starts as a direct code (CodeZip) build with main.py for Python or main.js for TypeScript. Follow the generated README to add the entrypoint and dependency manifest. When you run agentcore dev, agentcore build, or agentcore deploy, the CLI synchronizes agentcore.json with the code. A Dockerfile switches the Runtime to a container build. For Python, requires-python in pyproject.toml constrains the managed runtime version and [tool.agentcore].entrypoint can select another entrypoint. For TypeScript, engines.node constrains the Node.js version and the CLI bundles main.ts.

To translate an existing agent from Agents for Amazon Bedrock into Amazon Bedrock AgentCore Runtime code, pass its agent ID instead. Do not pass --language or --protocol with an import.

Replace <bedrock-agent-id> with your agent ID and <prepared-agent-alias-id> with your prepared alias ID:

agentcore add runtime \
  --name imported_agent \
  --agent-id <bedrock-agent-id> \
  --agent-alias-id <prepared-agent-alias-id> \
  --framework strands

To add another kind of resource without its wizard, pass its options on the command line. Run agentcore add <resource> --help to see the options.

After adding resources, run agentcore deploy to provision them.

Deep dives for the capabilities you can attach:

View logs and traces

# Stream Runtime logs
agentcore logs runtime

# Search a past window
agentcore logs runtime --since 30m --level error
agentcore logs runtime --since 1h --query "timeout"

# List recent Runtime traces
agentcore traces runtime list --since 30m

# Download a specific trace
agentcore traces runtime get <trace-id>

Troubleshoot

For more information, see Troubleshoot Amazon Bedrock AgentCore Runtime.

Clean up

agentcore remove all --yes
agentcore deploy --yes

remove all removes every resource from the project specification. The follow-up deploy detects the empty state and tears down the project’s deployed stack. The --yes option confirms the teardown without an interactive prompt.

Next steps