# AI policy drafting

Describe a rule, review catalog matches and tests, and install the result yourself.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/policies/ai-drafting

## Create a draft

Open the policy editor's AI drafting flow and describe the action, surface, environment, and desired outcome. The job runs asynchronously. Keep the job visible while it reports progress, completion, or failure; do not treat an accepted job as an installed policy.

The current drafter can use the workspace's MCP catalog and installed surfaces. It presents test results and matching-tool notes based on the available examples and tool names.

## Review the result

Check the rule's effect, conditions, trigger, environment, and identity assumptions. Confirm a known matching action and a close non-match. Test actual workflow cases beyond the generated examples. Install only after a human reviews the resulting policy.

## API job contract

The customer API provides administrator-gated job routes:

| Operation | Start route | Poll route |
| --- | --- | --- |
| Draft rule | `POST /api/v1/policies/draft-rule/jobs` | `GET /api/v1/policies/draft-rule/jobs/{id}` |
| Summarize change | `POST /api/v1/policies/draft-change-summary/jobs` | `GET /api/v1/policies/draft-change-summary/jobs/{id}` |
| Narrow a flagged rule | `POST /api/v1/decisions/{decisionID}/suggest-policy-fix/jobs` | `GET /api/v1/decisions/{decisionID}/suggest-policy-fix/jobs/{id}` |

Use a user session and the required AI-rule entitlement. The draft-rule body contains a non-empty `description`. Read the job status and its nested result; preserve unknown result fields in clients.

## Deprecations and limits

Older synchronous drafting routes remain mounted for compatibility but are deprecated and bounded by a request timeout. New integrations should use jobs. Drafting requires the server's model service to be configured. A failed job should remain a visible failure, not a success with an empty draft.

## Review scope and drafting failures

Current hosted drafting can propose shared coding-agent rules from supported history, and can draft native PII/secret content controls. Historical source is evidence origin, not proof that the resulting policy should apply only to that agent. Review the proposed target surfaces and real tool schemas. Native Cursor file-edit events remain audit-only.

If drafting fails, retain the request and inspect the visible error before retrying. A generated explanation or passing generated examples does not prove detector accuracy: independently test the sensitive case, a benign near-match and the actual target integration.