// agent-contract.ts
import { ModelProvider, ToolDefinition, MemoryConfig } from '@aws-sdk/client-bedrock-agentcore';

export interface AgentContract {
  modelId: string;
  directivePath: string;
  tools: ToolDefinition[];
  memory: MemoryConfig;
  policyPath: string;
}

export const validateContract = (contract: AgentContract): boolean => {
  if (!contract.modelId.includes('anthropic.claude') && !contract.modelId.includes('amazon.nova')) {
    throw new Error('Unsupported model family for managed harness');
  }
  if (contract.tools.length > 20) {
    console.warn('Tool registry exceeds recommended threshold; consider routing optimization');
  }
  return true;
};

// agent-manifest.json
{
  "version": "1.0-preview",
  "runtime": {
    "model": "anthropic.claude-sonnet-4-20250514",
    "directive": "directive.md",
    "max_turns": 12,
    "timeout_seconds": 300
  },
  "tool_registr

y": { "gateway": "mcp-standard", "endpoints": [ { "name": "task-manager", "url": "https://internal.mcp/tasks", "auth": "iam-role" }, { "name": "doc-retriever", "url": "https://internal.mcp/docs", "auth": "iam-role" } ] }, "memory": { "store": "agentcore-memory", "strategy": "semantic-hybrid", "retention_days": 90 } }

### Step 3: Enforce Boundaries with Cedar Policy
Cedar provides formal verification of tool access. Unlike documentation-based constraints, Cedar policies are evaluated at runtime before tool invocation.

```cedar
// agent-policy.cedar
permit (
  principal == aws::agent::core,
  action == aws::mcp::invoke,
  resource == aws::mcp::tool::task-manager
) when {
  context.user_role == "operator" &&
  context.request_scope in ["create", "update"]
};

forbid (
  principal == aws::agent::core,
  action == aws::mcp::invoke,
  resource == aws::mcp::tool::doc-retriever
) when {
  context.request_scope == "delete"
};

Step 4: Wire Observability & Evaluation

The managed harness automatically emits traces to CloudWatch. You must configure evaluation metrics to quantify agent performance.

// observability-config.ts
export const setupTelemetry = () => {
  return {
    cloudwatch: {
      namespace: 'AgentCore/ManagedHarness',
      metrics: ['ToolSelectionAccuracy', 'ResponseHelpfulness', 'ContextDriftScore'],
      retention_days: 30
    },
    evaluation: {
      pipeline: 'continuous',
      dimensions: ['accuracy', 'safety', 'latency'],
      threshold: { tool_selection_accuracy: 0.85 }
    }
  };
};

Architecture Rationale

• Declarative over Imperative: The manifest isolates design decisions from execution logic. This enables version control, peer review, and automated validation without touching runtime code.
• Cedar for Formal Policy: Natural language boundaries are unenforceable. Cedar’s policy language compiles to deterministic rules, preventing tool misuse before execution.
• Gateway Routing: MCP standardization allows tool endpoints to be swapped without modifying the harness. The gateway handles authentication, rate limiting, and response normalization.
• Memory Segmentation: Hybrid retrieval (semantic + keyword) prevents context pollution. Retention policies align with data governance requirements.

Pitfall Guide

1. Configuration Creep

Explanation: Treating the harness manifest as a script repository. Developers embed conditional logic, retry strategies, or state management directly into the config file. Fix: Keep the manifest strictly declarative. Move conditional routing to tool definitions or Cedar policies. Use external validation scripts to enforce schema compliance.

2. Policy Ambiguity

Explanation: Relying on system prompts or documentation to restrict tool access. Prompts are suggestions; policies are enforcement mechanisms. Fix: Implement Cedar policies for every tool endpoint. Use automated policy testing to verify deny/allow rules before deployment. Never trust prompt-based boundaries in production.

3. Memory Fragmentation

Explanation: Dumping all knowledge into a single vector store without segmentation. This causes retrieval conflicts and context drift. Fix: Partition memory by domain or task. Apply explicit retrieval rules in the manifest. Use metadata tagging to isolate cross-functional knowledge.

4. Tool Over-Exposure

Explanation: Registering all available MCP servers by default. This increases attack surface and degrades model decision quality. Fix: Apply least-privilege routing. Register only tools required for the agent’s scope. Use Cedar policies to restrict actions per endpoint.

5. Observability Blind Spots

Explanation: Assuming CloudWatch logs equal distributed traces. Logs show what happened; traces show why it happened across model/tool boundaries. Fix: Enable span-based tracing with correlation IDs. Monitor tool selection accuracy and context drift scores. Set alerts for latency spikes or retry loops.

6. Evaluation Neglect

Explanation: Deploying without quantitative metrics. Subjective assessment fails at scale and masks degradation. Fix: Implement continuous evaluation pipelines. Track tool selection accuracy, response helpfulness, and correctness. Set thresholds and automate rollback on breach.

7. Premature Optimization

Explanation: Tuning retrieval strategies or policy rules before validating core agent behavior. This wastes engineering cycles on unproven workflows. Fix: Deploy a minimal viable harness first. Validate tool routing and directive effectiveness. Optimize memory and policy only after baseline metrics stabilize.

Production Bundle

Action Checklist

• Define agent contract: model, directive, tool registry, memory strategy
• Validate manifest schema: enforce declarative structure, reject imperative logic
• Author Cedar policies: formalize tool boundaries, test deny/allow rules
• Configure memory segmentation: partition by domain, apply retrieval rules
• Enable CloudWatch tracing: correlate spans across model/tool calls
• Deploy evaluation pipeline: track accuracy, helpfulness, latency thresholds
• Run integration validation: simulate user workflows, verify policy enforcement
• Document design decisions: record rationale for tool selection, memory layout, policy scope

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo/Prototype	Managed Harness (Minimal Config)	Fast iteration, zero infra overhead, sufficient for single-user validation	Low (pay-per-use model calls)
Team/Internal	Managed Harness + Cedar Policies + Continuous Eval	Enforces boundaries, provides observability, scales with team collaboration	Medium (policy testing, eval pipeline costs)
Enterprise/External	Managed Harness + Strict Policy + Memory Segmentation + Eval SLAs	Meets compliance, prevents tool misuse, ensures consistent quality at scale	High (governance overhead, dedicated eval infrastructure)

Configuration Template

// agent-harness.config.json
{
  "version": "1.0-preview",
  "runtime": {
    "model": "anthropic.claude-sonnet-4-20250514",
    "directive": "directive.md",
    "max_turns": 10,
    "timeout_seconds": 240
  },
  "tool_registry": {
    "gateway": "mcp-standard",
    "endpoints": [
      { "name": "workflow-engine", "url": "https://mcp.internal/workflows", "auth": "iam-role" },
      { "name": "knowledge-base", "url": "https://mcp.internal/kb", "auth": "iam-role" }
    ]
  },
  "memory": {
    "store": "agentcore-memory",
    "strategy": "semantic-hybrid",
    "retention_days": 60,
    "partitions": ["ops", "dev", "security"]
  },
  "policy": {
    "engine": "cedar",
    "file": "agent-policy.cedar",
    "enforcement": "strict"
  },
  "observability": {
    "namespace": "Prod/AgentHarness",
    "metrics": ["ToolSelectionAccuracy", "ResponseHelpfulness", "ContextDriftScore"],
    "tracing": true
  }
}

// agent-policy.cedar
permit (
  principal == aws::agent::core,
  action == aws::mcp::invoke,
  resource == aws::mcp::tool::workflow-engine
) when {
  context.user_role == "operator" &&
  context.request_scope in ["execute", "status"]
};

forbid (
  principal == aws::agent::core,
  action == aws::mcp::invoke,
  resource == aws::mcp::tool::knowledge-base
) when {
  context.request_scope == "write"
};

Quick Start Guide

1. Initialize the manifest: Create agent-harness.config.json with your target model, directive path, and tool endpoints. Keep it declarative.
2. Define Cedar policies: Write agent-policy.cedar to restrict tool actions. Validate syntax using the Cedar CLI before deployment.
3. Deploy the harness: Use the AWS CLI or SDK to register the manifest with Bedrock AgentCore. The managed runtime will provision the microVM, gateway routing, and observability pipeline automatically.
4. Validate & iterate: Run simulated user queries. Monitor CloudWatch traces for tool selection accuracy and context drift. Adjust directive or policy boundaries based on evaluation metrics.