Getting Started with Amazon Bedrock AgentCore Harness and Runtime

11 min readAug 24, 2026

Introduction

AI agents are moving from experimentation to production. Organizations are deploying agents that reason over data, call external tools, maintain conversation history, and execute multi-step workflows autonomously. The challenge is no longer building a proof-of-concept. It is operating agents reliably at scale: isolation between sessions, authentication, observability, scaling, and cost control.

AWS previously offered Amazon Bedrock Agents (now called Bedrock Agents Classic) as a managed solution for agentic workloads. That service entered maintenance mode in July 2026 and is no longer open to new customers. Its successor is Amazon Bedrock AgentCore.

Amazon Bedrock AgentCore is a platform for building, deploying, and operating AI agents at scale. It includes multiple modular services that work together or independently: Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Evaluations, and others. Each service solves a specific piece of the agent lifecycle.

This article is the first in a series exploring AgentCore components. Here, the goal is to introduce and compare the two ways to run agents on AgentCore: Harness and Runtime. To illustrate the difference, we will create a simple agent for a used car dealership. This use case connects to previous articles and code in my blog. It is a straightforward scenario that will allow us to explore multiple AgentCore features in upcoming articles.

Harness vs Runtime: The Conceptual Difference

AgentCore provides two paths for deploying agents. Both run on the same underlying infrastructure (serverless microVMs with session isolation), but they differ in who owns the orchestration loop.

AgentCore Harness

The Harness is a managed agent loop. You declare what the agent is (model, system prompt, tools, memory, limits) as configuration, and AgentCore runs the orchestration. Powered by Strands Agents, the Harness handles tool execution, memory management, and response generation. You do not write orchestration code.

Key characteristics:

Configuration-driven. Changing a model or adding a tool is a config change, not a redeploy.
Each session runs in an isolated microVM with its own filesystem and shell.
Supports models from Amazon Bedrock, OpenAI, Google Gemini, and any LiteLLM-compatible provider.
Integrates natively with AgentCore Memory, Gateway, Browser, Code Interpreter, and Observability.
The recommended path for most use cases according to AWS documentation.

AgentCore Runtime

The Runtime is a serverless hosting environment. You bring your own agent code, written in any framework (Strands, LangGraph, CrewAI, LlamaIndex, OpenAI Agents SDK, or custom), package it in an ARM64 container, push to Amazon ECR, and deploy. The orchestration loop is yours.

Key characteristics:

You write the agent loop and control every aspect of orchestration.
Supports any framework, any model, any protocol (MCP, A2A).
Sessions run in isolated microVMs (same infrastructure as Harness).
Extended execution up to 8 hours for long-running/async workloads.
To use AgentCore services (Memory, Gateway, Browser), you call them from your code via the AgentCore SDK.

When to Use Each

Harness: Start here. Use it when your agent can be expressed as a model + system prompt + tools. Most agents fit this pattern. You get full AgentCore integration with zero orchestration code.
Runtime: Use it when you need custom orchestration logic, multi-agent supervisor patterns, prompt overrides at specific stages, or an existing agent codebase that you want to host on managed infrastructure.

The Harness is actually a managed abstraction that runs on top of the Runtime. If you outgrow the Harness, you can export it to code and deploy on Runtime without starting from scratch.

Creating a Harness: Available Methods

There are three paths to create a Harness, all leading to the same result:

AWS Console (Quick create / Advanced create) — graphical interface, ideal for exploration and first-time setup.
AgentCore CLI (agentcore create) - command-line tool with project scaffolding, suitable for iterative development.
AWS CLI / SDK (aws bedrock-agentcore-control create-harness or boto3) - direct API calls, best for automation and CI/CD pipelines.

In this article, we use the AWS Console for a visual, step-by-step experience.

Step 1: Create the Harness via AWS Console

1.1 Open the AgentCore Harness Console

1.1.1. Navigate to Amazon Bedrock AgentCore > Harness in the AWS Console.

1.1.2. Click the Create Harness button. You will see a dropdown arrow next to it. Click the arrow to expand the options: Quick create Harness and Advanced create Harness.

1.1.3. Select Advanced create Harness. This gives you control over the model selection and system prompt during creation.

Location of the Advanced create Harness button in the AWS Console

1.2 Configure the Harness

1.2.1. In the Harness name field, enter car_agent. The name must start with a letter and contain only letters, numbers, and underscores (a-z, A-Z, 0-9, _). Maximum 40 characters. Hyphens are not allowed.

1.2.2. In the Model and system prompt section:

