mission Enforcement | Rollback Success Rate | Budget Spike Mitigation | Audit Trail Depth |
|----------|-------------------------|--------------------------------|-----------------------|-------------------------|-------------------|
| Traditional Frameworks (LangGraph/CrewAI) | 5–8 | None (prompt-dependent) | 42% (manual intervention) | 0% (post-hoc billing) | Action logs only |
| AgentCore Harness (Infrastructure Only) | 1–2 | None (observability-focused) | 42% (manual intervention) | 0% (post-hoc billing) | Action logs only |
| AgentCore Harness + Shape (Governance Layer) | 1–2 | Strict phase & rule enforcement | 98.7% (automatic compensation) | 94.2% (real-time behavioral gates) | Decision-chain proof traces |
Key Findings:
- Sweet Spot: Decoupling governance from infrastructure reduces setup time by ~80% while achieving near-perfect transactional rollback rates.
- Governance Latency: Rule evaluation adds <12ms overhead per tool call, negligible compared to LLM inference latency.
- Compliance Readiness: Proof traces provide cryptographic decision chains, reducing audit preparation time from weeks to hours.
Core Solution
The solution decouples infrastructure provisioning from runtime governance. AgentCore Harness provides the execution environment, while Shape enforces permission boundaries, transactional integrity, and budget-aware behavior.
Architecture Decision
┌─────────────────────────────────────┐
│ Agent logic (LLM + prompts) │
├─────────────────────────────────────┤
│ Shape (governance) │ ← permission, phases, transactions
├─────────────────────────────────────┤
│ AgentCore Harness (infrastructure) │ ← compute, memory, networking
└─────────────────────────────────────┘
Deploy Shape inside an AgentCore Harness custom environment. The harness provides the runtime. Shape decides what the agent is allowed to do inside it.
Technical Implementation
Shape is a single-file Python library (~400 lines, zero dependencies) that introduces structured enforcement at the tool-call boundary:
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
Enforcement Mechanisms
- Phase Lifecycle: Explore → Decide → Commit. In Explore, only read tools execute. Write attempts raise exceptions, enforcing read-before-write structurally.
- Transactional Tool Calls: Commit blocks execute atomically. Failure triggers automatic compensation, mirroring ACID principles adapted for agent toolchains.
- Budget as Control Signal: Configurable thresholds dynamically alter behavior: scope reduction, commit blocking, forced re-evaluation, or hard stops.
- Proof Traces: Every permitted call records phase validation, budget checks, and rule evaluations, producing a decision chain rather than a flat log.
- Human-Readable Rule DSL: Governance policies are declarative, auditable, and decoupled from application code.
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
- Confusing Observability with Governance: Logging tool executions does not prevent unauthorized actions. Observability answers "what happened"; governance must answer "was this allowed?" Always enforce rules at the call boundary, not in post-processing logs.
- Relying on Prompt Discipline for Phase Control: LLMs do not guarantee adherence to read-before-write instructions under complex reasoning paths. Structural enforcement via phase contexts (
agent.explore() vs agent.commit()) is required to prevent partial writes.
- Ignoring Transactional Boundaries in Multi-Step Workflows: Treating sequential tool calls as independent operations guarantees state corruption on mid-workflow failures. Wrap state-mutating sequences in commit blocks to enable automatic compensation.
- Treating Budget as a Post-Hoc Metric: Monitoring costs after invoice generation provides zero operational control. Implement real-time budget gates that modify agent behavior (scope reduction, hard stops) before thresholds are breached.
- Coupling Infrastructure and Governance Logic: Embedding permission checks inside infrastructure code creates vendor lock-in and complicates audits. Maintain a strict layer boundary: harness manages runtime resources, governance library manages policy enforcement.
- Overlooking Proof Trace Requirements for Compliance: Flat execution logs fail compliance audits that require decision justification. Ensure every tool call records phase validation, budget state, and rule evaluation to produce auditable decision chains.
- Deploying Governance Without Isolation: Running governance rules in shared environments risks cross-session state leakage. Always pair Shape with microVM isolation (AgentCore Harness) to guarantee per-session filesystem and memory boundaries.
Deliverables
- 📘 Deployment Blueprint: Step-by-step architecture guide for provisioning AgentCore Harness custom environments, integrating Shape as a governance sidecar, and configuring VPC networking with per-session access controls.
- ✅ Runtime Governance Checklist: Pre-production validation matrix covering phase boundary testing, transactional rollback verification, budget threshold calibration, and proof trace audit readiness.
- ⚙️ Configuration Templates: Ready-to-use Shape DSL policy files, AgentCore environment YAML manifests, and tool-effect mapping schemas for READ, REVERSIBLE, and IRREVERSIBLE operations.
