agentcore-cli

Create, develop, and deploy AI agents to Amazon Bedrock AgentCore.

Python port of the AgentCore CLI (@aws/agentcore v0.31.1).

Status: early release. All commands are ported and covered by tests, but agentcore deploy has not yet been verified end-to-end against a real AWS account. Please report issues.

Overview

Amazon Bedrock AgentCore enables you to deploy and operate AI agents securely at scale using any framework and model. AgentCore provides tools and capabilities to make agents more effective, purpose-built infrastructure to securely scale agents, and controls to operate trustworthy agents. This CLI helps you create, develop locally, and deploy agents to AgentCore with minimal configuration.

Install

pip install agentcore-cli

Requirements:

• Python 3.11+
• uv for Python agents
• Node.js 20+ for agentcore deploy (deploys run the project's CDK app)

Upgrading from the Bedrock AgentCore Starter Toolkit? Both the old Python CLI and this one use the agentcore command name, so having both installed can cause confusion. Uninstall the old one using whichever tool you originally used:

pip uninstall bedrock-agentcore-starter-toolkit     # if installed via pip
pipx uninstall bedrock-agentcore-starter-toolkit    # if installed via pipx
uv tool uninstall bedrock-agentcore-starter-toolkit # if installed via uv

Quick start

Run agentcore with no arguments to walk through the commands interactively, or run each command individually:

# Initialize a new agent project (choose framework: strands, langgraph, or custom)
agentcore init my-agent --framework strands

# Develop locally
cd my-agent
agentcore dev

# Deploy to AgentCore Runtime
agentcore deploy --region us-east-1

# Test the deployed agent
agentcore invoke --agent-name my-agent --input "Hello, what can you do?"

init derives valid names from the folder: my-agent becomes project MyAgent with agent my_agent (invoke --agent-name accepts either spelling). --framework custom scaffolds a minimal bedrock-agentcore entrypoint for your own code.

You can also use the upstream wizard, agentcore create, which guides you through agent setup.

Supported frameworks

Framework	Notes
Strands Agents	AWS-native, streaming support (Python + TypeScript)
LangChain/LangGraph	Graph-based workflows
Google ADK	Gemini models only
OpenAI Agents	OpenAI models only
Bedrock Managed Agents	Runtime environment for Bedrock Managed Agents sessions (Python, Container)

Supported model providers

Provider	API key required	Default model
Amazon Bedrock	No (uses AWS credentials)	us.anthropic.claude-sonnet-4-5-20250514-v1:0
Anthropic	Yes	claude-sonnet-4-5-20250514
Google Gemini	Yes	gemini-2.5-flash
OpenAI	Yes	gpt-4.1

Commands

Project lifecycle

Command	Description
create	Create a new AgentCore project
init	Initialize a new agent project (added in this port)
dev	Start local development server
deploy	Deploy infrastructure to AWS
invoke	Invoke deployed agents

Resource management

Command	Description
add	Add harnesses, agents, memory, credentials, gateways and gateway-targets, evaluators, online evals, online insights, knowledge bases, config bundles, datasets, policy engines and policies, payment managers and payment connectors, capacity providers, runtime endpoints
remove	Remove any of the above resources from the project

Note: run agentcore deploy after add or remove to update resources in AWS.

Harness

A harness bundles a runtime, model, tools, skills, memory, and observability into one declarative config. Use it when you want infrastructure without writing agent code.

Command	Description
add harness	Add a harness resource (runtime + model + memory)
add tool	Add a tool to a harness (--harness <name> --type <type> --name <name>)
add skill	Add a skill to a harness (--harness <name> + --path / --s3 / --git)
export harness	Export a harness config to a deployable Strands Python agent under app/

After export harness, read app/<agentName>/EXPORT_NOTES.md before running deploy. It lists any manual follow-up the exporter could not automate.

Observability

Command	Description
logs	Stream or search agent runtime logs
traces list	List recent traces for a deployed agent
traces get	Download a trace to a JSON file
status	Show deployed resource details

Evaluations

Command	Description
add evaluator	Add a custom LLM-as-a-Judge evaluator
add online-eval	Add continuous evaluation for live traffic
run eval	Run on-demand evaluation against agent traces
run batch-evaluation	Run evaluators across all sessions
run recommendation	Optimize prompts and tool descriptions
evals history	View past eval run results
pause online-eval	Pause a deployed online eval config
resume online-eval	Resume a paused online eval config
stop batch-evaluation	Stop a running batch evaluation
logs evals	Stream or search online eval logs

Config bundles

Command	Description
add config-bundle	Add a versioned configuration bundle
cb versions	List version history for a bundle
cb diff	Diff two versions of a bundle
cb create-branch	Create a new branch on an existing bundle

Create agents with --with-config-bundle to auto-wire config bundle support into the generated template.

A/B tests

Command	Description
run ab-test	Start an A/B test (config-bundle or target-based) on a gateway
view ab-test	List A/B test jobs or view one in detail
pause ab-test	Pause traffic splitting for a running test
resume ab-test	Resume a paused test
stop ab-test	Stop a running test (terminal)
promote ab-test	Apply the winning variant to agentcore.json
archive ab-test	Delete the test on the service and clear local history

Knowledge bases

Command	Description
add knowledge-base	Add a managed Bedrock Knowledge Base wired to a gateway

Compatibility with the npm CLI

All upstream commands and flags work as documented in the upstream command reference (agentcore create, add, remove, status, logs, traces, evals, ...).

• Projects are interchangeable: the same agentcore/ files, written byte-for-byte as the npm CLI writes them.
• Secrets in agentcore/.env.local use the same enc:v1: AES-256-GCM envelope and key (OS keychain entry aws-agentcore / env-local-secret-key, or ~/.agentcore/secrets.key).
• Additions in this port: agentcore init, deploy --region, and invoke --agent-name / --input.
• Differences: interactive mode uses prompts instead of a full-screen UI; no telemetry is sent; agentcore update upgrades via pip (or tells you the pipx/uv command).