tools

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.

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

All tools

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 method. The agent rail card explainer gives the reasoning behind each field. More assets: tools hub.

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	A blank card with comments on every field	Keep cards versioned with your configuration
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	A JSON Schema (draft 2020-12) for a filled card 1	Check a card automatically before it is merged
33 filled cards	One YAML file per agent	Start from the closest job
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 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; 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	L2	`execute` is "None.", so drafting and activating stay on separate rails.
Consent Conflict Reviewer card	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 card	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.

Pick one real, low-risk job. If the job needs "and then", write two cards.
The owner writes Job and Trigger. Use one sentence each, and say what must never start a run.
The security engineer writes Data scope. Start from nothing, add only what the job needs and state what is excluded.
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. A session that reads untrusted text and holds sensitive data gets no state-changing tools.
The reviewer writes Output contract and Gate. What must they see before saying yes? The approver is never the requester, and timeouts expire.
The group writes Limits and Ledger. Describe limits in words, then agree who sets the numbers.
The reviewer and owner write Evaluation. List past cases and seeded errors, and pick an honest measure such as override rate.
The owner writes Owner and kill switch. Say what happens to work when the rail stops, and book a drill.
Set the level and mark the gaps. Start at the lowest useful rail level. Name the enforcing system for each field, then validate the YAML.

Not sure which job to start with? The 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. 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 shows them side by side.

Function	Agents and cards
Marketing operations	Journey QA Reviewer (card); Anomaly Watcher (card); Reporting Summariser (card); Audience Sync Steward (card)
Lifecycle and CRM marketing	Claims Checker (card); Frequency Advisor (card); Deliverability Watcher (card)
Data and analytics	Data Quality Triager (card); Identity Reviewer (card); Schema Drift Sentinel (card); Metric Explainer (card)
Compliance, privacy and security	DSAR Assembler (card); Evidence Packer (card); Policy Drift Checker (card); Access Review Assistant (card)
Customer support	Context Briefer (card); Case Classifier (card); Escalation Spotter (card)
Sales and revenue operations	Account Signal Digest (card); Lead Routing Proposer (card); CRM Hygiene Fixer (card)
Product and growth	Experiment Reader (card); Onboarding Funnel Watcher (card); Feature Adoption Explainer (card)
Platform operations	Cost Watcher (card); Connector Change Reviewer (card); Restore Drill Reporter (card)
Cross-cutting	Orchestrator card; Trainer (card); VP Marketing agent (card)

The three worked examples above complete the set.

Browse use cases Function playbooks Agent roster

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

Download the rail card template and fill it in for one real job. The AI agent rails hub explains the wider method. Next, read how to connect agents through MCP safely and the AI governance policy template.