Set API source to Bedrock.
For Model, select a model from the available options. The Harness defaults to Claude Sonnet 4.6, but that model may require AWS Marketplace subscription permissions that not all accounts have. In this series, I chose to run tests with models from the Amazon Nova family to explore AgentCore using AWS’s own models, but you are free to choose any model available in your account. When selecting a model, consider the tradeoffs between latency, cost, and precision. Smaller models are cheaper and faster but may struggle with complex tool parameter generation, resulting in more retries. Larger models are more precise on the first attempt but cost more per token and may have higher latency. Choose the model that best fits your use case and budget.
In the System prompt field, enter:

You are a helpful sales assistant for a used car dealership. You help customers find vehicles that match their needs and budget. Be friendly, knowledgeable, and transparent about vehicle conditions. If you don't have specific inventory data, let the customer know you'll check and get back to them.

1.2.3. Leave all remaining settings at their defaults for now. We will explore additional configurations (tools, memory, identity) in future articles.

1.2.4. In the Permissions section, the default option creates a new IAM execution role automatically. It is also possible to specify a pre-existing role or create a custom one. For this tutorial, keep the default option.

1.2.5. Click Create Harness and wait for the status to reach Ready.

Create Harness console with all configuration options used in this tutorial

Step 2: Test the Harness

After creation, the console opens a page showing the Harness details and configuration. The status will initially display as Creating while AWS provisions the resources.

2.1 Wait for the Harness to Become Ready

2.1.1. Stay on the Harness details page and wait for the status to change from Creating to Ready. This typically takes a few moments.

2.2 Open the Test Interface

2.2.1. Once the status is Ready, click the Test Harness button in the upper-right corner of the page. This opens an interactive chat interface where you can communicate with your agent.

Location of the Test Harness button in the upper-right corner

2.3 Send a Test Message

2.3.1. In the chat interface, type a simple message:

Hi, I'm looking for a reliable SUV under $25,000. What do you recommend?

2.3.2. Do not expect impressive results at this point. The agent has no tools, no inventory database, and no external data sources connected. It will try to help based solely on its general knowledge and the system prompt instructions. You may see the agent acknowledge that it cannot access inventory data and offer to check manually. This is the expected behavior for a Harness with no tools attached.

The goal here is simply to confirm the agent is responding. In upcoming articles, we will connect tools via AgentCore Gateway to give the agent access to real data.

2.4 Common Error: Model Access Denied

If you see an error like:

AccessDeniedException - An error occurred (AccessDeniedException) when calling the ConverseStream operation: Model access is denied due to IAM user or service role is not authorized to perform the required AWS Marketplace actions (aws-marketplace:ViewSubscriptions, aws-marketplace:Subscribe) to enable access to this model.

This means the selected model requires an AWS Marketplace subscription that has not been completed for your account. You have two options:

Switch to a different model: Edit the Harness configuration and select a model that does not require Marketplace subscription, such as Amazon Nova Lite or another Amazon-native model.
Subscribe to the model: Go to the Amazon Bedrock console, navigate to Model access, and request access to the desired model. For details, see Add or remove access to Amazon Bedrock foundation models.

Step 3: Create an ECR Repository

To deploy an agent on AgentCore Runtime, you need a container image stored in Amazon ECR. In this step, we create the repository that will hold our agent image.

3.1 Open the ECR Console

3.1.1. Navigate to Amazon ECR > Repositories in the AWS Console.

Get Carlos Biagolini’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

3.1.2. Click Create repository.

3.2 Configure the Repository

3.2.1. Set Visibility settings to Private.

3.2.2. In the Repository name field, enter agentcore/car-agent-runtime. The agentcore/ prefix acts as a namespace to group all agent-related repositories together.

3.2.3. Leave all remaining settings at their defaults.

3.2.4. Click Create repository.

3.3 Build and Push the Container Image

The agent code is available on GitHub. Clone the repository to get the source files:

git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreRuntime.git
cd PythonAwsBedrockAgentCoreRuntime

The repository contains three files:

agent.py - A FastAPI application that implements the /invocations (POST) and /ping (GET) endpoints required by AgentCore Runtime. It uses the Bedrock Converse API with Amazon Nova Lite and the same system prompt we used in the Harness.
requirements.txt - Python dependencies with pinned versions.
Dockerfile - ARM64 container configuration based on python:3.11-slim-bookworm.

3.3.1. Set your environment variables (update these once with your values):

export AWS_PROFILE=<your-aws-profile>  # optional, if you use named profiles
export AWS_REGION=us-east-1
export AWS_ACCOUNT_ID=<your-account-id>
export ECR_REPO=agentcore/car-agent-runtime
export REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
export REPO_URI="${REGISTRY}/${ECR_REPO}"

