View a markdown version of this page

Get started with Amazon Bedrock AgentCore - Amazon Bedrock AgentCore
PrerequisitesStep 1: Install the AgentCore CLIStep 2: Create your projectStep 3: Test locallyStep 4: Deploy your agentStep 5: Invoke your deployed agentAdd capabilities to your projectView logs and tracesClean upNext steps

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:

  • Code-based agent (default, GA). You write the agent loop in Python using a framework you already know (Strands, LangGraph, Google ADK, or OpenAI Agents), and deploy it to AgentCore Runtime. Full control over orchestration logic.

  • Managed harness (preview). You declare the agent in a config file (model, prompt, tools, memory) and AgentCore runs the loop for you. No framework, no orchestration code. Good path when you want the fastest route from idea to a running agent. Learn more.

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

Prerequisites

  • Node.js 20 or later. The AgentCore CLI is distributed as an npm package. Check with node --version. Install from nodejs.org if needed.

  • npm. Included with Node.js.

  • An AWS account with credentials configured. Configure via AWS CLI, environment variables, or an AWS profile. See Configuring the AWS CLI.

  • Python 3.10 or later (for agent code). Check with python3 --version.

  • IAM permissions. Your identity needs permissions to make AgentCore API calls and to assume the CDK bootstrap roles used during deployment. See AgentCore CLI IAM Permissions.

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.

Opt into the preview channel

To access preview capabilities (harness, config-based agents, in-progress features), install the preview channel:

npm install -g @aws/agentcore@preview

The preview channel is the same CLI with preview features enabled. Stable commands behave identically. See What is the AgentCore harness for what the preview unlocks.

Step 2: Create your project

agentcore create

The interactive wizard asks you for:

  • Framework - Strands Agents (recommended), LangChain/LangGraph, Google Agent Development Kit, or OpenAI Agents SDK

  • Model provider - Amazon Bedrock, Anthropic, OpenAI, or Gemini

  • Memory - None, short-term only, or long-term and short-term

  • Build type - CodeZip (default) or Container

You can also pass flags directly:

agentcore create \
  --name MyAgent \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip
Note

Preview alternative. With the preview CLI installed, you can scaffold a config-based harness instead of a code-based agent. The CLI surfaces this as a choice in the wizard. Harness is the fastest path to a running agent because there is no framework or orchestration code to write.

Project structure

agentcore create generates:

MyAgent/
├── agentcore/
│   ├── agentcore.json      # Project and resource configuration
│   ├── aws-targets.json    # Deployment target (account and region)
│   └── cdk/                # CDK infrastructure (auto-managed)
└── app/
    └── MyAgent/            # Your agent code
        ├── main.py         # Agent entrypoint
        ├── pyproject.toml  # Python dependencies
        └── ...

Key files:

  • agentcore/agentcore.json - the main config. Defines your agents, memory stores, gateways, credentials, and other resources. Managed by agentcore add and agentcore remove.

  • app/ - your agent code. Each agent gets its own subdirectory with an entrypoint and a pyproject.toml.

  • agentcore/aws-targets.json - the AWS account and region for deployment.

Step 3: Test locally

cd MyAgent
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.

Useful flags:

  • --no-browser - use the terminal-based TUI instead of the browser inspector.

  • --no-traces - disable writing traces to agentcore/.cli/traces.

  • --logs - tail server logs in non-interactive mode.

  • --port <N> - pin the dev port (default 8080 for HTTP, 8000 for MCP, 9000 for A2A; auto-increments if busy).

Step 4: Deploy your agent

agentcore deploy

Deploy:

  1. Packages your code into a zip artifact (or builds a container if --build Container)

  2. Uses AWS CDK under the hood to synthesize and provision resources

  3. Creates an AgentCore Runtime endpoint for your agent

  4. Configures CloudWatch logging and observability

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

Preview what will change without deploying:

agentcore deploy --plan

Check status:

agentcore status

Step 5: Invoke your deployed agent

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

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

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

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>

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

  • What is the AgentCore harness - the config-based path to a running agent (preview). Use any model, connect to tools, persist state, deploy in your VPC, and graduate to code when you need it.

  • AgentCore code samples - end-to-end examples across frameworks and capabilities.