---
title: "AgentCore Harness — the managed agent loop where model, tools, and prompt are config, not code"
date: 2026-06-07
service: "Amazon Bedrock AgentCore"
component: "Harness"
tags: [agentcore, harness, managed-agent-loop, strands, microvm, invoke-harness, inline-functions, allowed-tools, skills, litellm, multi-model, session-storage, invoke-agent-runtime-command, preview]
source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html
verified_on: 2026-06-07
url: https://vanemmerik.ai/aws-ai/2026-06-07.html
---

# AWS Bedrock & AgentCore · Tip of the Day · 2026-06-07

## AgentCore Harness — the agent loop you no longer have to write

Twelve tips in, we've covered every AgentCore primitive one at a
time — Runtime, Memory, Identity, Gateway, the Built-in Tools, Policy,
Evaluations. **AgentCore Harness** (public preview) is the piece that
composes them: a managed agent loop where you declare the model, the
tools, and the instructions as *configuration*, and AWS runs the
orchestration — environment, compute, memory, identity, VPC
networking, and observability included. Trying a different model or
adding a tool is a config change, not a code rewrite.

    aws bedrock-agentcore-control create-harness \
      --harness-name "MyHarness" \
      --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"

≈ 9 min read · Amazon Bedrock AgentCore · Harness

## 01 · What the harness actually is

Every agent has an orchestration layer: the loop that calls the model,
decides which tool to invoke, passes results back, manages the context
window, and handles failures. Running that loop needs infrastructure —
compute, a sandbox, tool connectivity, storage, memory, identity,
observability. The docs call that whole assembly the **agent
harness**, "the system that lets an agent actually run."

The **managed agent harness** replaces the build-it-yourself version
with a declaration. You say what the agent does (model, tools, system
prompt); AgentCore provides everything underneath. Under the hood it's
powered by **Strands Agents**, AWS's open-source agent framework, and
each harness is backed by a managed AgentCore Runtime that AWS
provisions and operates for you.

Every session is **stateful by default** and runs in its own
**Firecracker microVM** — the agent gets a private filesystem and
shell, can write and execute code, and keeps short-term and long-term
memory and files across sessions. Public preview regions: US East
(N. Virginia), US West (Oregon), Europe (Frankfurt), Asia Pacific
(Sydney). There's no separate harness charge — you pay only for the
underlying AgentCore capabilities you use.

## 02 · Defaults at create time, overrides at invoke time

This is the core of the config-based model. Define the harness once
with defaults — model, system prompt, tools, memory, execution
limits — then override any of them on a single invocation. The harness
resource stays unchanged; only that call uses the overrides. The docs
put it bluntly: "you can test N model/prompt/tool combinations in the
time it would take to redeploy once."

Two ways in. The AgentCore CLI (`npm install -g @aws/agentcore@preview`,
Node.js 20+):

    agentcore create --name myresearchagent --model-provider bedrock
    agentcore deploy
    agentcore invoke --harness myresearchagent \
      --session-id "$(uuidgen)" \
      "Research three tropical vacation options under $3k."

Or boto3 (Python 3.10+) against `bedrock-agentcore`: `create-harness`
on the control plane, poll `get-harness` until `READY`, then
`invoke_harness` with a `runtimeSessionId` of **at least 33
characters** (a bare UUID clears it). If you don't specify a model,
the harness defaults to **Claude Sonnet 4.6 on Amazon Bedrock**
(`global.anthropic.claude-sonnet-4-6`).

`InvokeHarness` streams events — `messageStart`, `contentBlockDelta`,
`messageStop`, `metadata` — and `messageStop` carries a `stopReason`:
`end_turn`, `tool_use` (an inline function is waiting on you),
`max_tokens`, `max_iterations_exceeded`, `timeout_exceeded`, or
`max_output_tokens_exceeded`.

## 03 · Any model, switched mid-session

The harness speaks to Amazon Bedrock, OpenAI, and Google Gemini
natively, and to anything else **LiteLLM** supports via
`liteLlmModelConfig` (provider-prefixed IDs like
`openai/gpt-5.4`, plus optional `apiBase` for OpenAI-compatible
gateways). You can **switch providers between turns of the same
session** and the conversation context carries over.

Third-party API keys never live in your agent code: store them in
**AgentCore Identity's token vault** as an API key credential
provider, pass the `apiKeyArn`, and the harness pulls the key at
invocation time.

`bedrockModelConfig` also takes an `apiFormat` field that picks the
protocol *and* the endpoint: `converse_stream` (default, the
`bedrock-runtime` endpoint), or `responses` / `chat_completions` —
both OpenAI-compatible formats served by the `bedrock-mantle`
endpoint, which supports a different model set than `bedrock-runtime`.

## 04 · Five tool types, plus a built-in shell

Tools are declarative — you list what the agent can call, AgentCore
handles invocation, credentials, and results:

- **`remote_mcp`** — any remote MCP endpoint by URL; header values can
  embed `${arn:...}` token-vault references so API keys resolve at
  invocation time.
- **`agentcore_gateway`** — reference a Gateway ARN and every tool on
  it becomes available, with Cedar Policy enforcement intact.
- **`agentcore_browser`** and **`agentcore_code_interpreter`** — the
  Built-in Tools, one line each.
