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

# Policies

> Define structured rulesets and guidelines for your agents

Policies allow you to create versioned, structured rulesets that agents use for document processing, compliance checking, and classification tasks. Instead of embedding rules directly in agent prompts, policies provide a centralized way to manage guidelines, instructions, and classification dispositions.

## Use Cases

* **Compliance checking**: Define rules and red/green flags for reviewing documents against regulatory requirements
* **Document classification**: Create disposition categories for agents to classify documents into
* **Structured extraction**: Provide hierarchical guidelines that agents follow when extracting information
* **Audit workflows**: Maintain versioned policies for traceability and rollback capabilities

## How Policies Work

1. **Create a policy** at the organization level with a name and description
2. **Add versions** to the policy, each containing structured content (guidelines, instructions, dispositions)
3. **Link the policy** to one or more agents via the agent's engine configuration
4. **Run agent jobs** - agents apply the policy's current version when processing documents
5. **Update policies** by creating new versions without breaking existing agent configurations

## Policy Versioning

Policies use a versioning model similar to agents:

* Each policy has multiple **versions** containing the actual content
* One version is marked as the **current version**
* Agents reference a specific policy version via `policy_version_id`
* Creating a new version automatically sets it as current
* You can switch back to previous versions at any time

```mermaid theme={null}
graph LR
    P[Policy] --> V1[Version 1]
    P --> V2[Version 2]
    P --> V3[Version 3]
    P -.->|current| V3
    A[Agent] -->|policy_version_id| V3
```

## Policy Content Structure

Each policy version contains structured JSON content with four optional sections:

### Guidelines

A hierarchical structure for organizing rules:

```json theme={null}
{
  "guidelines": {
    "categories": [
      {
        "title": "Document Verification",
        "description": "Rules for verifying document authenticity",
        "rules": [
          {
            "title": "Check signatures",
            "description": "Verify all required signatures are present",
            "flag": "RED_FLAG",
            "sub_rules": [
              {
                "title": "Authorized signatories",
                "description": "Signatures must match authorized personnel list"
              }
            ]
          }
        ]
      }
    ]
  }
}
```

| Field        | Description                                   |
| ------------ | --------------------------------------------- |
| `categories` | Top-level groupings of related rules          |
| `rules`      | Individual rules within a category            |
| `sub_rules`  | Nested rules for additional detail            |
| `flag`       | Optional `GREEN_FLAG` or `RED_FLAG` indicator |

### Instructions

Free-form text instructions for the agent:

```json theme={null}
{
  "instructions": "Review all documents for compliance with company policy. Flag any discrepancies and provide detailed reasoning for each decision."
}
```

### Dispositions

Classification options for agent outputs:

```json theme={null}
{
  "dispositions": {
    "classifications": [
      {
        "name": "Approved",
        "description": "Document meets all requirements",
        "prompt": "Select this when all compliance checks pass"
      },
      {
        "name": "Rejected",
        "description": "Document fails one or more requirements",
        "prompt": "Select this when any critical rule is violated"
      },
      {
        "name": "Needs Review",
        "description": "Document requires manual review",
        "prompt": "Select this for edge cases or unclear situations"
      }
    ]
  }
}
```

### Summary Template

A Handlebars-style template for generating structured summaries:

```json theme={null}
{
  "summary_template": {
    "template": "## Review Summary\n\n**Decision**: {{disposition}}\n\n**Findings**:\n{{#each findings}}\n- {{this}}\n{{/each}}"
  }
}
```

## Linking Policies to Agents

Policies are linked to agents through the agent's engine configuration. When creating or updating an agent version, specify the `policy_version_id` to use:

```json theme={null}
{
  "engine_config": {
    "policy_version_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

<Note>
  Policies cannot be deleted while they are in use by any agent. You must first unlink all agents before deleting a policy.
</Note>

## API Reference

<CardGroup cols={2}>
  <Card title="List Policies" icon="list" href="/api-reference/policies/list-policies">
    Get all policies in your organization
  </Card>

  <Card title="Create Policy" icon="plus" href="/api-reference/policies/create-policy">
    Create a new policy with initial version
  </Card>

  <Card title="Create Version" icon="code-branch" href="/api-reference/policies/create-policy-version">
    Add a new version to an existing policy
  </Card>

  <Card title="Set Current Version" icon="arrow-pointer" href="/api-reference/policies/set-current-version">
    Change which version is active
  </Card>
</CardGroup>