The Agent Rail Card: A One-Page AI Agent Permissions Template

Who this is for: security engineers, marketing-operations leads and DPOs who must put something on paper before an agent gets access. You will get the ten fields, a filled example, a map from each field to the system that enforces it, and a workshop plan. This page is part of the AI agent rails method.

Why do AI agents need a written permissions template?

AI agents need a written permissions template because identity systems can say what an agent can reach, but not what it is for. A shared service account plus a system prompt is a common starting point. That setup gives one credential to every job and leaves the limits in text the model may ignore. Afterwards, nobody can say which job did what. OWASP lists ASI03 Identity & Privilege Abuse among its top risks for agentic applications 113.

No shared standard for this exists yet, and identity for agents is still being worked out. The US National Institute of Standards and Technology published a draft concept paper on 5 February 2026, with comments closing on 2 April 2026. It proposes a project on applying existing identity standards to agents, and it asks about identification, authorisation, auditing and prompt injection 2. Microsoft's Entra Agent ID documentation says traditional identity types "aren't ideal" for agents, and it blocks agent identities from many high-privilege roles 3.

Those efforts cover who the agent is and what it may call. A rail card adds what identity cannot: the one job, the approver, the limits, the evidence and the person who answers for it. It stands beside least-privilege tool access and does not replace it.

The ten fields of a rail card

A rail card is the one-page spec for a job, with ten fields in a fixed order: Job, Trigger, Data scope, Tool scope (read, propose, execute), Output contract, Gate, Limits, Ledger, Evaluation, Owner and kill switch. The table gives the question each field answers, then a weak and a strong answer. The strong answers describe the Segment Drafter.

The weak answers share one fault: no system could check them.

A filled rail card: the Segment Drafter

The card below is a filled rail card for the Segment Drafter at L2. Everything in it is illustrative. The tool names, numbers and key names are invented for teaching. It is not a PrivyCDP API, schema or feature.

# Illustrative example only. Tool names, numbers and keys are invented for teaching.
# Not a product API or schema. Replace every value with your own.
rail: segment-drafter
version: "1.0"
level: L2
job: "Draft a segment definition from a plain-English request and return it with counts and reason codes."
trigger: "A marketing-operations request routed by the Orchestrator; never on a schedule."
data_scope:
  allowed: [segmentation_schema, consent_filtered_counts, pseudonymised_ids]
  excluded: [direct_identifiers, free_text_fields, special_category_data]
  working_copies: "none kept after the run"
tool_scope:
  read: [example_schema_read, example_segments_list, example_count_estimate]
  propose: [example_segment_draft]
  execute: []
output_contract: [draft_definition, estimated_count, overlap_with_live_segments, reason_codes, open_questions]
gate:
  approver: "marketing-operations reviewer, never the requester"
  evidence: [diff_against_live_segments, estimated_count, rule_check_results]
  binds_to: definition_hash
  on_timeout: "draft expires after 48 hours; never auto-approves"
limits:
  runs_per_day: 50
  budget_per_run_eur: 0.20
  second_approver_above_audience: 2000000
ledger:
  writer: "gateway and approval service, never the agent"
  fields: [correlation_id, request_hash, tools_called, draft_version, draft_hash, counts, approver, outcome, model_version, card_version]
evaluation:
  set: "past requests with accepted definitions, plus seeded sensitive-attribute traps"
  metrics: [override_rate, sensitive_attribute_failures_caught]
  must_be_refused: [activate_segment, read_free_text_field, use_special_category_attribute]
  rerun_on: [model_change, prompt_change, tool_schema_change]
owner: "Head of marketing operations"
kill_switch:
  manual: "Orchestrator pause"
  automatic: "3 rejected drafts in a row on one request"

Four lines in this example do most of the work.

• execute: [] means the agent cannot activate anything. Drafting and publishing are separate rails. In the segmentation walkthrough, a separate service re-checks consent and acts only after approval. A bug or a hijack in drafting stops at a draft.
• binds_to: definition_hash means any later edit voids the approval. The reviewer approved these exact contents, not a version of them.
• on_timeout states that a timeout expires. It never approves.
• must_be_refused turns the "never" list into tests. Each entry is a call the gateway must refuse and log. A "never" with no test is only a hope.

