AMAZON BEDROCK / SERVICE DETAIL S01 HARNESS
THE MANAGED HARNESSPRACTICAL 2 / 2GA
CHAPTER 06 / 36
TOPIC let AgentCore run the loop
REV 2026.07
New to these words? Sheet 01-A "Key terms" defines agent, tool, the loop, session, and microVM.
IN PLAIN WORDS
Three ways to run the managed harness in the cloud, from easiest to most manual: the command-line tool, raw AWS commands, or Python. Terms: execution role = an AWS identity the harness is allowed to act as; control plane = admin commands (create, get); data plane = run-time commands (invoke); session id = a name for one conversation (here at least 33 characters); streaming = the answer arrives piece by piece.
[ 1 ] PREREQUISITES
[x] AWS credentials in a supported region (GA in 15 Regions, incl. N. Virginia, Oregon, Frankfurt, Sydney; see the AgentCore regions page)
[x] For the CLI: Node.js 20+
[x] For the SDK: Python 3.10+, boto3, and an IAM execution role the harness can assume
[x] If no model is set, the harness defaults to Claude Sonnet 4.6 on Bedrock
[ 2 ] PATH A, THE AGENTCORE CLI (fastest)
$ npm install -g @aws/agentcore # AgentCore CLI (Node 20+)
$ agentcore create --name myresearchagent --model-provider bedrock
$ agentcore deploy
$ agentcore invoke --harness myresearchagent \
--session-id "$(uuidgen)" \
"Research three tropical vacation options under $3k, within five hours of NYC."
$ agentcore dev # local inspector, deploys resources first
Reuse the same --session-id to continue the conversation in the same environment. Add a harness with `agentcore add harness`.
[ 3 ] PATH B, THE AWS CLI (control plane)
$ aws bedrock-agentcore-control create-harness \
--harness-name "MyHarness" \
--execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"
$ aws bedrock-agentcore-control get-harness \
--harness-id "MyHarness-XyZ123" # poll until "status": "READY", note the arn
[ 4 ] PATH C, INVOKE FROM PYTHON (boto3, streaming)
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_harness(
harnessArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-XyZ123",
runtimeSessionId="1234abcd-12ab-34cd-56ef-1234567890ab",
messages=[{
"role": "user",
"content": [{"text": "Research three tropical vacation options under $3k."}]
}],
)
for event in response["stream"]:
if "contentBlockDelta" in event:
delta = event["contentBlockDelta"].get("delta", {})
if "text" in delta:
print(delta["text"], end="", flush=True)
elif "runtimeClientError" in event:
print(f"\nError: {event['runtimeClientError']['message']}")
| STREAM EVENT | MEANING |
|---|
| messageStart | new message begins (includes role) |
| contentBlockStart | block begins: text, toolUse, or toolResult |
| contentBlockDelta | incremental text or toolUse input |
| contentBlockStop | block ends |
| messageStop | message ends, includes stopReason |
| metadata | token usage and latency |
| runtimeClientError | error during execution |
[ 5 ] STOP REASONS (why the loop ended)
| stopReason | MEANING | stopReason | MEANING |
|---|
| end_turn | finished normally | max_iterations_exceeded | maxIterations limit hit |
| tool_use | calling an inline function, waiting for a client result | timeout_exceeded | timeoutSeconds limit hit |
| max_tokens | per-turn token limit reached | max_output_tokens_exceeded | maxTokens budget exhausted |
The runtimeSessionId must be at least 33 characters. Control plane ops: CreateHarness, GetHarness, UpdateHarness, DeleteHarness, ListHarnesses. Data plane: InvokeHarness.