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

# Custom Policy Agents

> Create AI-powered agents that review applications against your organization's specific policies and standards

<Note>
  Custom Policy Agents are currently in **beta**. [Contact support](mailto:support@superblocks.com) to get on the waitlist.
</Note>

**Custom Policy Agents** are AI-powered reviewers that admins configure to enforce organization-specific policies. Each agent has its own instructions, a dedicated context window, and access to your organization's [Knowledge](/building-with-clark/knowledge/index). They evaluate applications against standards that deterministic scanning cannot capture — data handling policies, architecture requirements, compliance rules, and more.

Custom Policy Agents are part of the [Policy Agents](/admin/policy-agents/index) framework and appear alongside built-in security scans in the publish readiness checklist.

## How it works

A Custom Policy Agent is an AI reviewer that runs against your application at publish time:

1. **Admin creates the agent** with a name, instructions, mode, and scope
2. **Builder publishes** — the agent evaluates a frozen snapshot of the application
3. **Agent produces findings** — structured results with evidence, locations, and severity
4. **Builder sees results** in the publish readiness checklist with clear next actions

Multiple agents run in parallel. Each appears as a separate item in publish readiness, so builders know exactly which policy passed and which needs attention.

## Creating an agent

Admins configure each Custom Policy Agent with:

| Setting          | Description                                                                        |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Name**         | Display name shown in publish readiness (e.g., "PHI Storage Agent")                |
| **Instructions** | The policy the agent enforces — written in natural language, as detailed as needed |
| **Mode**         | **Blocking** (prevents publish until resolved) or **Advisory** (warns but allows)  |
| **Scope**        | Which applications the agent applies to — all apps, or a specific subset           |

### Writing effective instructions

Agent instructions work best when they are specific, concrete, and reference your organization's actual standards. You can reference your organization's [Knowledge](/building-with-clark/knowledge/index) to give agents access to existing policies and documentation.

Examples of effective instructions:

* "Check that any application storing or transmitting patient health information (PHI) only writes to integrations on the approved PHI storage list. Flag any write operation to an unapproved destination as a blocking finding."
* "Verify that all API endpoints that perform write operations include role-based access control checks. Any endpoint that modifies data without verifying the caller's permissions should be flagged."
* "Confirm that no application stores secrets or credentials in environment variables, local storage, or hardcoded values. All secrets must be referenced through Superblocks integrations."

## What the agent can access

Custom Policy Agents have read-only access to the application being reviewed:

* Application source files and component structure
* Application metadata and configuration
* Integration references and connection details
* Findings from the built-in security scan (so agents can build on deterministic results)

Agents cannot modify the application. They evaluate and report — Clark handles remediation.

## Relationship to Clark

Custom Policy Agents and Clark serve distinct roles:

|            | Custom Policy Agent              | Clark                                     |
| ---------- | -------------------------------- | ----------------------------------------- |
| **Role**   | Reviewer — evaluates and reports | Fixer — remediates findings               |
| **When**   | Runs at publish time             | Runs when builder clicks "Fix with Clark" |
| **Access** | Read-only app state              | Read-write app state                      |
| **Output** | Structured findings              | Code changes                              |

When a Custom Policy Agent blocks publish, the builder can ask Clark to fix eligible findings. Clark modifies the app, and then a fresh agent run verifies the fix resolved the issue. The agent never resolves its own findings — independent verification is always required.

## Example use cases

### PHI storage compliance

> "Flag any application that writes patient identifiers, diagnoses, or treatment records to an integration not on the approved PHI storage list. Reference the 'Approved PHI Destinations' knowledge document."

### Internal authentication standards

> "Verify that every API endpoint performing data mutations checks the caller's role against the required permission level. Flag endpoints that skip authorization checks."

### Data handling policies

> "Check that applications do not export, log, or display raw payment card numbers. Ensure any refund or chargeback workflow includes approval steps and audit logging."

### Architecture standards

> "Confirm that no application makes direct database queries from frontend components. All data access must go through backend APIs."

## What builders see

When a Custom Policy Agent completes, builders see it in their publish readiness checklist:

```text theme={null}
PHI Storage Agent    Blocked — 2 findings
```

Clicking into the report shows each finding with:

* **What the agent found** — a clear explanation of the policy violation
* **Evidence** — the specific code, configuration, or pattern that triggered the finding
* **Location** — where in the application the issue exists
* **Fix with Clark** — one-click remediation for eligible findings

If Clark cannot fix a finding, the builder can escalate to an admin. Authorized admins can override a blocking agent when appropriate.