How to run a first AgentCore agent with the CLI

The AgentCore CLI is the documented path from an empty project to an invoked Amazon Bedrock AgentCore endpoint. You install one npm package, scaffold a project, test it locally, deploy, and call the agent from the terminal. This is evergreen setup from the developer guide, not a launch announcement.

The same CLI supports two styles. A managed harness is a config file — model, prompt, tools, and memory — and AgentCore runs the loop. No framework and no orchestration code. A code-based agent, the flow this quickstart walks, is a Python loop you write with Strands, LangGraph, Google ADK, or OpenAI Agents, then deploy to AgentCore Runtime. The harness path is a different page in the same guide.

Prerequisites

You need an AWS account. Configure credentials with the AWS CLI, environment variables, or an AWS profile.

• Node.js 20 or later, and npm. The CLI is an npm package. Check with node --version. Install Node.js 20 or later if that check fails.
• Python 3.10 or later for agent code. Check with python3 --version.
• IAM permission to make AgentCore API calls and to assume the CDK bootstrap roles used during deployment. The permission list is on the Use the AgentCore CLI page; this quickstart does not inline it.
• Model access. Amazon Bedrock enables foundation models by default, including Amazon Nova, Anthropic Claude, Meta Llama, and Mistral AI models. Non-foundation models need the separate model-access steps.
• Docker only if you choose the Container build type. The default CodeZip build does not require Docker.

Install the CLI

npm install -g @aws/agentcore

Confirm the binary responds with a version:

agentcore --version

If that reports an error instead of a version number, an older Python agentcore command is shadowing the npm one on your PATH. The guide says this happens when the bedrock-agentcore-starter-toolkit pip package was installed earlier, and that it is most common on Windows. Uninstall that package, open a new terminal, and run the version check again:

pip uninstall bedrock-agentcore-starter-toolkit

To update later, rerun the install command or run agentcore update.

Scaffold a code-based agent

agentcore create

The wizard first asks what to build:

• Harness — a managed, config-based agent loop. No framework or orchestration code.
• Agent — a code-based agent using a framework you choose, deployed to AgentCore Runtime.
• Skip — project structure without an agent. Add one later with agentcore add.

Choose Agent. The wizard then asks 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 pass those choices as flags. This is the guide's example:

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

The quickstart points to the AgentCore CLI reference for every command and option. The flags above are the create example on this page, not a claim that no other flags exist.

CodeZip packages your code in a zip file and uploads it to Amazon S3. It does not require Docker. Container builds and deploys a container image and requires a running Docker daemon.

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

A code-based project includes AGENTS.md and a README at the root, an agentcore directory, and an app directory. The agentcore directory holds agentcore.json, aws-targets.json, and a cdk directory. Under app, a folder for the agent holds main.py, pyproject.toml, a README, and folders named model, mcp_client, and skills.

A harness project keeps that same agentcore directory. Under app/, it contains harness.json and system-prompt.md instead of a Python entrypoint.

agentcore.json is the main configuration file. It defines agents, harnesses, memory stores, gateways, credentials, and other resources. agentcore add and agentcore remove manage it. aws-targets.json holds the AWS accounts and Regions for deployment. A file named .env.local in the agentcore directory holds local secrets, such as API keys for model providers. The quickstart lists the entrypoint but does not show its source.

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. You can chat with the agent, inspect traces, and browse project resources. Code changes are picked up automatically.

If the port is already in use:

agentcore dev --port 3000

The quickstart does not name the default port. It only shows 3000 as an alternate.

Deploy

agentcore deploy

Deploy packages your code into a zip artifact, or builds a container if you used --build Container. It uses AWS CDK to synthesize and provision resources, creates an AgentCore Runtime endpoint for the agent, and configures CloudWatch logging and observability.

The first deploy takes a few minutes while CDK bootstraps the account. Subsequent deploys are faster. If bootstrap is required, interactive deployment asks for confirmation. agentcore deploy --yes approves the bootstrap operation without a prompt.

Preview the change without deploying:

agentcore deploy --dry-run

Check status:

agentcore status

Invoke

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

The documented loop is to iterate on app/MyAgent/main.py, test with agentcore dev, deploy with agentcore deploy, and invoke with agentcore invoke.

You can also call the deployed agent with the AWS SDK InvokeAgentRuntime operation. Get the agent runtime ARN from agentcore status, create a file named invoke_agent.py, and replace Agent ARN with that ARN. The quickstart's sample is:

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 it:

python invoke_agent.py

Your identity must have the bedrock-agentcore:InvokeAgentRuntime permission. For an agent that uses OAuth, the guide says to make an HTTPS request to InvokeAgentRuntime instead of using the AWS SDK. That procedure is on the authorization page, not in this quickstart.

When a command fails

Permission denied: verify credentials with aws sts get-caller-identity, and confirm the identity has the permissions in Use the AgentCore CLI.

Model access denied: foundation models are enabled by default. A non-foundation model needs the model-access steps.

Deployment errors: agentcore deploy --verbose shows resource-level deployment events. The CLI checks CDK bootstrap status.

Configuration validation errors: agentcore validate.

To tear the deployment down:

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.

What to do next

Confirm agentcore --version prints a version, not an error from the old pip toolkit. Scaffold with the Strands and CodeZip flags above if you want the documented non-interactive path, then chat in the local inspector before the first deploy. After invoke returns, edit app/MyAgent/main.py and repeat dev, deploy, and invoke. If you want a config file instead of a Python framework, follow the harness page linked from the quickstart's next-steps section. End-to-end examples across frameworks are in the AgentCore code samples repository named there.

Sources

• Get started with the AgentCore CLI