egrity, 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.