> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.quarry-systems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Governance

> Managing AI agent access and permissions with Bedrock

## 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

<CardGroup cols={2}>
  <Card title="Principle of Least Privilege" icon="shield-check">
    Agents should only access what they need for their specific task
  </Card>

  <Card title="Context-Aware Access" icon="sitemap">
    Different scopes may require different agent capabilities
  </Card>

  <Card title="Auditability" icon="clipboard-list">
    Track what agents access and do across your organization
  </Card>

  <Card title="Revocability" icon="ban">
    Quickly revoke agent access when needed
  </Card>
</CardGroup>

## 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

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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"]}
    ]
  }'
```

<Info>
  **Inline Memberships**: The `memberships` array creates the membership and role assignments automatically when the subject is created.
</Info>

## Advanced Patterns

### Pattern 1: Scope-Specific Agent Permissions

Different teams may want different agent capabilities:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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)](https://modelcontextprotocol.io/) servers, Bedrock can govern which tools and resources agents can access:

```bash theme={null}
# 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:

```typescript theme={null}
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](/delegation/on-behalf-of#prerequisite-a-delegation-grant) must exist **and** both must have the permission (the allow is the intersection):

```typescript theme={null}
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

```typescript theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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"
  }'
```

<Note>
  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.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Start with minimal permissions">
    Give agents the least privilege needed. It's easier to grant more access than to revoke it after a problem.
  </Accordion>

  <Accordion title="Use descriptive metadata">
    Include model version, capabilities, and purpose in agent metadata for easier auditing.
  </Accordion>

  <Accordion title="Separate agents by function">
    Create different agent subjects for different purposes rather than one super-agent.
  </Accordion>

  <Accordion title="Restrict production access">
    Use scope overrides to limit agent capabilities in production environments.
  </Accordion>

  <Accordion title="Audit agent actions">
    Log all permission checks and actions for compliance and debugging.
  </Accordion>

  <Accordion title="Version your agents">
    Use external IDs like `coding-assistant-v1` to track agent versions.
  </Accordion>
</AccordionGroup>

## 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           |

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-tenant Authorization" icon="building" href="/guides/multi-tenant">
    Isolate agent access across tenants
  </Card>

  <Card title="Scope Overrides" icon="sliders" href="/guides/scope-overrides">
    Fine-tune agent permissions at specific scopes
  </Card>
</CardGroup>