adaptationio/bedrock-agentcore-policy

Amazon Bedrock AgentCore Policy

Overview

AgentCore Policy provides deterministic enforcement of agent boundaries, separate from the probabilistic nature of prompt engineering. Author policies in natural language that automatically convert to Cedar—AWS's open-source policy language—for real-time enforcement at the Gateway layer.

Purpose: Define what agents can and cannot do with deterministic, auditable rules

Pattern: Task-based (5 operations)

Key Principles (validated by AWS December 2025):

1. Natural Language Authoring - Write policies in plain English
2. Automated Cedar Generation - System converts to valid Cedar
3. Real-time Enforcement - Gateway intercepts every tool call
4. Automated Reasoning - Detects overly permissive/restrictive rules
5. Default Deny - No permit policy = automatic denial
6. Forbid Wins - Forbid always overrides permit

Quality Targets:

• Policy generation: < 5 seconds
• Enforcement latency: < 10ms per tool call
• Validation coverage: 100% of tool schemas

---

When to Use

Use bedrock-agentcore-policy when:

• Setting boundaries for what agents can do
• Implementing role-based access control (RBAC)
• Enforcing compliance rules (e.g., max refund amounts)
• Temporarily disabling problematic tools
• Requiring specific parameters for operations
• Auditing agent actions

When NOT to Use:

• Content filtering (use Bedrock Guardrails)
• Rate limiting (use API Gateway)
• Business logic (implement in tools)

---

Prerequisites

Required

• AgentCore Gateway configured
• Tools registered as Gateway targets
• IAM permissions for policy operations

Recommended

• Understanding of Cedar semantics
• Tool schemas documented
• Test scenarios defined

---

Operations

Operation 1: Natural Language Policy Authoring

Time: 2-5 minutes Automation: 95% Purpose: Create policies from plain English descriptions

Process:

1. Define requirements in natural language:

"Allow all users to read policy details and claim status.
Only allow users with 'senior-adjuster' role to update coverage.
Block all claim filings unless a description is provided."

2. Generate Cedar policy:

import boto3

control = boto3.client('bedrock-agentcore-control')

# Start policy generation from natural language
response = control.start_policy_generation(
    gatewayId='gateway-xxx',
    naturalLanguagePolicy="""
    Allow all users to get policy and get claim status.
    Only allow principals with the 'senior-adjuster' role to update coverage.
    Block principals from filing claims unless description is provided.
    """,
    policyName='insurance-agent-policy'
)

generation_id = response['policyGenerationId']

# Wait for completion
waiter = control.get_waiter('PolicyGenerationCompleted')
waiter.wait(policyGenerationId=generation_id)

# Get generated Cedar
result = control.get_policy_generation(
    policyGenerationId=generation_id
)

cedar_policy = result['generatedPolicy']
validation_results = result['validationResults']

3. Review generated Cedar:

// Permit read-only actions for everyone
permit(
    principal,
    action in [
        AgentCore::Action::"InsuranceAPI__get_policy",
        AgentCore::Action::"InsuranceAPI__get_claim_status"
    ],
    resource
);

// Permit updates only for specific roles
permit(
    principal,
    action == AgentCore::Action::"InsuranceAPI__update_coverage",
    resource
)
when {
    principal.hasTag("role") &&
    principal.getTag("role") == "senior-adjuster"
};

// Block claims without description
forbid(
    principal,
    action == AgentCore::Action::"InsuranceAPI__file_claim",
    resource
)
unless {
    context.input has description
};

---

Operation 2: Create Policy Directly (Cedar)

Time: 5-10 minutes Automation: 80% Purpose: Write Cedar policies with full control

Cedar Syntax:

// Basic permit
permit(
    principal,
    action == AgentCore::Action::"ToolName__method",
    resource == AgentCore::Gateway::"arn:..."
);

// With conditions
permit(
    principal is AgentCore::OAuthUser,
    action == AgentCore::Action::"RefundAPI__process_refund",
    resource
)
when {
    context.input.amount < 1000
};

// Forbid with unless
forbid(
    principal,
    action == AgentCore::Action::"DeleteAPI__delete_record",
    resource
)
unless {
    principal.hasTag("role") &&
    principal.getTag("role") == "admin"
};

Create policy via boto3:

