AgentCore CLI

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

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.

🚀 Jump Into AgentCore

• Node.js 20.x or later
• uv for Python agents (install)

Installation

Upgrading from the Bedrock AgentCore Starter Toolkit? If the old Python CLI is still installed, you'll see a warning after install asking you to uninstall it. Both CLIs use the agentcore command name, so having both 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

npm install -g @aws/agentcore

Quick Start

Use the terminal UI to walk through all commands interactively, or run each command individually:

# Launch terminal UI
agentcore

# Create a new project (wizard guides you through agent setup)
agentcore create
cd my-project

# Test locally
agentcore dev

# Deploy to AWS
agentcore deploy

# Test deployed agent
agentcore invoke

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

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
dev	Start local development server
deploy	Deploy infrastructure to AWS
invoke	Invoke deployed agents

Resource Management

Command	Description
add	Add agents, memory, credentials, gateways and gateway-targets, evaluators, online evals, online insights, knowledge bases, config bundles, datasets, harnesses, policy engines and policies, payment managers and payment connectors, 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.

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

See Knowledge Bases for ingestion, vectorization, and retrieval setup.

Insights — [preview]

Failure-pattern analysis across agent sessions. Insights configs run continuously alongside online evals and surface clusters of bad outcomes.

Command	Description
add online-insights	Add a continuous insights config bound to a runtime
run insights	Run on-demand failure analysis across recent sessions
view insights	List insights jobs or view one in detail
pause online-insights	Pause a deployed online insights config
resume online-insights	Resume a paused online insights config
archive insights	Delete an insights job on the service + clear local history

Harness — [preview]

Harness commands are only available in the preview release of the CLI. Install it with:

npm install -g @aws/agentcore@preview

A harness bundles a runtime, model, tools, skills, memory, and observability into one declarative config. Use it when you want infra 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.

Policies & Guardrails

Policy engines apply Cedar-based pre/post-call policies to agent invocations — including Bedrock content filters (VIOLENCE, HATE, SEXUAL, MISCONDUCT, INSULTS), prompt-attack detection, and sensitive-information redaction.

Command	Description
add policy-engine	Add a Cedar policy engine to the project
add policy	Add a policy to a policy engine (form-based guardrails or raw Cedar)

Payments

Pay-per-call agent transactions via the x402 protocol. When a tool call returns 402 Payment Required, the payments system signs and submits payment then retries automatically.

Command	Description
add payment-manager	Add a payment manager (orchestrates payment sessions for the agent)
add payment-connector	Add a payment connector with provider credentials (CoinbaseCDP, StripePrivy)

See Payments for the full setup including instrument creation and tool allowlists.

Datasets

Curated session datasets for batch evaluation and recommendation runs.

Command	Description
add dataset	Add a dataset resource (session list, ground-truth file, or trace filter)
dataset download	Download a dataset version locally
dataset publish-version	Publish a new dataset version
dataset remove-version	Remove a dataset version

Web Search Gateway Targets

Add a managed web-search target to a gateway:

agentcore add gateway-target --type connector --connector web-search \
  --gateway <gateway-name> --name <target-name>
# Optional: --exclude-domains "example.com,foo.org"

See Gateway for full target setup including Lambda, MCP, OpenAPI, Smithy, and API Gateway.

Utilities

Command	Description
validate	Validate configuration files
package	Package agent artifacts without deploying
fetch access	Fetch access info for deployed resources
feedback	Send feedback to the AgentCore team (with screenshot)
update	Check for and install CLI updates

Project Structure

my-project/
├── agentcore/
│   ├── .env.local          # API keys (gitignored)
│   ├── agentcore.json      # Resource specifications
│   ├── aws-targets.json    # Deployment targets
│   └── cdk/                # CDK infrastructure
├── app/                    # Application code

App Structure

├── app/                    # Application code
│   └── <AgentName>/        # Agent directory
│       ├── main.py         # Agent entry point
│       ├── pyproject.toml  # Python dependencies
│       └── model/          # Model configuration

Configuration

Projects use JSON schema files in the agentcore/ directory:

• agentcore.json - Project resources (agents, memory, credentials, gateways, evaluators, online evals/insights, knowledge bases, harnesses, policy engines and policies, payment managers and connectors, config bundles, datasets, runtime endpoints)
• deployed-state.json - Runtime state in agentcore/.cli/ (auto-managed)
• aws-targets.json - Deployment targets (account, region)

Capabilities

• Runtime - Managed execution environment for deployed agents
• Memory - Semantic, summarization, user-preference, and episodic strategies
• Credentials - Secure API key + OAuth credential management via Secrets Manager
• Gateways - MCP gateways with Lambda / MCP server / OpenAPI / Smithy / API Gateway / web-search / knowledge-base targets
• Evaluations - LLM-as-a-Judge for on-demand, batch, and continuous agent quality monitoring
• Recommendations - Auto-optimize system prompts and tool descriptions from real session traces
• A/B Tests - Traffic-split between config-bundle or target-based variants and promote the winner
• Insights [preview] - Failure-pattern analysis and clustering across agent sessions
• Knowledge Bases - Managed Bedrock Knowledge Bases auto-wired to gateways
• Harness - Declarative agent: bundle runtime + tools + skills + memory + observability without writing agent code
• Policies & Guardrails - Cedar pre/post-call policies including Bedrock content filters, prompt-attack detection, and sensitive-information redaction
• Payments - x402-protocol microtransactions for pay-per-call tools and APIs
• Config Bundles - Versioned runtime configurations as a separately-deployable resource

Documentation

Reference

• CLI Commands Reference - Full command reference for scripting and CI/CD
• Configuration - Schema reference for config files
• Frameworks - Supported frameworks and model providers
• PERMISSIONS - IAM permissions required to deploy

Resources & features

• Memory - Memory strategies and sharing
• Gateway - Gateway setup, targets, and authentication
• Knowledge Bases - Managed Bedrock Knowledge Bases wired to gateways
• Payments - x402-protocol microtransactions for paid tools/APIs
• Config Bundles - Versioned runtime configurations
• Container Builds - Container build types and Dockerfile setup

Evaluation & quality

• Evaluations - Evaluators, on-demand evals, and online monitoring
• Batch Evaluation - Run evaluators across sessions at scale
• Recommendations - Optimize prompts and tool descriptions
• A/B Tests - Split traffic between variants and promote the winner

Operations

• Local Development - Dev server and debugging
• Transaction Search - Trace + log search across agent invocations
• Telemetry - CLI usage telemetry — what's collected and how to opt out
• TUI Harness - Programmatic TUI driver for testing
• Testing - Unit, integration, and e2e test infrastructure
• Feedback - Submit feedback from your terminal

Examples

See the AgentCore Samples repository for end-to-end examples using the CLI, including multi-agent workflows, MCP gateway targets, and framework integrations.

Feedback & Issues

Have a quick comment or suggestion? Send it from your terminal:

agentcore feedback "your message" --screenshot path/to/screenshot.png

The CLI will display the AWS Customer Agreement and prompt for consent before submitting. See docs/feedback.md for usage details.

For bugs, regressions, or feature requests that need discussion, open an issue on GitHub instead.

Security

See SECURITY for reporting vulnerabilities and security information.

License

This project is licensed under the Apache-2.0 License.