Agent Governance

Overview

As AI agents become integral to workflows—coding assistants, autonomous workflows, MCP servers, and more—organizations need robust governance. Bedrock treats agents as first-class subjects, enabling you to apply the same authorization model to agents that you use for humans.

Why Agent Governance Matters

Principle of Least Privilege

Agents should only access what they need for their specific task

Context-Aware Access

Different scopes may require different agent capabilities

Auditability

Track what agents access and do across your organization

Revocability

Quickly revoke agent access when needed

Agent Subject Types

Bedrock supports multiple subject types for different use cases:

Type	Use Case	Example
`agent`	AI assistants and autonomous agents	Claude, GPT-4, custom LLM agents
`service`	Backend services and microservices	Payment processor, notification service
`api_key`	API integrations	Third-party integrations, webhooks

Example: Coding Assistant Agent

Let’s set up a coding assistant with appropriate permissions for a development team.

1. Register the Agent

curl -X POST 'https://api.example.com/subjects' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "subjectType": "agent",
    "externalId": "coding-assistant-v1",
    "displayName": "Coding Assistant",
    "meta": {
      "model": "claude-3-sonnet",
      "version": "1.0.0",
      "capabilities": ["code-review", "code-generation", "documentation"]
    }
  }'

2. Create Agent-Specific Roles

Define roles tailored for agent capabilities:

# Create all agent roles at once
curl -X POST 'https://api.example.com/roles/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "role_code_reader", "name": "Code Reader", "description": "Can read code and documentation", "scopeId": "scope_engineering"},
    {"id": "role_code_writer", "name": "Code Writer", "description": "Can read and modify code", "scopeId": "scope_engineering"},
    {"id": "role_autonomous", "name": "Autonomous Agent", "description": "Full autonomous access", "scopeId": "scope_engineering"}
  ]'

3. Define Agent Permissions

Create granular permissions for agent actions:

# Create all permissions at once
curl -X POST 'https://api.example.com/permissions/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "perm_read_code", "scopeId": "scope_engineering", "action": "read", "resourceType": "code", "resourcePattern": "*", "key": "code:read:*"},
    {"id": "perm_write_code", "scopeId": "scope_engineering", "action": "write", "resourceType": "code", "resourcePattern": "*", "key": "code:write:*"},
    {"id": "perm_execute_code", "scopeId": "scope_engineering", "action": "execute", "resourceType": "code", "resourcePattern": "*", "key": "code:execute:*"},
    {"id": "perm_read_infra", "scopeId": "scope_engineering", "action": "read", "resourceType": "infrastructure", "resourcePattern": "*", "key": "infrastructure:read:*"},
    {"id": "perm_modify_infra", "scopeId": "scope_engineering", "action": "modify", "resourceType": "infrastructure", "resourcePattern": "*", "key": "infrastructure:modify:*"},
    {"id": "perm_read_data", "scopeId": "scope_engineering", "action": "read", "resourceType": "data", "resourcePattern": "*", "key": "data:read:*"},
    {"id": "perm_write_data", "scopeId": "scope_engineering", "action": "write", "resourceType": "data", "resourcePattern": "*", "key": "data:write:*"}
  ]'

# Assign permissions to roles
curl -X POST 'https://api.example.com/role-permissions/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"roleId": "role_code_reader", "permissionId": "perm_read_code"},
    {"roleId": "role_code_writer", "permissionId": "perm_read_code"},
    {"roleId": "role_code_writer", "permissionId": "perm_write_code"}
  ]'

4. Add Agent to Scope with Restricted Role

You can create the agent with inline membership and role assignment:

# Create agent with membership and role in one request
curl -X POST 'https://api.example.com/subjects' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "sub_coding_assistant",
    "subjectType": "agent",
    "externalId": "coding-assistant-v1",
    "displayName": "Coding Assistant",
    "meta": {"model": "claude-3-sonnet", "version": "1.0.0"},
    "memberships": [
      {"scopeId": "scope_engineering", "roleIds": ["role_code_reader"]}
    ]
  }'

Inline Memberships: The memberships array creates the membership and role assignments automatically when the subject is created.

Advanced Patterns

Pattern 1: Scope-Specific Agent Permissions

Different teams may want different agent capabilities:

# Platform team allows code writing
curl -X POST 'https://api.example.com/memberships' \
  -d '{"subjectId": "sub_coding_assistant", "scopeId": "scope_platform"}'

curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_code_writer", "membershipId": "mem_agent_platform"}'

# Security team restricts to read-only
curl -X POST 'https://api.example.com/memberships' \
  -d '{"subjectId": "sub_coding_assistant", "scopeId": "scope_security"}'

curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_code_reader", "membershipId": "mem_agent_security"}'

Pattern 2: Override Agent Permissions at Child Scopes

Restrict agent capabilities in sensitive areas:

# Disable code execution for agents in production scope
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_production",
    "permissionId": "perm_execute_code",
    "state": "inactive"
  }'

# Disable data write for agents in customer data scope
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_customer_data",
    "permissionId": "perm_write_data",
    "state": "inactive"
  }'

Pattern 3: Role-Permission Overrides for Agents

Fine-tune what specific roles can do at specific scopes:

# Code Writer role cannot write code in the compliance scope
curl -X POST 'https://api.example.com/scope-overrides/role-permissions' \
  -d '{
    "childScopeId": "scope_compliance",
    "roleId": "role_code_writer",
    "permissionId": "perm_write_code",
    "state": "revoke"
  }'

Pattern 4: Multiple Agents with Different Access

# Create multiple agents with their roles in one batch
curl -X POST 'https://api.example.com/subjects/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "subjectType": "agent",
      "externalId": "coding-assistant",
      "displayName": "Coding Assistant",
      "memberships": [{"scopeId": "scope_engineering", "roleIds": ["role_code_writer"]}]
    },
    {
      "subjectType": "agent",
      "externalId": "docs-assistant",
      "displayName": "Documentation Agent",
      "memberships": [{"scopeId": "scope_engineering", "roleIds": ["role_code_reader"]}]
    },
    {
      "subjectType": "agent",
      "externalId": "security-scanner",
      "displayName": "Security Scanner",
      "memberships": [{"scopeId": "scope_engineering", "roleIds": ["role_code_reader"]}]
    }
  ]'

MCP Server Integration

When using Model Context Protocol (MCP) servers, Bedrock can govern which tools and resources agents can access:

# Create MCP-specific permissions in batch
curl -X POST 'https://api.example.com/permissions/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "perm_mcp_fs_read", "scopeId": "scope_engineering", "action": "read", "resourceType": "mcp:filesystem", "resourcePattern": "*", "key": "mcp:filesystem:read:*"},
    {"id": "perm_mcp_fs_write", "scopeId": "scope_engineering", "action": "write", "resourceType": "mcp:filesystem", "resourcePattern": "*", "key": "mcp:filesystem:write:*"},
    {"id": "perm_mcp_db_query", "scopeId": "scope_engineering", "action": "query", "resourceType": "mcp:database", "resourcePattern": "*", "key": "mcp:database:query:*"},
    {"id": "perm_mcp_gh_read", "scopeId": "scope_engineering", "action": "read", "resourceType": "mcp:github", "resourcePattern": "*", "key": "mcp:github:read:*"},
    {"id": "perm_mcp_gh_write", "scopeId": "scope_engineering", "action": "write", "resourceType": "mcp:github", "resourcePattern": "*", "key": "mcp:github:write:*"}
  ]'

Your MCP server can then check Bedrock permissions before executing tools.

Checking Agent Permissions

Use the BedrockEngine to evaluate permissions at runtime:

import { BedrockEngine } from '@quarry-systems/bedrock-core';

const engine = new BedrockEngine(store);

// Check if an agent can perform an action
const decision = await engine.evaluate({
  actor: { subjectId: 'agent_coding_assistant', subjectType: 'agent' },
  scopeId: 'scope_engineering',
  action: 'write',
  resource: { resourceType: 'code', resourcePattern: '*' },
});

if (decision.allowed) {
  // Agent has permission
  console.log(decision.explanation);
  // "Permission write:code granted via roles: role_code_writer"
} else {
  // Agent denied
  console.log(decision.explanation);
  // "No permission for write:code for subject agent_coding_assistant in scope scope_engineering"
}

Delegated Permissions (Agent Acting on Behalf of User)

When an agent acts on behalf of a user, an active delegation grant must exist and both must have the permission (the allow is the intersection):

const decision = await engine.evaluate({
  actor: { subjectId: 'agent_coding_assistant', subjectType: 'agent' },
  onBehalfOf: { subjectId: 'user_jane', subjectType: 'user' },
  scopeId: 'scope_engineering',
  action: 'write',
  resource: { resourceType: 'code' },
});

// Both actor (agent) AND principal (user) must be allowed
console.log(decision.usedDelegation); // true
console.log(decision.allowed); // true only if both have permission

List All Effective Permissions

const permissions = await engine.listEffectivePermissions(
  'agent_coding_assistant',
  'scope_engineering'
);

// Returns array of EffectivePermissionSummary
// [{ resourceType: 'code', action: 'read', permissions: [...], sourceRoles: [...] }]

Agents as Resources: Identity & Ownership