response = control.create_policy(
    name='refund-limit-policy',
    description='Limits refunds to under $1000 for non-managers',
    policyContent='''
permit(
    principal,
    action == AgentCore::Action::"RefundToolTarget___refund",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/refund"
)
when {
    context.input.amount < 1000
};

permit(
    principal,
    action == AgentCore::Action::"RefundToolTarget___refund",
    resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/refund"
)
when {
    principal.hasTag("role") &&
    principal.getTag("role") == "manager"
};
'''
)

policy_id = response['policyId']

---

Operation 3: Common Policy Patterns

Time: 5-15 minutes Automation: 90% Purpose: Implement standard access control patterns

Pattern 1: Role-Based Access Control (RBAC)

// Admin-only actions
permit(
    principal,
    action in [
        AgentCore::Action::"AdminAPI__delete_user",
        AgentCore::Action::"AdminAPI__modify_permissions"
    ],
    resource
)
when {
    principal.hasTag("role") &&
    principal.getTag("role") == "admin"
};

Pattern 2: OAuth Scope Validation

// Require specific scope
permit(
    principal is AgentCore::OAuthUser,
    action == AgentCore::Action::"CustomerAPI__read_profile",
    resource
)
when {
    principal.hasTag("scope") &&
    principal.getTag("scope") like "*customer:read*"
};

Pattern 3: Parameter Constraints

// Limit by parameter value
permit(
    principal,
    action == AgentCore::Action::"TransferAPI__transfer_funds",
    resource
)
when {
    context.input has amount &&
    context.input.amount <= 10000
};

Pattern 4: Multi-Condition AND Logic

// All conditions must be true
permit(
    principal,
    action == AgentCore::Action::"InsuranceAPI__update_coverage",
    resource
)
when {
    context.input has coverageType &&
    context.input has newLimit &&
    (context.input.coverageType == "liability" ||
     context.input.coverageType == "collision")
};

Pattern 5: Disable Specific Tool

// Temporarily disable a tool
forbid(
    principal,
    action == AgentCore::Action::"ProblematicAPI__buggy_method",
    resource
);

Pattern 6: User-Specific Permissions

// Grant to specific user
permit(
    principal,
    action == AgentCore::Action::"SpecialAPI__sensitive_action",
    resource
)
when {
    principal.hasTag("username") &&
    principal.getTag("username") == "trusted-user"
};

---

Operation 4: Policy Engine Configuration

Time: 5-10 minutes Automation: 85% Purpose: Attach policies to Gateway for enforcement

Create Policy Engine:

# Create policy engine to evaluate policies
response = control.create_policy_engine(
    name='insurance-policy-engine',
    description='Enforces insurance agent boundaries',
    gatewayId='gateway-xxx'
)

engine_id = response['policyEngineId']

# Wait for active
waiter = control.get_waiter('PolicyEngineActive')
waiter.wait(policyEngineId=engine_id)

Attach Policy to Engine:

# Update policy engine with policies
response = control.update_policy_engine(
    policyEngineId=engine_id,
    policyIds=[
        'policy-read-access',
        'policy-role-restrictions',
        'policy-refund-limits'
    ]
)

Test Policy Enforcement:

# Invoke agent and observe policy enforcement
client = boto3.client('bedrock-agentcore')

response = client.invoke_agent_runtime(
    agentRuntimeArn='arn:...',
    runtimeSessionId='test-session',
    payload={
        'prompt': 'Process a refund of $50000',
        'context': {
            'user_id': 'regular-user',
            'role': 'customer-service'  # Not manager
        }
    }
)

# Policy will block this - amount exceeds $1000 for non-managers
# Agent response will indicate the action was denied

---

Operation 5: Policy Validation and Debugging

Time: 5-15 minutes Automation: 80% Purpose: Test and troubleshoot policy behavior

Validation Checks:

# Get policy validation results
response = control.get_policy_generation(
    policyGenerationId=generation_id
)

for issue in response.get('validationResults', {}).get('issues', []):
    print(f"Issue: {issue['type']}")
    print(f"Message: {issue['message']}")
    print(f"Location: {issue.get('location', 'N/A')}")

# Common issues:
# - Overly permissive (allows more than intended)
# - Overly restrictive (blocks legitimate actions)
# - Unsatisfiable conditions (can never match)
# - Schema mismatch (references non-existent tools)

