The AgentCore Managed Harness: Model + Prompt + Tools

Running an agent with zero orchestration code.

Every tool-using agent needs a loop: send a prompt, notice the model wants to call a tool, run the tool, feed the result back, repeat until the model is done. On Bedrock's own Converse API, you write that loop yourself - checking stopReason for tool_use and looping until you see end_turn. AgentCore's managed harness is the piece of the platform that can run this same loop for you, so a hosted agent's code can be as small as "here is my model, my prompt, and my tools" with no hand-written loop at all.

This page describes the harness at the level of the shape it presents, not a guaranteed API contract. AgentCore is a 2026 preview capability, and the declarative "model + prompt + tools" configuration described here is the least settled part of its surface - treat method and field names as illustrative and verify against current AWS documentation before depending on them.

Recipe

Quick-reference recipe card - copy-paste ready. Field and operation names are illustrative; verify at build time.

# --- Python (boto3) --- illustrative shape, verify exact fields at build time
import boto3, json
 
client = boto3.client("bedrock-agentcore", region_name="us-east-1")
resp = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/harness-agent",
    payload=json.dumps({"prompt": "What's the status of order 4821?"}).encode(),
)
print(json.loads(resp["response"].read()))

// --- TypeScript (AWS SDK v3) --- illustrative shape, verify exact fields at build time
import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore";
 
const client = new BedrockAgentCoreClient({ region: "us-east-1" });
const resp = await client.send(new InvokeAgentRuntimeCommand({
  agentRuntimeArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/harness-agent",
  payload: new TextEncoder().encode(JSON.stringify({ prompt: "What's the status of order 4821?" })),
}));
console.log(new TextDecoder().decode(resp.response as Uint8Array));

• From the caller's side, invoking a harness-managed agent looks identical to invoking any AgentCore Runtime - one request in, one final answer out.
• The difference is internal: if the model wants to call a tool mid-answer, the harness runs that loop server-side before returning.
• You never see the intermediate tool_use turns unless you specifically ask for tracing (see the observability page).
• This is the same invoke surface shown on the basics page - the harness is a mode of operating an agent, not a different client.

Working Example

Here is the declarative side: what you configure so the harness knows which model, prompt, and tools to use. Treat this as the most speculative snippet on this page.

# --- Python (boto3) --- highly illustrative; the actual config surface may differ, verify at build time
import boto3
 
control = boto3.client("bedrock-agentcore-control", region_name="us-east-1")
control.update_agent_runtime(  # representative operation name only
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/harness-agent",
    modelId="amazon.nova-lite-v1:0",
    systemPrompt="You are a support agent. Use tools to look up order status; never guess.",
    toolGatewayArn="arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/support-tools",
)

// --- TypeScript (AWS SDK v3) --- highly illustrative; the actual config surface may differ, verify at build time
import { BedrockAgentCoreControlClient, UpdateAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore-control";
 
const control = new BedrockAgentCoreControlClient({ region: "us-east-1" });
await control.send(new UpdateAgentRuntimeCommand({ // representative operation name only
  agentRuntimeArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/harness-agent",
  modelId: "amazon.nova-lite-v1:0",
  systemPrompt: "You are a support agent. Use tools to look up order status; never guess.",
  toolGatewayArn: "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/support-tools",
}));

What this demonstrates:

• Three inputs define the agent's behavior: which model answers, what instructions steer it, and which tools (typically surfaced via a Gateway) it may call.
• None of this configuration includes a loop, a retry policy, or tool-result plumbing - that is exactly the part the harness is meant to absorb.
• Whether this configuration happens through a control-plane API call, a config file bundled with your deployment, or CLI flags is genuinely unclear from public materials at time of writing - all three are plausible, and you should confirm the real mechanism before building tooling around it.
• Swapping the model id or editing the system prompt here is meant to be a config change, not a code change - consistent with how Converse treats modelId on the plain Bedrock Runtime side.

Deep Dive

Why a Managed Loop Matters

A tool-calling loop is small in code but easy to get subtly wrong: forgetting to append the assistant's tool-call turn before the tool result, not capping iterations, or mishandling a tool error mid-loop. Every team building a tool-using agent on Bedrock directly has written some version of this same loop. The managed harness exists to make that loop a platform concern - written once by AWS, exercised by every agent that opts into it - the same argument AgentCore Runtime makes for hosting infrastructure generally.

How This Differs From Runtime Alone

AgentCore Runtime, on its own, will host any packaged entrypoint - including one where you write the full tool loop yourself using a framework like LangGraph or Strands, or by hand against Converse's toolConfig. The managed harness is a further step: instead of your entrypoint containing a loop, it contains a declaration, and AWS's own harness code runs the loop. Both are "an agent on AgentCore," but only one has zero orchestration code in your repository.

This matters for how much you can inspect and customize. A hand-written loop is fully yours to modify - add custom retry logic, short-circuit on certain tool results, log whatever you want mid-loop. A harness-managed loop trades that flexibility for less code and less to maintain, similar to the trade-off Converse itself makes versus InvokeModel on the plain inference side.

Where Tools Come From

The tools available to a harness-managed agent are expected to come primarily from AgentCore Gateway - the piece of AgentCore that turns existing APIs, Lambda functions, and services into agent-callable tool definitions - plus any built-in tools AWS ships (a managed web-search tool is covered later in this section). The harness page and the Gateway page are tightly coupled: Gateway defines what a tool is, and the harness decides when to call it during a conversation.

Gotchas

• Assuming the harness is the only way to run an agent on AgentCore. It is not - Runtime also hosts hand-written orchestration. Fix: pick the harness for "declare model+prompt+tools" simplicity; pick a hand-written loop when you need custom control-flow.
• Expecting to see intermediate tool-call turns in the invoke response. A harness-managed loop is expected to return only the final answer unless you opt into tracing. Fix: use the observability page's guidance to inspect intermediate steps when debugging.
• Treating the config example above as a confirmed API. It is intentionally the most speculative snippet in this section. Fix: confirm the real configuration mechanism (API call, file, or CLI) in AWS's current AgentCore docs before scripting against it.
• Forgetting the harness still needs a real system prompt. A managed loop does not make prompt engineering unnecessary - a vague prompt still produces vague tool use. Fix: write the same specific, grounded instructions you would for any tool-using agent.
• Assuming every model works identically inside the harness. Tool-calling quality varies by model family, same as with Converse's toolConfig. Fix: evaluate your chosen model's tool-use behavior directly rather than assuming parity.

Alternatives

FAQs

Related

• AgentCore's Managed Agent Runtime - the hosting layer the harness runs on top of.
• AgentCore Gateway & Tool Registration - where the harness's tools typically come from.
• The Managed Web Search Tool - a built-in tool the harness can call.
• Observability & Guardrails for Production Agents - inspecting what the loop actually did.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). Amazon Bedrock AgentCore is a fast-moving 2026 preview capability - verify exact API/CLI surface against current AWS docs before relying on specific method names.