Beyond RBAC and delegation, Bedrock models two first-class agent-governance edges. An agent is a subject; the thing it represents (its runtime, workspace, artifact) is a resource. Subject–Resource Identity — a 1:1 link between a subject and the resource that represents it (create-only). It is for integrity and introspection and is not read on the evaluation path.

curl -X POST 'https://api.example.com/subject-resource-identities' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -d '{"subjectId": "sub_coding_assistant", "resourceId": "resource_agent_runtime"}'

Resource Ownership — owns(subject, resource, role). An active ownership row grants the owner-role’s matching permissions on that specific resource, evaluated as its own engine leg (routed through overrides, conditions fail-closed, temporal window via the trusted clock). Use it to give an agent authority over the resources it owns without a broad scope role.

curl -X POST 'https://api.example.com/resource-ownerships' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -d '{
    "subjectId": "sub_coding_assistant",
    "resourceId": "resource_agent_runtime",
    "roleId": "role_owner",
    "validFrom": "2026-01-01T00:00:00Z",
    "validUntil": "2026-12-31T23:59:59Z"
  }'

A resource-policy deny still overrides an ownership grant (policies evaluate before the ownership leg). Ownership adds authority; it does not bypass an explicit deny.

Best Practices

Start with minimal permissions

Give agents the least privilege needed. It’s easier to grant more access than to revoke it after a problem.

Use descriptive metadata

Include model version, capabilities, and purpose in agent metadata for easier auditing.

Separate agents by function

Create different agent subjects for different purposes rather than one super-agent.

Restrict production access

Use scope overrides to limit agent capabilities in production environments.

Audit agent actions

Log all permission checks and actions for compliance and debugging.

Version your agents

Use external IDs like coding-assistant-v1 to track agent versions.

Comparison: User vs Agent Governance

Aspect	Users	Agents
Subject type	`user`	`agent`, `service`, `api_key`
Authentication	OAuth, SSO, passwords	API keys, tokens
Typical roles	Admin, Editor, Viewer	Reader, Writer, Autonomous
Permission scope	Often broad	Usually narrow and specific
Override usage	Occasional	Frequent (restrict in sensitive areas)
Metadata	Name, email	Model, version, capabilities

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

Agent Governance

Overview

Why Agent Governance Matters

Principle of Least Privilege

Context-Aware Access

Auditability

Revocability

Agent Subject Types

Example: Coding Assistant Agent

1. Register the Agent

2. Create Agent-Specific Roles

3. Define Agent Permissions

4. Add Agent to Scope with Restricted Role

Advanced Patterns

Pattern 1: Scope-Specific Agent Permissions

Pattern 2: Override Agent Permissions at Child Scopes

Pattern 3: Role-Permission Overrides for Agents

Pattern 4: Multiple Agents with Different Access

MCP Server Integration

Checking Agent Permissions

Delegated Permissions (Agent Acting on Behalf of User)

List All Effective Permissions

Agents as Resources: Identity & Ownership

Best Practices

Comparison: User vs Agent Governance

Next Steps

Multi-tenant Authorization

Scope Overrides

​Overview

​Why Agent Governance Matters

Principle of Least Privilege

Context-Aware Access

Auditability

Revocability

​Agent Subject Types

​Example: Coding Assistant Agent

​1. Register the Agent

​2. Create Agent-Specific Roles

​3. Define Agent Permissions

​4. Add Agent to Scope with Restricted Role

​Advanced Patterns

​Pattern 1: Scope-Specific Agent Permissions

​Pattern 2: Override Agent Permissions at Child Scopes

​Pattern 3: Role-Permission Overrides for Agents

​Pattern 4: Multiple Agents with Different Access

​MCP Server Integration

​Checking Agent Permissions

​Delegated Permissions (Agent Acting on Behalf of User)

​List All Effective Permissions

​Agents as Resources: Identity & Ownership

​Best Practices

​Comparison: User vs Agent Governance

​Next Steps

Multi-tenant Authorization

Scope Overrides

Overview

Why Agent Governance Matters

Agent Subject Types

Example: Coding Assistant Agent

1. Register the Agent

2. Create Agent-Specific Roles

3. Define Agent Permissions

4. Add Agent to Scope with Restricted Role

Advanced Patterns

Pattern 1: Scope-Specific Agent Permissions

Pattern 2: Override Agent Permissions at Child Scopes

Pattern 3: Role-Permission Overrides for Agents

Pattern 4: Multiple Agents with Different Access

MCP Server Integration

Checking Agent Permissions

Delegated Permissions (Agent Acting on Behalf of User)

List All Effective Permissions

Agents as Resources: Identity & Ownership

Best Practices

Comparison: User vs Agent Governance

Next Steps