- **`inline_function`** — a tool schema that executes *client-side*.
  The harness pauses with `stopReason: "tool_use"`, your code does the
  work, and you send back both the assistant `toolUse` message and
  your `toolResult`. This is the human-in-the-loop pattern.

Every session also ships default builtins: `shell` (bash) and
`file_operations`. The `allowedTools` parameter scopes what the LLM
may call, with glob patterns like `"@builtin/shell"`, `"@git/read_*"`,
or `"@*-mcp/status"`.

Separately, **`InvokeAgentRuntimeCommand`** gives you direct shell
access to the session microVM — deterministic command execution with
"no model reasoning, no token cost." Clone a repo before the agent
starts; run the tests after it finishes. Commands run as **root**
inside the microVM, and `allowedTools` does *not* gate this API — it
has its own IAM action.

## 05 · Memory, filesystem, and what persists

Attach an **AgentCore Memory** instance and every invocation saves the
conversation automatically, scoped by session ID (plus `actorId` if
provided). Reuse the same session ID and history is reloaded before
the agent reasons — even after the microVM has expired. You never
re-send old messages.

If the Memory instance has active long-term strategies, the harness
**auto-derives a retrieval configuration** (defaults `topK=10`,
`relevanceScore=0.2`) and injects relevant long-term memories into
context on every call. Provide your own `retrievalConfig` to override.
One catch: if you add or remove strategies later, call `UpdateHarness`
to refresh the derived config.

Files have three persistence options: **session storage** (service-
managed, survives stop/resume for the same session ID, no VPC
needed), an **EFS access point**, or an **S3 Files access point**
that syncs bidirectionally with a bucket — the latter two require VPC
networking.

## 06 · Custom environments and Agent Skills

The base environment is Python and bash. Need more? Point the harness
at a container image in ECR (built for **linux/arm64**) and the agent
runs in that exact environment. The harness overrides your
`ENTRYPOINT` and `CMD` — your software and env vars are available,
but your startup command never runs; start background processes via
`InvokeAgentRuntimeCommand` instead.

**Agent Skills** — the same markdown-plus-scripts bundles popularized
by Claude — are first-class: each entry in `skills` is a `path`
already in the environment, or an `s3` / `git` source the harness
fetches at invocation time. Git sources support private repos via a
token-vault credential ARN. Skills are fetched fresh at the start of
each session, so the agent always gets the current version.

## Limits worth knowing

- **Execution caps, with defaults:** `maxIterations` 75 reasoning
  cycles, `timeoutSeconds` 3600 per invocation,
  `idleRuntimeSessionTimeout` 900 s warm idle, `maxLifetime` 28800 s
  (8 h) per microVM session. `maxTokens` has no default — set one.
- **Double IAM permissions.** `InvokeHarness` requires both
  `bedrock-agentcore:InvokeHarness` *and*
  `bedrock-agentcore:InvokeAgentRuntime`; the same pairing applies to
  create/update/delete. In CloudTrail, harness activity appears under
  `AWS::BedrockAgentCore::Runtime`, and data events log as
  `InvokeAgentRuntime`.
- **SigV4 callers don't get per-user identity.** Token-vault user
  scoping and on-behalf-of exchange only work when callers
  authenticate with a Bearer JWT via inbound OAuth.
- **VPC mode still needs the internet.** The harness pulls its
  application container from Amazon ECR Public at each session start;
  ECR Public has no VPC endpoints, so you need a NAT gateway — or
  sessions fail with image-pull timeouts.
- **Skill fetch limits:** every source needs a `SKILL.md`, S3 skills
  max 1 GB, Git fetches must finish in 60 seconds.
- **`UpdateHarness` replaces the whole `filesystemConfigurations`
  list** — `GetHarness` first, then send existing mounts plus the new
  one.

## Try it in five minutes

1. Install the preview CLI: `npm install -g @aws/agentcore@preview`
   (Node 20+, credentials in a preview region — Oregon, N. Virginia,
   Frankfurt, or Sydney).
2. `agentcore create --name myagent --model-provider bedrock` —
   long-term memory is wired in by default.
3. `agentcore deploy`, then
   `agentcore invoke --harness myagent --session-id "$(uuidgen)" "..."`.
   Reuse the session ID to continue in the same microVM.
4. Run `agentcore dev` to open the agent inspector in your browser —
   chat, traces, and per-session config overrides in one view.
5. Swap the model on one call with `--model-id`, or add the browser
   with `--tools agentcore-browser`. No redeploy. That's the point.

## Verified against the official AWS docs on 2026-06-07

Sources:

- AgentCore harness [Preview] — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html
- Get started — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-get-started.html
- Configure agents and models — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-config-and-models.html
- Connect to tools — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-tools.html
- Persist memory and filesystem — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-memory.html
- Environment and Skills — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-environment.html
- Observability and cost controls — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-operations.html
- Security and access controls — https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html

If the docs change, this tip is a snapshot of that day — check the sources for current behaviour.

---

*This page — research, writing, verification, and deployment — was built by Claude Cowork. The tip was generated this morning, cross-checked against the official AWS docs, and published to Cloudflare R2 on a schedule. A daily experiment by Monty van Emmerik · vanemmerik.ai*