3.3.2. Build the ARM64 image:

docker buildx build --platform linux/arm64 -t ${ECR_REPO}:latest --load .

3.3.3. Authenticate Docker with ECR:

aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $REGISTRY

3.3.4. Tag and push to ECR:

docker tag ${ECR_REPO}:latest ${REPO_URI}:latest
docker push ${REPO_URI}:latest

3.3.5. Verify the image was pushed by checking the ECR console. You should see the latest tag in your repository.

Step 4: Create the Runtime via AWS Console

4.1 Open the AgentCore Runtime Console

4.1.1. Navigate to Amazon Bedrock AgentCore > Runtime in the AWS Console.

4.1.2. Click the Create runtime button.

4.2 Configure the Runtime

AgentCore Runtime console with the Create runtime button

4.2.1. In the Name field, enter car_agent_runtime.

4.2.2. In the Description field, enter Used car dealership agent - Runtime deployment.

4.2.3. In the Agent Source section:

Set Source type to ECR Container.
In the Image URI field, enter the full URI of your image:

<your-account-id>.dkr.ecr.us-east-1.amazonaws.com/car-agent-runtime:latest

4.2.4. Leave all remaining settings at their defaults. Similar to the Harness, the console creates a new IAM execution role automatically with the necessary permissions (ECR pull, Bedrock model invocation, CloudWatch Logs, X-Ray).

4.2.5. Click Create runtime and wait for the status to reach Ready. This may take a few minutes as AWS pulls the container image and provisions the environment.

Step 5: Test the Runtime Agent

Create runtime form with name, ECR Container source type, and Image URI configured

5.1 Wait for the Runtime to Become Ready

5.1.1. Stay on the Runtime details page and wait for the status to change from Creating to Ready.

5.2 Open the Test Interface

5.2.1. Once the status is Ready, click the Test button in the upper-right corner of the Runtime details page.

5.3 Send a Test Message

Runtime details page with status Ready and the Test button in the upper-right corner

5.3 Send a Test Message

{"prompt": "Hi, do you have any SUVs available?"}

5.3.2. Click Run to invoke the agent. As with the Harness test, do not expect impressive results. The agent has no tools or inventory data. It will respond using its general knowledge and the system prompt. The goal is to confirm the container is running correctly and the agent responds.

5.4 Updating the Runtime After Image Changes

Runtime test interface showing the input payload and the agent response

If you make changes to your agent code and push a new image to ECR, keep in mind that this does not automatically update the Runtime. Each Runtime version is an immutable snapshot of the configuration (container image, protocol, network settings). To deploy a new image, you must explicitly trigger an update.

In the console, navigate to your Runtime details page and click Update runtime. Via CLI:

aws bedrock-agentcore-control update-agent-runtime \
  --agent-runtime-id "<your-runtime-id>" \
  --agent-runtime-artifact '{"containerConfiguration": {"containerUri": "'${REPO_URI}':latest"}}' \
  --network-configuration '{"networkMode": "PUBLIC"}' \
  --role-arn "<your-role-arn>" \
  --region ${AWS_REGION} \
  --profile ${AWS_PROFILE}

This creates a new version and the DEFAULT endpoint automatically points to it. Previous versions remain available for rollback if needed.

Step 6: Clean Up

If you do not plan to continue using the resources created in this tutorial, it is a good practice to remove them from your account. For pricing details, check the AgentCore pricing page.

To remove the resources:

Navigate to Amazon Bedrock AgentCore > Harness, select your Harness, and click Delete
Navigate to Amazon Bedrock AgentCore > Runtime, select your Runtime, and click Delete
Navigate to Amazon ECR > Repositories, select the agentcore/car-agent-runtime repository, and click Delete

Conclusion

Amazon Bedrock AgentCore replaces the legacy Bedrock Agents Classic with a modular, flexible platform. The two deployment models cover different needs:

Harness gives you speed and simplicity. Declare your agent’s configuration, deploy, invoke. No orchestration code, no container builds.
Runtime gives you full control. Bring any framework, any model, any orchestration logic. Package in a container and deploy to managed infrastructure.

Both share the same security model (microVM isolation per session), pricing model (consumption-based), and observability stack (OpenTelemetry). The choice depends on whether your use case fits a declarative model or requires custom code.

For additional details, refer to:

Stay Connected

If you found this article helpful and want to learn more about AWS, cloud architecture, AI, infrastructure as code, and cloud security, follow the author for future content and tutorials: