# AI Agent Rail Card Template: YAML, Spreadsheet and JSON Schema

This AI agent permissions template is a free download for writing one rail card: a one-page spec with ten fields that fix what one agent may do on one job. It comes as commented YAML, a spreadsheet and a JSON Schema, and it works with any customer data platform (CDP). It is a vendor-neutral method, not a product API, and PrivyCDP does not ship these agents.

**Who this is for:** security engineers, marketing-operations leads and data protection officers defining access before an agent gets it. The template belongs to the [AI agent rails](https://privycdp.org/ai/rails) method. [The agent rail card explainer](https://privycdp.org/ai/rails/agent-rail-card) gives the reasoning behind each field. More assets: [tools hub](https://privycdp.org/tools).

## What is in the rail card download?

The rail card download holds three template files, plus reference material to adapt.

| File | What it is | Use it to |
|---|---|---|
| [agent-rail-card-template.yaml](https://privycdp.org/tools/agent-rail-card-template.yaml) | A blank card with comments on every field | Keep cards versioned with your configuration |
| [agent-rail-card-template.csv](https://privycdp.org/tools/agent-rail-card-template.csv) | One row per field, with weak and strong answers | Fill in a card in a workshop, with no tooling |
| [agent-rail-card.schema.json](https://privycdp.org/tools/agent-rail-card.schema.json) | A JSON Schema (draft 2020-12) for a filled card [1](#source-1) | Check a card automatically before it is merged |
| [33 filled cards](#the-full-set-of-33-rail-cards) | One YAML file per agent | Start from the closest job |
| [agent-roster.json](https://privycdp.org/tools/agent-roster.json) | All 33 agents as one JSON dataset | Load the set into your own tooling |

Every YAML card uses the same keys: identifying keys such as `rail` and `level`, the ten fields, then `never`, `where_it_runs` and an optional `profile` link.

## The ten fields of a rail card

A rail card has ten fields, always in this order, and each one names the system that enforces it, because a prompt is not a control. The strong answers come from the [Segment Drafter](https://privycdp.org/ai/rails/agents/segment-drafter) card and are illustrative.

| Field | Question it answers | Weak answer | Strong answer | Enforced by |
|---|---|---|---|---|
| Job | What one outcome does this rail exist to produce? | Help with segments. | Draft a segment definition from a plain-English request and return it with counts and reason codes. | Rail catalogue and routing table: a request with no matching rail has no route |
| Trigger | What starts a run, and what must never start one? | When needed. | A marketing-operations request routed by the [Orchestrator](https://privycdp.org/ai/rails/orchestrator-agent); never on a schedule. | Routing table or scheduler |
| Data scope | Which objects and fields may it read, how masked, and what is excluded? | CRM data. | Segmentation schema, consent-filtered counts and pseudonymised IDs; no direct identifiers, free-text fields or special-category data. | Data view or field projection |
| Tool scope | Which allow-listed tools may it call for each verb: read, propose, execute? | Access to the platform API. | Read: schema; existing segments; count estimates. Propose: versioned segment draft. Execute: none. | Tool allow-list at the gateway; a per-agent identity with scoped credentials |
| Output contract | What must come back, and in what shape? | A good segment. | Draft definition, estimated count, overlap with live segments, reason codes, open questions. | Schema validation before the output reaches a person |
| Gate | Who approves what evidence, and what happens on a timeout? | A manager checks it. | Marketing-operations reviewer, never the requester; approval binds to the definition hash; a timeout expires the draft and never approves it. | Approval service |
| Limits | What is the most one run can do, how often, at what cost and where? | Reasonable use. | Runs per day, budget per run, and an audience size above which a second approver is needed, each with a written value. | Gateway or execution service |
| Ledger | What does every run record, and who writes it? | Logging is on. | Correlation ID, request hash, tools called, draft version and hash, counts, approver, outcome, model version; written outside the agent. | Ledger writer outside the agent |
| Evaluation | How do you know it is good, and still good? | It looked right in the demo. | Past requests with accepted definitions, plus seeded sensitive-attribute traps; rerun before any model, prompt or tool change; measured by override rate and sensitive-attribute failures caught. | Test harness and a regression gate in change control |
| Owner and kill switch | Who answers for this rail, how is it stopped, and what pauses it automatically? | The AI team can turn it off. | Head of marketing operations; Orchestrator pause; automatic pause after repeated rejections on one request. | Orchestrator or gateway; a person holds the switch |

A field that no system enforces is documentation, so record it as a known gap.

## Which worked examples should you copy from?

Three worked examples show how the same fields change as risk rises. Limits are in words, because each team sets its own numbers.

| Example | Level | What to copy |
|---|---|---|
| [Segment Drafter card](https://privycdp.org/tools/rail-cards/segment-drafter.yaml) | L2 | `execute` is "None.", so drafting and activating stay on separate rails. |
| [Consent Conflict Reviewer](https://privycdp.org/ai/rails/agents/consent-conflict-reviewer) [card](https://privycdp.org/tools/rail-cards/consent-conflict-reviewer.yaml) | L2, L4 for hold only | The one automatic action only adds caution, a person clears it, and no consent or suppression write tools exist. |
| [Sync Medic](https://privycdp.org/ai/rails/agents/sync-medic) [card](https://privycdp.org/tools/rail-cards/sync-medic.yaml) | L3 to L4 | A retry needs no new approval only if the version, audience hash and destination are unchanged and consent is re-checked. Anything else goes to a person. |

## How do you fill in a rail card in a workshop?

A rail card is best filled in during a short workshop with the rail's owner, a security engineer and the reviewer. We suggest about an hour.

1. **Pick one real, low-risk job.** If the job needs "and then", write two cards.
2. **The owner writes Job and Trigger.** Use one sentence each, and say what must never start a run.
3. **The security engineer writes Data scope.** Start from nothing, add only what the job needs and state what is excluded.
4. **The security engineer writes Tool scope, then runs the Rule of Two check.** Name which properties the session holds: untrusted input, sensitive data, the ability to change state or communicate externally [2](#source-2). A session that reads untrusted text and holds sensitive data gets no state-changing tools.
5. **The reviewer writes Output contract and Gate.** What must they see before saying yes? The approver is never the requester, and timeouts expire.
6. **The group writes Limits and Ledger.** Describe limits in words, then agree who sets the numbers.
7. **The reviewer and owner write Evaluation.** List past cases and seeded errors, and pick an honest measure such as override rate.
8. **The owner writes Owner and kill switch.** Say what happens to work when the rail stops, and book a drill.
9. **Set the level and mark the gaps.** Start at the lowest useful [rail level](https://privycdp.org/ai/rails/rail-levels-autonomy-ladder). Name the enforcing system for each field, then validate the YAML.

Not sure which job to start with? The [readiness assessment](https://privycdp.org/tools/agent-rails-readiness-assessment) suggests one per function.

## What does the JSON Schema check?

The rail card JSON Schema checks that a card is complete and well formed, not that its answers are true or enforced. Any draft 2020-12 validator can run it [1](#source-1). All 33 filled cards pass, and the blank template fails until filled in.

- Every key except `profile` must exist and must not be blank.
- `tool_scope` must hold `read`, `propose` and `execute`, and nothing else.
- `risk` must be low, medium or high.
- `level` must be L0 to L4, with an optional range or named exception. The ladder stops at L4.
- Unknown keys fail. Prefix your own, such as numeric limits, with `x_`.

## The full set of 33 rail cards

The full set covers 33 reference jobs, each as a YAML file to copy. They are examples, not product features. The [permission matrix](https://privycdp.org/tools/agent-permission-matrix) shows them side by side.

| Function | Agents and cards |
|---|---|
| Marketing operations | [Journey QA Reviewer](https://privycdp.org/ai/rails/agents/journey-qa-reviewer) ([card](https://privycdp.org/tools/rail-cards/journey-qa-reviewer.yaml)); [Anomaly Watcher](https://privycdp.org/ai/rails/agents/anomaly-watcher) ([card](https://privycdp.org/tools/rail-cards/anomaly-watcher.yaml)); [Reporting Summariser](https://privycdp.org/ai/rails/agents/reporting-summariser) ([card](https://privycdp.org/tools/rail-cards/reporting-summariser.yaml)); [Audience Sync Steward](https://privycdp.org/ai/rails/agents/audience-sync-steward) ([card](https://privycdp.org/tools/rail-cards/audience-sync-steward.yaml)) |
| Lifecycle and CRM marketing | [Claims Checker](https://privycdp.org/ai/rails/agents/claims-checker) ([card](https://privycdp.org/tools/rail-cards/claims-checker.yaml)); [Frequency Advisor](https://privycdp.org/ai/rails/agents/frequency-advisor) ([card](https://privycdp.org/tools/rail-cards/frequency-advisor.yaml)); [Deliverability Watcher](https://privycdp.org/ai/rails/agents/deliverability-watcher) ([card](https://privycdp.org/tools/rail-cards/deliverability-watcher.yaml)) |
| Data and analytics | [Data Quality Triager](https://privycdp.org/ai/rails/agents/data-quality-triager) ([card](https://privycdp.org/tools/rail-cards/data-quality-triager.yaml)); [Identity Reviewer](https://privycdp.org/ai/rails/agents/identity-reviewer) ([card](https://privycdp.org/tools/rail-cards/identity-reviewer.yaml)); [Schema Drift Sentinel](https://privycdp.org/ai/rails/agents/schema-drift-sentinel) ([card](https://privycdp.org/tools/rail-cards/schema-drift-sentinel.yaml)); [Metric Explainer](https://privycdp.org/ai/rails/agents/metric-explainer) ([card](https://privycdp.org/tools/rail-cards/metric-explainer.yaml)) |
| Compliance, privacy and security | [DSAR Assembler](https://privycdp.org/ai/rails/agents/dsar-assembler) ([card](https://privycdp.org/tools/rail-cards/dsar-assembler.yaml)); [Evidence Packer](https://privycdp.org/ai/rails/agents/evidence-packer) ([card](https://privycdp.org/tools/rail-cards/evidence-packer.yaml)); [Policy Drift Checker](https://privycdp.org/ai/rails/agents/policy-drift-checker) ([card](https://privycdp.org/tools/rail-cards/policy-drift-checker.yaml)); [Access Review Assistant](https://privycdp.org/ai/rails/agents/access-review-assistant) ([card](https://privycdp.org/tools/rail-cards/access-review-assistant.yaml)) |
| Customer support | [Context Briefer](https://privycdp.org/ai/rails/agents/context-briefer) ([card](https://privycdp.org/tools/rail-cards/context-briefer.yaml)); [Case Classifier](https://privycdp.org/ai/rails/agents/case-classifier) ([card](https://privycdp.org/tools/rail-cards/case-classifier.yaml)); [Escalation Spotter](https://privycdp.org/ai/rails/agents/escalation-spotter) ([card](https://privycdp.org/tools/rail-cards/escalation-spotter.yaml)) |
| Sales and revenue operations | [Account Signal Digest](https://privycdp.org/ai/rails/agents/account-signal-digest) ([card](https://privycdp.org/tools/rail-cards/account-signal-digest.yaml)); [Lead Routing Proposer](https://privycdp.org/ai/rails/agents/lead-routing-proposer) ([card](https://privycdp.org/tools/rail-cards/lead-routing-proposer.yaml)); [CRM Hygiene Fixer](https://privycdp.org/ai/rails/agents/crm-hygiene-fixer) ([card](https://privycdp.org/tools/rail-cards/crm-hygiene-fixer.yaml)) |
| Product and growth | [Experiment Reader](https://privycdp.org/ai/rails/agents/experiment-reader) ([card](https://privycdp.org/tools/rail-cards/experiment-reader.yaml)); [Onboarding Funnel Watcher](https://privycdp.org/ai/rails/agents/onboarding-funnel-watcher) ([card](https://privycdp.org/tools/rail-cards/onboarding-funnel-watcher.yaml)); [Feature Adoption Explainer](https://privycdp.org/ai/rails/agents/feature-adoption-explainer) ([card](https://privycdp.org/tools/rail-cards/feature-adoption-explainer.yaml)) |
| Platform operations | [Cost Watcher](https://privycdp.org/ai/rails/agents/cost-watcher) ([card](https://privycdp.org/tools/rail-cards/cost-watcher.yaml)); [Connector Change Reviewer](https://privycdp.org/ai/rails/agents/connector-change-reviewer) ([card](https://privycdp.org/tools/rail-cards/connector-change-reviewer.yaml)); [Restore Drill Reporter](https://privycdp.org/ai/rails/agents/restore-drill-reporter) ([card](https://privycdp.org/tools/rail-cards/restore-drill-reporter.yaml)) |
| Cross-cutting | [Orchestrator card](https://privycdp.org/tools/rail-cards/orchestrator-agent.yaml); [Trainer](https://privycdp.org/ai/rails/trainer-agent) ([card](https://privycdp.org/tools/rail-cards/trainer-agent.yaml)); [VP Marketing agent](https://privycdp.org/ai/rails/vp-marketing-agent) ([card](https://privycdp.org/tools/rail-cards/vp-marketing-agent.yaml)) |

The three worked examples above complete the set.

By Art Kukharenko
Published: 2026-11-02
Updated: 2026-11-02

## FAQ

### What should an AI agent permissions template include?

An AI agent permissions template should fix ten things for each job: job, trigger, data scope, tool scope, output contract, gate, limits, ledger, evaluation, and owner and kill switch. It should also name the system that enforces each one. A list of allowed tools leaves out who approves, what is logged and who can stop the agent.

### Is the rail card a PrivyCDP feature or a product API?

No. The rail card is a vendor-neutral method, and its keys are not API calls. PrivyCDP offers an MCP-ready interface and an immutable audit ledger that records each AI-assisted action with the human or system actor that authorised it. Your team still writes and enforces each card.

### How is a rail card different from an A2A Agent Card?

An A2A Agent Card is a JSON document that describes an agent's identity, endpoint, capabilities, authentication and skills for discovery, and it is not a permission system [3](#source-3). A rail card restricts what one agent may do on one job, and who approves it.

### Can we use the template with vendor agents we cannot fully configure?

Yes. Fill in the card anyway and record what you cannot enforce as a known gap. If a gap touches consent, suppression or approval, hold the job at a lower level or keep it manual.

### Does one agent need several rail cards?

An agent needs several cards when it does several jobs, because levels belong to a job. A narrow exception can stay on one card, as the Anomaly Watcher's "L1, L4 pause" shows. A different data scope, approver or audit trail needs its own card.

### Who approves changes to a rail card?

A rail card change passes the same gate as the actions it governs. As a pattern, tightening a limit needs the owner, widening data scope needs the data protection officer, adding a tool needs security, and raising a level needs written evidence. Each ledger entry should record the card version.

## Sources

1. JSON Schema, Draft 2020-12: https://json-schema.org/draft/2020-12
2. Meta, Agents Rule of Two (31 October 2025): https://ai.meta.com/blog/practical-ai-agent-security/
3. A2A protocol, agent discovery: https://a2a-protocol.org/latest/topics/agent-discovery/

[Download the rail card template](https://privycdp.org/tools/agent-rail-card-template.yaml) and fill it in for one real job. The [AI agent rails](https://privycdp.org/ai/rails) hub explains the wider method. Next, read how to [connect agents through MCP safely](https://privycdp.org/ai/mcp-salesforce-hubspot-cdp-agents-safely) and the [AI governance policy template](https://privycdp.org/ai/ai-governance-policy-template-marketing).


## Further reading

- [Consent Conflict Reviewer: An AI Agent That Explains Consent Conflicts](https://privycdp.org/ai/rails/agents/consent-conflict-reviewer)
- [Segment Drafter: An AI Agent That Drafts Segments for Human Approval](https://privycdp.org/ai/rails/agents/segment-drafter)
- [Sync Medic: An AI Agent That Retries Failed Syncs Within Limits](https://privycdp.org/ai/rails/agents/sync-medic)
- [AI Agent Rails: An Operating Model for Running Agents on Customer Data](https://privycdp.org/ai/rails)
- [Customer data platform tools and templates](https://privycdp.org/tools)