errun Incidents (Monthly) | Tool Call Latency Overhead | |----------|-------------------|-----------------------|---------------------------------|----------------------------------|----------------------------| | Custom Harness + Ad-hoc Governance | 5–10 | 65% | 78% | 4–7 | ~120ms | | AgentCore Harness + Shape Governance | <1 | 99.9% | 100% | 0–1 | ~15ms |

Key Findings:

• Structural phase enforcement eliminates read-before-write violations by raising hard exceptions instead of relying on LLM compliance.
• Atomic transaction boundaries guarantee all-or-nothing execution for irreversible tool calls, reducing manual cleanup operations by >90%.
• Budget-as-control-signal architecture prevents cost spikes by dynamically gating behavior at configurable thresholds before invoice generation.
• Proof traces provide a deterministic decision chain (phase → budget → rule checks) that satisfies audit requirements without instrumenting every downstream service.

Core Solution

The recommended architecture strictly separates the execution runtime from the permission layer. AgentCore Harness provides the infrastructure foundation, while Shape enforces governance at the tool-call boundary.

Architecture Decision

Deploy Shape inside an AgentCore Harness custom environment. The harness manages microVM isolation, stateful memory, multi-model switching, VPC networking, and observability. Shape intercepts tool execution to enforce phase lifecycles, transactional semantics, budget gates, and audit trails.

┌─────────────────────────────────────┐
│  Agent logic (LLM + prompts)        │
├─────────────────────────────────────┤
│  Shape (governance)                 │  ← permission, phases, transactions
├─────────────────────────────────────┤
│  AgentCore Harness (infrastructure) │  ← compute, memory, networking
└─────────────────────────────────────┘

Technical Implementation

Shape operates as a single-file Python library (~400 lines, zero dependencies) that wraps tool definitions with effect classifications and rule-based execution gates. It integrates seamlessly into the Harness runtime without modifying underlying model routing or networking configurations.

from shape import Agent, ToolEffect

agent = Agent("customer-service", budget=5.00)
agent.tool("lookup_customer", effect=ToolEffect.READ,         fn=lookup_fn)
agent.tool("update_record",   effect=ToolEffect.REVERSIBLE,   fn=update_fn)
agent.tool("send_email",      effect=ToolEffect.IRREVERSIBLE, fn=email_fn)

agent.rules("""
    BLOCK send_email WHEN phase IS NOT commit
    BLOCK * WHEN budget ABOVE 90%
""")

# EXPLORE: read-only, safe
with agent.explore() as ctx:
    customer = ctx.call("lookup_customer", id="C-1234")

# COMMIT: transactional, all-or-nothing
with agent.commit() as tx:
    tx.call("update_record", cost=0.01, id="C-1234", status="welcomed")
    tx.call("send_email",    cost=0.10, to=customer["email"], template="welcome")
    # if send_email fails → update_record is compensated automatically

Capability Matrix

Capability	AgentCore Harness	Shape
Managed compute and isolation	✓	✗
Persistent memory and filesystem	✓	✗
Multi-model switching	✓	✗
Observability (what happened)	✓	✗
Phase enforcement (read before write)	✗	✓
Transactional tool calls with rollback	✗	✓
Budget as a behavioral gate	✗	✓
Proof traces (why it was permitted)	✗	✓
Human-readable rule DSL	Cedar (via Gateway)	built-in
Vendor lock-in	AWS	none
Dependencies	AWS SDK	zero

Pitfall Guide

1. Conflating Observability with Governance: Tracing execution logs only answers what occurred. Without runtime permission checks, agents will still execute prohibited actions. Implement hard gates at the tool-call boundary.
2. Relying on Prompt Discipline for Phase Control: LLMs degrade under token pressure and will bypass "read before write" instructions. Use structural phase boundaries that raise exceptions on violation, not warnings.
3. Treating Budget as a Post-Mortem Metric: Cost should function as a real-time control signal. Configure threshold-based behavioral changes (scope reduction, commit blocking, hard stops) to prevent runaway inference spend.
4. Manual Compensation for Failed Workflows: Multi-step agent pipelines lack atomicity by default. Adopt automatic compensation mechanisms that roll back reversible actions when irreversible steps fail.
5. Tying Governance to Vendor-Specific SDKs: Locking permission logic to a single cloud provider's IAM or policy language limits portability and increases migration friction. Use framework-agnostic governance libraries that run inside the infrastructure layer.
6. Skipping Proof Traces for Auditability: Compliance requires deterministic proof of why a tool was permitted, not just execution timestamps. Maintain structured decision chains (phase validation → budget check → rule evaluation) alongside standard observability traces.

Deliverables

• 📘 Decoupled Agent Architecture Blueprint: Reference architecture detailing how to deploy Shape inside AgentCore Harness custom environments, including VPC routing, identity propagation, and observability pipeline wiring.
• ✅ Production-Ready Agent Governance Checklist: 12-point validation matrix covering phase boundary testing, transaction rollback verification, budget threshold calibration, and audit trail completeness before production rollout.
• ⚙️ Configuration Templates:
  • shape_rules.yaml: Pre-built Rule DSL templates for common patterns (read-before-write, budget gating, irreversible action locking)
  • harness_env.json: AgentCore Harness custom environment configuration snippet with Shape dependency injection and microVM resource limits