The 50 runs, the budget, the 48 hours and the audience threshold are placeholders. Set your own, and use words on the card until you have evidence for a number.

Rail card, Agent Card, model card, DPIA: what does each one do?

A rail card restricts one job, while the five documents most often confused with it do other work. "Agent card" is already a protocol term, so the naming trap is real.

Keep all that apply, and link the model card and the DPIA from the rail card. An auditor can then walk from the job to the assessment.

Where is each rail card field enforced?

Each rail card field needs a named system that refuses when the field is broken. A field no system enforces is documentation, and the card should say so. This table is the core of the method, and the test column shows how to prove each control works.

Two design rules sit behind the table. Rules enforce and models explain, so a model's "pass" never overrides a failed rule. And each card should name which Rule of Two properties its session holds 8. A session that reads untrusted text and holds sensitive data gets no state-changing tools, so delivery of a report runs in a separate service, not as a tool the model holds.

How does a rail card map to MCP tool permissions?

A rail card maps to MCP tool permissions through its tool scope field: each verb becomes a set of scopes on one agent identity. The Model Context Protocol leaves this design to you. Its current revision is 2026-07-28, and MCP for Salesforce, HubSpot and your own platform explains what it does and does not guarantee. These steps take a card to a working configuration.

1. Give each rail its own agent identity, so the ledger can tell jobs apart and you can revoke one without breaking others.
2. Turn each entry under read, propose and execute into a named scope, with no wildcards.
3. Keep the verbs on separate credentials or tool servers, so a propose token cannot call an execute tool.
4. Issue short-lived tokens bound to one server. Mint a write token only after approval, in the execution service and never in the model's session.
5. Pin each tool's description and schema by hash. A change counts as a new approval and triggers a regression run, because a server can alter a tool description after you approved it 9.
6. Treat tool annotations as hints. MCP says clients must treat them as untrusted unless they come from a trusted server 10, so enforce read-only in the gateway.

PrivyCDP's product page describes an MCP-ready interface and an immutable audit ledger that records each AI-assisted action with the human or system actor that authorised it; the rail card itself is a vendor-neutral method, not a product feature.

Who may change a rail card?

Who may change a rail card depends on whether the change narrows or widens what the agent can do. Every change creates a new version.

Each run's ledger entry records the card version, so a reader can tell which rules applied. Store cards versioned next to your segmentation rules, in the customer's own environment, somewhere the agent cannot write to. The Trainer may propose a change, and a person decides it.

How does an auditor read a rail card?

An auditor reads a rail card as the claim and the audit ledger as the evidence. Comparing the two answers three questions.

1. Did any run go beyond the card? Compare the tools called and the fields read with the card version recorded on that run.
2. Was every execution approved by the right person? Check that the approver was not the requester, that the approved hash matches the executed hash, and that no approval had expired.
3. Who changed the card, and was the change tested? Match each new version to its decider in the table above, and to a regression result.

The Policy Drift Checker runs this kind of comparison on metadata, and an owner decides what to do about the findings.

The ledger names approvers because accountability needs a name. Reports drawn from it should still go by rail and role. Annex III point 4(b) of the EU AI Act lists monitoring workers' performance and allocating tasks by individual behaviour as high-risk uses 11, so take advice before using ledger data to rate named staff.

Four common rail card mistakes

Four mistakes make a rail card look complete while leaving the agent uncontrolled. Each has a simple fix.

How do you fill your first rail card in a 60-minute workshop?

A first rail card fits a suggested 60-minute workshop with three people: the job's owner, a security engineer and a reviewer who will use the output. Start from a real, low-risk job such as journey QA or a reporting summary.

1. Write the job in one sentence. If it needs two outcomes, pick one.
2. Write the trigger, and what must never start a run.
3. List the fields the job truly needs. Strike anything the last few real examples did not use.
4. List tools by read, propose and execute. Default execute to none.
5. Define the output so a reviewer can check it without rerunning the job.
6. Name the gate: the approver's role, the evidence they see and what a timeout does.
7. Set the limits, and say which system enforces each one.
8. List the ledger fields and the system that writes them.
9. Write the evaluation, with at least one test for each "never".
10. Name the owner and how to stop the agent. Then mark each field as enforced or as documentation, and log the gaps.

Run the finished card in shadow mode before anything depends on it.