Get started with the AgentCore CLI

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

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.

Step 2: Create your project

agentcore create

The interactive wizard first asks what you want to build:

If you choose Agent, the wizard continues with:

You can also pass flags directly to create a code-based agent:

agentcore create \
  --project-name MyProject \
  --name MyAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

For all available commands and options, see AgentCore CLI reference.

Build types

Project structure

agentcore create generates shared project configuration and a different application structure for code-based agents and harnesses:

Key files:

Step 3: Test locally

cd MyProject
agentcore dev

agentcore dev creates a Python virtual environment, installs dependencies, starts a local server with hot reload, and opens the agent inspector in your browser so you can chat with the agent, inspect traces, and browse project resources. Code changes are picked up automatically.

Step 4: Deploy your agent

agentcore deploy

Deploy:

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

Preview what will change without deploying:

agentcore deploy --dry-run

Check status:

agentcore status

Step 5: Invoke your deployed agent

agentcore invoke --prompt "Hello, what can you do?"

If your agent has payments configured, provide payment context at invoke time:

agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com

That’s the loop. Iterate on app/MyAgent/main.py, test with agentcore dev, deploy with agentcore deploy, invoke with agentcore invoke.

Invoke an agent programmatically

You can invoke the deployed agent with the AWS SDK InvokeAgentRuntime operation. Get the agent runtime ARN:

agentcore status

Create a file named invoke_agent.py. Replace Agent ARN with the ARN of your agent:

import json
import uuid

import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": prompt}).encode(),
    qualifier="DEFAULT",
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode("utf-8"))

print(json.loads("".join(content)))

Run the code:

python invoke_agent.py

Your identity must have the bedrock-agentcore:InvokeAgentRuntime permission.

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.

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

Each add command scaffolds the config and prompts for required values. After adding, run agentcore deploy to provision.

Deep dives for the capabilities you can attach:

View logs and traces

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

Troubleshoot

For more information, see Troubleshoot Amazon Bedrock AgentCore Runtime.

Clean up

agentcore remove all
agentcore deploy

remove all resets the configuration. The follow-up deploy detects the empty state and tears down the resources in your account.

Next steps