Get started with the AgentCore CLI

This tutorial shows you how to use the AgentCore CLI to create, deploy, and invoke a Python agent on Amazon Bedrock AgentCore Runtime.

The AgentCore CLI is a command-line tool that scaffolds agent projects, deploys them to Amazon Bedrock AgentCore Runtime, and invokes them. You can use the CLI with popular Python agent frameworks such as Strands Agents, LangChain/LangGraph, Google ADK, and OpenAI Agents. This tutorial uses Strands Agents.

For information about the HTTP protocol that the agent uses, see HTTP protocol contract.

Prerequisites

Before you start, make sure you have:

Step 1: Install the AgentCore CLI

Install the AgentCore CLI globally:

npm install -g @aws/agentcore

Verify the installation:

agentcore --help

You should see output similar to the following:

Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

Step 2: Create your agent project

Use the agentcore create command to scaffold a new agent project:

AgentCore CLI

Pass flags directly to create a project non-interactively:

agentcore create --name MyAgent --framework Strands --protocol HTTP --model-provider Bedrock --memory none

To accept all defaults (Python, Strands, Bedrock, no memory), use the --defaults flag:

agentcore create --name MyAgent --defaults

Interactive

Run agentcore create without flags to launch the interactive wizard:

agentcore create

1. Enter your project name:

   

2. Choose your agent framework and model provider:

   

3. Review your configuration and confirm:

   

The agentcore create command accepts the following flags:

The command generates a project directory with the following structure:

MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

The agentcore/agentcore.json file contains your project and agent configuration. The app/MyAgent/main.py file contains starter agent code using your selected framework.

Step 3: Test your agent locally

Before deploying to AWS, test your agent locally using the development server. First, change into the project directory:

cd MyAgent

If you selected a model provider that requires an API key (OpenAI, Anthropic, or Gemini), make sure the key is configured in agentcore/.env.local.

Start the local development server:

AgentCore CLI

agentcore dev

Interactive

Run agentcore to open the TUI home screen, then navigate to the dev server option:

agentcore

The agentcore dev command:

In a separate terminal, invoke your local agent:

agentcore dev "Hello, tell me a joke"

Passing a prompt sends it to the running local development server. Use --stream to see the response streamed in real time.

Step 4: Enable observability for your agent

Amazon Bedrock AgentCore Observability helps you trace, debug, and monitor agents that you host in Amazon Bedrock AgentCore Runtime. First enable CloudWatch Transaction Search by following the instructions at Enabling Amazon Bedrock AgentCore runtime observability. To observe your agent, see View observability data for your Amazon Bedrock AgentCore agents.

After you deploy your agent, you can use the AgentCore CLI to stream logs and view traces:

# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

Step 5: Deploy to Amazon Bedrock AgentCore Runtime

Deploy your agent to Amazon Bedrock AgentCore Runtime:

AgentCore CLI

agentcore deploy

Interactive

Run agentcore deploy to start deployment. The CLI shows the deployment progress as it builds and deploys your project:

agentcore deploy

To preview the deployment without making changes, use the --plan flag:

agentcore deploy --plan

The agentcore deploy command:

Use -v for verbose output that shows resource-level deployment events. Use -y to auto-confirm the deployment without a prompt.

If the deployment fails, check for common issues.

Step 6: Test your deployed agent

After deployment completes, invoke your deployed agent:

AgentCore CLI

agentcore invoke "Tell me a joke"

You can also pass the prompt with the --prompt flag, specify a runtime with --runtime, or stream the response in real time with --stream:

agentcore invoke --prompt "Tell me a joke" --stream

To maintain a conversation across multiple invocations, use the --session-id flag:

agentcore invoke --session-id my-session "What else can you tell me?"

Interactive

Run agentcore to open the TUI home screen, then select the invoke option to chat with your deployed agent:

agentcore

If you see a joke in the response, your agent is running in Amazon Bedrock AgentCore Runtime and can be invoked. If not, check for common issues.

Step 7: Invoke your deployed agent

AgentCore CLI

Invoke your deployed agent with a prompt:

agentcore invoke --runtime MyAgent "Hello, what can you do?"

Stream the response in real time:

agentcore invoke --runtime MyAgent "Tell me a joke" --stream

Run agentcore invoke without a prompt to open the interactive chat TUI, which streams responses by default and maintains your session automatically.

AWS Python SDK (Boto3)

You can also invoke the agent using the AWS SDK InvokeAgentRuntime operation. To get the ARN of your deployed agent, use the agentcore status command:

agentcore status

Use the following boto3 (AWS SDK for Python) code to invoke your agent. Replace Agent ARN with the ARN of your agent. Make sure that you have bedrock-agentcore:InvokeAgentRuntime permissions. Create a file named invoke_agent.py and add the following code:

import json
import uuid
import boto3

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

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

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

Open a terminal window and run the code with the following command:

python invoke_agent.py

If successful, you should see a joke in the response. If the call fails, check the logs using agentcore logs or view them in Amazon CloudWatch.

Note

If you plan on integrating your agent with OAuth, you can't use the AWS SDK to call InvokeAgentRuntime. Instead, make a HTTPS request to InvokeAgentRuntime. For more information, see Authenticate and authorize with Inbound Auth and Outbound Auth.

Step 8: Clean up

If you no longer want to host the agent in Amazon Bedrock AgentCore Runtime, remove the deployed AWS resources. First, remove all resources from your local configuration:

AgentCore CLI

agentcore remove all

Interactive

Run agentcore to open the TUI home screen, then select the remove option to choose which resources to remove:

agentcore

Then deploy again to tear down the AWS resources:

AgentCore CLI

agentcore deploy

Interactive

From the AgentCore CLI home screen, select deploy to apply the removal and tear down AWS resources:

The remove all command resets the agentcore/agentcore.json configuration file while preserving agentcore/aws-targets.json and deployment state. The subsequent deploy detects the removed resources and tears down the corresponding AWS resources.

Find your resources

After deployment, you can check the status of your resources by using the AgentCore CLI:

AgentCore CLI

agentcore status

Interactive

Run agentcore and select status to view a live dashboard of all deployed resources:

agentcore

You can also view your resources in the AWS Console:

Common issues and solutions

Common issues and solutions when getting started with the AgentCore CLI. For more troubleshooting information, see Troubleshoot Amazon Bedrock AgentCore Runtime.

Advanced options (Optional)

After creating your agent project with agentcore create, you can extend it by using the agentcore add commands. For the full CLI reference, see the AgentCore CLI documentation.

Build types

When creating your project, choose a build type that fits your needs:

Add resources to your project

You can add additional resources to your project after creation:

# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

After adding resources, run agentcore deploy to provision the new resources in AWS.

Why ARM64?

Amazon Bedrock AgentCore Runtime runs on ARM64 (AWS Graviton). The AgentCore CLI handles architecture compatibility automatically for both the CodeZip and Container build types. For Container builds, only images built for ARM64 will work when deployed to Amazon Bedrock AgentCore Runtime.