Debug Policy Decisions:

# Enable detailed logging
import logging
logging.getLogger('botocore').setLevel(logging.DEBUG)

# Check CloudWatch for policy decisions
# Log group: /aws/bedrock-agentcore/gateway/{gateway-id}
# Look for: PolicyDecision events

# Example log entry:
# {
#   "eventType": "PolicyDecision",
#   "action": "InsuranceAPI__file_claim",
#   "decision": "DENY",
#   "matchedPolicy": "policy-require-description",
#   "reason": "Condition not satisfied: context.input has description"
# }

Test Scenarios:

def test_policy_scenarios():
    """Test various policy scenarios"""

    test_cases = [
        {
            'name': 'Regular user reads policy',
            'action': 'get_policy',
            'context': {'role': 'user'},
            'expected': 'ALLOW'
        },
        {
            'name': 'Regular user updates coverage',
            'action': 'update_coverage',
            'context': {'role': 'user'},
            'expected': 'DENY'
        },
        {
            'name': 'Senior adjuster updates coverage',
            'action': 'update_coverage',
            'context': {'role': 'senior-adjuster'},
            'expected': 'ALLOW'
        },
        {
            'name': 'Claim without description',
            'action': 'file_claim',
            'context': {'role': 'user'},
            'input': {'amount': 100},  # No description
            'expected': 'DENY'
        },
        {
            'name': 'Claim with description',
            'action': 'file_claim',
            'context': {'role': 'user'},
            'input': {'amount': 100, 'description': 'Car accident'},
            'expected': 'ALLOW'
        }
    ]

    for case in test_cases:
        result = simulate_policy(case)
        assert result == case['expected'], f"Failed: {case['name']}"

---

Cedar Quick Reference

Principal Types

principal                           // Any principal
principal is AgentCore::OAuthUser   // OAuth authenticated user
principal is AgentCore::ApiKeyUser  // API key authenticated

Actions

action == AgentCore::Action::"ToolName__method"
action in [Action1, Action2, Action3]

Conditions

// Tag checks
principal.hasTag("role")
principal.getTag("role") == "admin"
principal.getTag("scope") like "*read*"

// Context/input checks
context.input has fieldName
context.input.amount < 1000
context.input.type == "premium"

// Logical operators
&&  // AND
||  // OR
!   // NOT

Policy Types

permit(...)         // Allow if conditions match
permit(...) when {} // Allow with conditions
forbid(...)         // Deny unconditionally
forbid(...) unless {} // Deny unless conditions match

---

Best Practices

1. Start Permissive, Tighten Gradually

// Phase 1: Allow all, log actions
permit(principal, action, resource);

// Phase 2: After analysis, add restrictions
permit(principal, action, resource)
when { /* specific conditions */ };

2. Use Descriptive Policy Names

control.create_policy(
    name='refund-limit-1000-non-managers',  # Good
    # name='policy-1',  # Bad
    ...
)

3. Document Business Rules

// Business Rule: PCI-DSS compliance requires
// credit card operations to be role-restricted
permit(
    principal,
    action == AgentCore::Action::"PaymentAPI__process_card",
    resource
)
when {
    principal.hasTag("role") &&
    principal.getTag("role") in ["payment-admin", "finance"]
};

4. Layer Policies

Policy Stack:
1. Global deny (default)
2. Read-only permits (broad)
3. Write permits (role-specific)
4. Admin permits (highly restricted)
5. Emergency forbids (immediate disable)

---

MCP Server Integration

AgentCore Policy is available as an MCP server for AI-assisted coding environments:

{
  "mcpServers": {
    "bedrock-agentcore-policy": {
      "command": "uvx",
      "args": ["bedrock-agentcore-policy-mcp"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

---

Related Skills

• bedrock-agentcore: Core platform and Gateway setup
• bedrock-agentcore-evaluations: Test policy effectiveness
• bedrock-agentcore-deployment: Deploy policies with agents
• eks-irsa: IAM integration for EKS-hosted agents

---

References

• references/cedar-syntax.md - Complete Cedar language guide
• references/policy-patterns.md - Common patterns library
• references/troubleshooting.md - Policy debugging guide

---

Sources

• Amazon Bedrock AgentCore Policy
• Example Policies
• Common Policy Patterns
• Cedar Language