matic (ACID-like) | Real-time thresholds | Proof traces (why permitted) |
Key Findings:
- Infrastructure setup drops by ~90% when shifting from custom plumbing to declarative configuration.
- Governance enforcement shifts from probabilistic (prompts) to deterministic (structural phase checks), eliminating partial-commit failures.
- Budget gating moves from retrospective billing analysis to real-time behavioral control, preventing runaway token/tool costs.
- The sweet spot lies in pairing managed isolation (Harness) with a zero-dependency governance layer (Shape) that enforces read-before-write, transactional rollbacks, and auditable decision chains.
Core Solution
The production-ready architecture decouples runtime execution from permission enforcement:
┌─────────────────────────────────────┐
│ Agent logic (LLM + prompts) │
├─────────────────────────────────────┤
│ Shape (governance) │ ← permission, phases, transactions
├─────────────────────────────────────┤
│ AgentCore Harness (infrastructure) │ ← compute, memory, networking
└─────────────────────────────────────┘
AgentCore Harness (Infrastructure Layer)
AgentCore Harness replaces custom orchestration plumbing with a declarative configuration. It provides:
- Isolated compute: Per-session microVMs with dedicated filesystems and shells for setup, scripting, and debugging.
- Stateful by default: Persistent short/long-term memory and filesystem across sessions.
- Multi-model, mid-session: Switch between Amazon Bedrock, OpenAI, or Google Gemini without context loss.
- Tool connectivity: AgentCore Gateway, MCP servers, built-in browser, and code interpreter.
- Observability & Security: Full action tracing, VPC networking, identity management, and per-session access controls.
- Custom environments: Bring your own source, dependencies, and tools.
Shape (Governance Layer)
Shape is a single-file Python library (~400 lines, zero dependencies) that enforces deterministic rules at execution time:
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 Capabilities:
- Phase lifecycle: Explore → Decide → Commit. Write tools throw exceptions in Explore mode, enforcing read-before-write structurally.
- Transactional tool calls: All-or-nothing execution with automatic compensation on failure.
- Budget as a control signal: Real-time behavioral gating at configurable thresholds (reduce scope, block commits, hard stop).
- Proof traces: Structured validation records (phase check → budget check → rule check) proving why each call was permitted.
- Human-readable rule DSL: Auditable governance rules decoupled from infrastructure 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
- Relying on Prompt-Based Governance: Prompts are suggestions, not enforcement mechanisms. Under complex reasoning or token pressure, agents will bypass them. Always implement structural phase checks that raise exceptions on policy violations.
- Ignoring Transactional Rollbacks: Multi-step agent workflows lack ACID properties by default. A failure at step 2 leaves step 1 committed, corrupting downstream state. Implement automatic compensation/rollback logic to guarantee all-or-nothing execution.
- Treating Budget as a Post-Mortem Metric: Checking costs after the invoice is too late. Budget must act as a real-time behavioral gate. Configure thresholds that trigger scope reduction, commit blocking, or hard stops before costs spiral.
- Confusing Observability with Governance: Tracing what happened does not prove why it was allowed. Governance requires structured proof traces that validate phase, budget, and rule checks before execution, not just execution logs.
- Coupling Infrastructure and Governance: Embedding governance logic directly into infrastructure code creates vendor lock-in and makes rules difficult to audit or migrate. Decouple them: use Harness for runtime isolation and a separate, dependency-free layer for permission enforcement.
- Skipping the Read-Before-Write Phase: Allowing write operations during exploration leads to partial data corruption and inconsistent state. Enforce strict phase lifecycles where write tools are structurally blocked until the agent explicitly enters Commit mode.
Deliverables
- 📘 Architecture Blueprint:
agentcore-shape-governance-blueprint.pdf — Complete reference architecture detailing microVM isolation, Shape DSL integration, MCP/Gateway routing, and proof-trace generation.
- ✅ Production Governance Checklist:
agent-governance-checklist.md — Step-by-step validation for phase enforcement, rollback configuration, budget thresholds, audit trail completeness, and multi-model switching safety.
- ⚙️ Configuration Templates:
harness-config.yaml — Declarative setup for compute, memory, tool routing, and observability.shape-rules.yaml — Human-readable governance DSL templates for phase gating, budget thresholds, and tool effect mapping.deployment-scripts/ — Ready-to-run scripts for packaging Shape into AgentCore Harness custom environments with zero external dependencies.
