Key takeaways
- AgentCore Harness lets AWS own the agent loop and execution.
- Desired control over the runtime should drive the choice.
- Harness passes skill content to the agent without validating, sanitizing, or inspecting it, so teams still own skill-source trust.
An AWS agent harness is an ownership choice before it is a feature choice. The useful question is not which option has the longest service list. It is whether AWS or your team should own the loop, orchestration, runtime infrastructure, application workflow, and controls around consequential tool calls. That boundary becomes the basis for implementation, testing, and failure handling.
What is the point of an agent harness?
The point of an agent harness is to turn the machinery around a model into an operating system you can configure and control. With AgentCore Harness, that machinery includes infrastructure, orchestration, tool wiring, memory, runtime isolation, and observability. The model is only one component. The harness determines how the system runs around it.
Memory shows why this boundary matters. AgentCore Memory combines short-term event storage with long-term memory extraction, allowing an application to maintain contextual interactions without operating the memory infrastructure itself. That is a concrete transfer of responsibility, not merely an extra feature.
The two memory functions solve different parts of the same context problem. Short-term event storage keeps the events used in an interaction. Long-term extraction supplies the other memory function named in the service design. The application can use both without taking on the memory infrastructure. What changes is who operates that layer, not the need to decide what the agent should retain and use.
The same distinction applies across the rest of the harness. Infrastructure, orchestration, tool wiring, runtime isolation, and observability can become configuration. Each configured mechanism still expresses an operating choice. Tools define what the agent can call. Runtime isolation defines where execution sits. Observability defines what execution can expose when something goes wrong.
We use the word harness for the surrounding controls because reliability depends on more than model behavior. Our five-lever agent harness guide develops that broader architecture. On AWS, however, the immediate design decision is narrower: decide what AWS will operate and what remains inside your application.
Who should own the loop, runtime, and application layer?
Start with the workload that already exists. AgentCore Harness, AgentCore Runtime, and a custom API with Lambda place responsibility at different layers. None is a universal winner.
| Path | Workload fit | Retained responsibility | Limitation |
|---|---|---|---|
| AgentCore Harness | In the cited architecture guide, most enterprise-search assistants use Harness while reaching knowledge through MCP or API tools. | Your team defines the model, instructions, tools, memory, and configuration. AWS owns the agent loop and execution. | Harness treats skill content as trusted input and does not validate, sanitize, or inspect the content or source before passing it to the agent. |
| AgentCore Runtime | In the cited guide, a custom workflow or multi-agent platform uses Runtime. | Your team owns orchestration while AWS manages runtime infrastructure. | Runtime V2 create and update operations can take several minutes to reach READY because snapshot preparation adds a one-time cost. |
| Custom API with Lambda | In the cited guide, this path fits an existing backend or product workflow that already owns routing, authentication, user experience, and release management. | The application keeps those existing workflow responsibilities. | A Lambda function that blocks while an AgentCore agent runs spends most of its billed time waiting. |
Use retained responsibility as an exclusion test. A path is a poor match when it transfers a layer your team intends to control or leaves the team operating a layer it intends AWS to manage. That test makes the workload fit concrete without treating any row as the default.
Which AWS agent harness fits the work?
The best agent harness is the one that matches how much runtime control your team wants to retain. That criterion is more durable than a feature-count comparison.
Use a build-versus-adopt review that covers the full operating boundary:
- Runtime control: How much control over the runtime does your team need to retain?
- Managed scope: Should AWS manage orchestration and infrastructure, or does your team need to operate those layers?
- Inspectability: Must your team inspect, customize, or self-host the harness?
- Certified authority: Which principals may change the model, tools, memory, configuration, or skill sources, and where is that authority enforced?
- Context load: What instructions, memory, and skill content enter the agent context for each invocation?
- Reversibility: Which tool effects can be reversed, and where does that capability live outside the agent loop?
- Post-failure behavior: What state will the next attempt receive, and can a failed call replay incomplete history?
AgentCore Harness provides an abstraction for teams that want AWS to manage orchestration and infrastructure. An open-source alternative exposes the harness for inspection, customization, and self-hosting. The remaining checks keep the choice tied to authority, context, reversibility, and failed-state behavior instead of treating deployment as the whole decision.
The checklist does not settle coordination design inside a team-owned path. If coordination is the harder problem, our guide to AI agent orchestration frameworks compares choices through coordination cost. That is a separate design question from whether the harness itself should be managed or open to inspection and change.
How should a consequential tool call move through controls?
Trace one proposed tool call in order, from the caller's authority through the state used after execution. No single AWS service owns this entire path.
| Stage | Mechanism | Failure boundary |
|---|---|---|
| 1. Identity and input authority | Control which principals may override the skills field. Skills can be overridden on each InvokeHarness call. | Forwarding caller-supplied input can introduce skill sources containing arbitrary instructions or scripts. |
| 2. Permission decision | AgentCore Gateway Policy checks the tool action against configured rules. | The configured policy allows or denies that action. |
| 3. Human approval | Identify operations that require human oversight, then choose a centralized, tool-specific, asynchronous, or real-time approval pattern. | The approval requirements determine which pattern applies. |
| 4. State and deterministic application | In the cited Step Functions design, orchestration, fan-out, validation, routing, and retries remain outside agent reasoning. | Agent output is applied only after deterministic validation. |
| 5. Execution evidence | AgentCore CloudWatch dashboards and OpenTelemetry traces expose execution behavior. | The surfaced failure categories include infinite loops and tool-invocation failures. |
| 6. Recovery state | Store the corresponding ToolMessage or toolResult with a checkpointed toolUse. | A missing result can replay malformed history, causing retries and later turns to fail deterministically. |
Skill sources are part of the security boundary
AgentCore Harness can fetch skill bundles containing Markdown and scripts from Amazon S3 or Git at invocation time, then inject them into the agent context. That flexibility makes the source of a skill part of the system's trust boundary.
Implementers are responsible for using trusted, access-controlled sources. They are also responsible for reviewing skill instructions and scripts, and for controlling which principals may override the skills field. Those duties remain with the team even when AWS owns the agent loop.
There are three concrete review surfaces here. The S3 location or Git repository must be trusted and access-controlled. The Markdown instructions and scripts inside the bundle must be reviewed. The principals that can replace the skills field must be controlled. Treating only the storage location as trusted leaves the other two surfaces unaddressed.
Two mitigations are concrete. Strip or ignore the skills field in caller-supplied requests when callers should not control it. Where overrides are needed, allowlist the permitted S3 prefixes or Git repositories. These controls narrow which sources can reach the agent. They do not change the fact that Harness passes accepted skill content into context.
The choice between those mitigations depends on whether callers need any influence over skills. If they do, constrain the field to approved locations. In both cases, keep content review and principal control as explicit implementation work. The managed agent loop does not perform that review for the team.
What changes when AgentCore Runtime V2 starts?
Runtime V2 changes the deployment lifecycle because create and update operations prepare and snapshot the environment. That snapshot work is different from Runtime V1 behavior and happens before the runtime becomes ready.
Preparation and health reporting are separate parts of that lifecycle. The create or update operation prepares the environment and its snapshot. The runtime then has to finish initialization before its health signal says it is healthy. A response from the create operation does not replace either condition.
The health endpoint must reflect real initialization state. For Runtime V2, /ping should report healthy only after initialization finishes. If the runtime does not report healthy within 120 seconds of startup, creation fails with a health-check error.
This creates a precise startup contract. Do not make /ping healthy while initialization is still in progress. The service uses that signal to decide whether creation succeeded, so the application must connect its health response to completed initialization.
The 120-second limit belongs to the startup health check. It is not a signal to report healthy early. Initialization has to finish first, and a runtime that does not report healthy within that window fails creation with a health-check error. Startup code therefore needs a truthful readiness condition that can complete inside that limit.
Runtime updates need state-aware clients
After an AgentCore Runtime V2 create or update request returns, the client should poll get_agent_runtime until status is READY or FAILED. Those are the terminal states that determine what the client can do next.
An update or deletion attempted before the runtime reaches a terminal state returns ConflictException. The client therefore needs state-aware control flow around deployment changes. The return of the create or update request is not the readiness signal.
A minimal client state path has three decisions. Poll after the create or update request returns. Continue waiting while the runtime has not reached a terminal state. At READY, the operation has completed successfully; at FAILED, handle the failed operation. Do not send an update or deletion during the nonterminal part of that path.
Runtime V2 also limits environment-variable size by deployment type. Direct-code deployments have a 1.5 KB limit. Container agents have a 2.5 KB limit. Exceeding the applicable limit causes ValidationException.
Keep those limits attached to the correct packaging path. A client can validate the size for its deployment type before submitting the operation, then use runtime polling to follow the resulting state. The size check and state check govern different parts of the same deployment workflow.
This gives the client two failure conditions to handle without confusing them. An oversized environment-variable payload fails validation before it can become a healthy runtime. A submitted create or update can later end in FAILED. The applicable size limit comes from the packaging model, while the terminal status comes from get_agent_runtime.
Tracing narrows diagnosis, and evaluation gates quality
Observability and evaluation answer different operating questions. Traces help locate an execution failure. Evaluation tests whether agent behavior meets the quality gates selected for its lifecycle.
In AWS's production-debugging example, structured observability turned hours of guesswork into minutes of targeted investigation. The result is about narrowing diagnosis. It supports investing in structured investigation rather than relying on guesswork when an execution fails. Our glossary entry on agent observability places those signals in the wider harness.
An AWS reference implementation organizes agent evaluation into four layers: tool usage, reasoning, output quality, and domain-specific checks. Together, those checks provide quality gates across the agent lifecycle. They do not serve the same purpose as a trace. Our note on agent evaluation develops the distinction between observing execution and judging behavior.
The four layers prevent one result from standing in for every kind of quality. Tool usage, reasoning, output quality, and domain-specific checks remain named parts of the reference design. A lifecycle gate can include all four without pretending that good output alone proves correct tool use, or that a sound reasoning check proves the domain-specific result.
That separation also changes what to inspect after a failure. Use structured observability to target the execution investigation. Use the evaluation layers as quality gates across development and operation. They can work together, but they answer different questions about the same agent system.
How can a long-running AgentCore call avoid idle Lambda time?
Replace a blocking Lambda path with one of three patterns AWS presents for this AgentCore pipeline: a task-token callback, a direct service integration, or a durable function. Each removes the need for a Lambda function to spend most of its billed time waiting while the agent runs.
The cost boundary matters. Across the four cases in the cited comparison, agent and model cost stays unchanged. What changes is orchestration overhead and, for the blocking anti-pattern, wasted idle Lambda compute. Moving to an asynchronous pattern does not make the agent or model cheaper in those cases.
That distinction keeps the architecture comparison honest. The agent still runs, and the model is still invoked. The savings opportunity identified in the blocking anti-pattern is the Lambda time spent waiting. The other differences belong to orchestration overhead, not to a claimed reduction in model work.
The choice among the three alternatives is therefore an orchestration decision. A task-token callback, direct service integration, and durable function structure the wait differently. The supported comparison does not rank one as universally best. It establishes the problem each avoids: holding a billed Lambda invocation open while the AgentCore call continues.
Evaluate these alternatives against the workflow around the call. If the goal is specifically to remove idle Lambda waiting, all three are presented as alternatives to the blocking path. Do not justify the change with lower agent or model cost, because that cost remains unchanged across the four cited cases.
Where can you inspect AWS agent examples on GitHub?
For an AWS agent harness GitHub reference, start with artifacts that expose the code and orchestration shape. The Strands Agents GitHub organization provides open-source tools for building and running AI agents in Python and TypeScript. It is a direct place to inspect an open-source agent toolchain.
AWS also provides a sample for its asynchronous patterns. The sample includes a complete AgentCore agent, state-machine definitions, and a durable function for asynchronous Step Functions patterns. Those components let you inspect the agent and the surrounding orchestration in the same reference.
The sample is useful because the orchestration artifacts are present alongside the agent. You can inspect the state-machine definitions and durable function as concrete implementations of the asynchronous patterns. The repository is an implementation reference, not proof that the design will meet the performance needs of a different workload.
These repositories answer different implementation questions. Strands Agents exposes tools for building and running agents. The AWS asynchronous sample shows the agent beside state-machine definitions and a durable function. Neither repository settles the responsibility choice for your workload. Use the matrix first, then inspect the code that matches the layer your team intends to own.
For a broader method that connects authority, state, evaluation, and recovery, read our five-lever agent harness guide.