What a registration holds
- Lesson 7
- 40 min
- Module 3: Register every agent
Where we are
In the last module, we gave each capability a contract, and we blocked Omar's remap with each consumer's evidence. The catalog now says what a capability promises. But it does not say who may use it, for what, with which data, or who answers when something goes wrong. In this lesson, we write the record that every agent needs before its first call, the way a company keeps a record of every van in its fleet.
Lesson 7 of 21 · Governing AI Agents: Gateways, Registries and ControlsWhat a registration holds
1. Why agents need platform controls
2. Ask for capabilities, not models
3. Register every agent
4. The model gateway
5. Govern tools and actions
6. Usage, evidence and shadow AI
7. Build, buy and roll out
What you will be able to do
Write a registration for each of Larkfield’s agents before it calls anything. It says who owns the agent, what it does and how risky it is. It also says which data and capabilities it may use, what it may spend and when someone checks it again. The registry checks each form and refuses the ones that the platform cannot allow.
Before you startWhat to know and to have ready
What you need to know
- Capabilities and their contracts, from A capability catalog. A contract lists the data classes that a capability allows.
- The data classes
public,internal,personalandpaymentinconfig/data-classes.yaml, from the same lesson. - Each consumer’s evaluation and the remap gate, from Change a mapping safely. The draft forms in
registrations/come from there. - What the support workflow does: it proposes refunds, return labels and reships, and a person approves each one. You met it in AI Agents and Workflow Orchestration.
What you need on your computer
- The project
~/projects/ai-estate, the same as the snapshotend-of-m02, with its virtual environment active.python -m pytest -qends with104 passed, 1 deselected. If your project is broken, copy the snapshotend-of-m02as its README says. - The labs repository in
~/projects/nextia-learning-labs. Get the newest files first:git -C ~/projects/nextia-learning-labs pull.
Tested on macOS (Apple silicon) with Python 3.12.13. The Windows (PowerShell) and Linux commands are written for you, but the course did not run them.
A fleet of vans
Section titled “A fleet of vans”Think of a company with forty delivery vans. The office keeps a fleet register, with one card for each van. The card names the person who answers for the van. It says what the van is for, who may drive it, and what it may carry: parcels, yes; chemicals, no. It also gives the limit on the fuel card, and the date of the next inspection.
For most vans, one short card is enough. But one van carries gas bottles. For that van, the company fills in a longer form. It says what can go wrong, who checks the load, and who to call after an accident. That van also needs an inspection before its first trip, and more often after that.
The register is useful because of its rules. No card, no keys: a van without a card does not leave the yard. When the responsible person leaves the company, the van gets a new responsible person. When a van is sold, its card stays in the archive, and its number is never given to another van.
The problem: five agents, and five questions with no answer
Section titled “The problem: five agents, and five questions with no answer”Larkfield’s estate has the same vans without the cards. Kwame, the platform owner, asks five simple questions about the estate:
- Who answers for the weekly digest?
- Which apps may send customer messages to a model?
- Which agent may change money or goods?
- How much may each one spend in a month?
- When did anyone last check the release judge?
Nobody can answer them. The drafts from Module 2 hold only what the remap gate needs. That is an ID, a name, an owner, a team, the capabilities and the evaluation. Kwame adds the estate’s first registry code, and checks the triage service’s draft. Before you look, predict: which of the five questions does the draft answer?
- missing: kind, purpose, users, risk_tier, data_classes, tools, autonomy, budget_usd_month, limits, review_date- limits.requests_per_minute: a whole number, 0 or more- limits.tokens_per_day: a whole number, 0 or more- limits.max_calls_per_run: a whole number, 0 or moreOnly the first one, about the owner. The draft says that Amira owns the triage service. It does not say what data the service sends, how risky it is, what it may spend or when it is checked again. And the weekly digest has no draft at all.
The idea: a registration, kept in a registry
Section titled “The idea: a registration, kept in a registry”A registration is the record that an agent must have before its first call. It answers the questions above in fixed fields, so that both a person and a program can read them. The registry is the place that keeps every registration, with its status and its history. In this course, the registry is a small SQLite database, state/registry.db, and the command python -m estate reads and changes it.
The word comes from the fleet register, and from every official register of cars, companies or medicines. The idea is the same. A thing may operate only if it has a record, and the record names who answers for it.
Like the vans, most agents need only a short form. An agent with a high risk also fills in a long form. Here is what each field means, and what the platform does with it:
| Field | What it answers | What the platform does with it |
|---|---|---|
id, name, kind |
Which agent is it? kind is app, agent, tool-server or script. |
The ID becomes the agent’s identity: its client ID, in the next lesson. |
owner, team |
Who answers for it? | An owner who has left the company blocks the registration. |
purpose, users |
What does it do, and for whom? | The inventory, and the monthly report. |
risk_tier |
How much harm can a mistake do? | low, medium or high: the review interval, the long form, and later the failure mode. |
data_classes |
Which data may it send to a model? | Each capability’s contract must allow each class. payment never goes to a model. |
capabilities |
Which capabilities may it ask for? | The gateway refuses any other capability. |
tools |
Which tools may it call? | The tool gateway refuses any other tool. |
autonomy |
Does it act alone? | suggests, acts-with-approval or acts. A high-risk agent may not act. |
budget_usd_month, limits |
What may it spend and send? | Hard stops at the gateway: dollars a month, tokens a day, requests a minute, model calls per run. |
review_date |
When does someone check it again? | python -m estate review-due lists every review that is overdue. |
Two fields depend on the agent. evaluations names the evidence for each capability that the agent uses, and the remap gate of Module 2 reads it. pins keeps one exact model for a capability, with a date when the pin ends. The long form, for high risk only, adds impact, human_oversight, failure_mode, incident_contact, data_retention and kill_switch_tested.
Risk tier and autonomy, in plain words
Section titled “Risk tier and autonomy, in plain words”Two fields need a decision, not a lookup. The risk tier says how much harm a mistake of the agent can do. Ask three questions. Does it change anything in the world, such as money, goods or a customer’s account? Does it see personal data? Does a customer see its output before a person checks it?
- Low: it suggests things to staff, with internal data only. The document assistant is low.
- Medium: it sees personal data, or its output matters, but a person decides. The triage service and the release judge are medium.
- High: it can change money or goods, even with a person’s approval, or many people depend on it. The support workflow is high.
The autonomy level says how the agent acts. suggests means that a person does the action. acts-with-approval means that the agent does the action after a person approves it. acts means that it does the action alone.
The tier decides how often a person checks the registration again. The interval is at most 12 months for low risk, 6 for medium and 3 for high. A high-risk registration starts as pending, and it cannot call anything until a person reviews it. Low and medium registrations become active at once. This is the inspection before the first trip.
Who decides what “high” means for Larkfield? The organisation’s governance does, in policy. A later course on AI governance covers that. This course turns the decision into controls that a program can check.
A tiny worked example: the triage service’s form
Section titled “A tiny worked example: the triage service’s form”Here is the triage service’s complete short form, registrations/ticket-triage.yaml. Every value is visible:
# Registration (short form). Fill it in before the first call: python -m estate register registrations/ticket-triage.yamlid: ticket-triagename: Ticket triagekind: appowner: usr-amirateam: servicepurpose: Reads each new ticket and returns the team and whether a person must handle it.users: The help desk reads the result. Customers do not see it.from: the MLOps course's ticket service (its triage step)risk_tier: mediumdata_classes: [personal]capabilities: [fast-small, embed]tools: []autonomy: suggestsbudget_usd_month: 15limits: {requests_per_minute: 600, tokens_per_day: 2500000, max_calls_per_run: 3}evaluations: fast-small: {evaluation: "evaluation course, triage set, dev split", measure: decisions, minimum: 0.85}review_date: 2027-01-15Read it as Kwame does, and justify each choice:
risk_tier: medium. The service reads customer tickets, so it sees personal data. But it changes nothing, and a person reads its result. It is not low, because of the data, and not high, because it does not act.data_classes: [personal]. A ticket holds names and order details. The class is the most sensitive data that the service sends.capabilities: [fast-small, embed]. One chat call chooses the team, and one embedding feeds the search. It needs nothing stronger.tools: []andautonomy: suggests. It calls no tool and does nothing itself.limits. 822 tickets a day, at most 3 calls each, make about 2,500 calls a day. So 600 a minute is far above normal traffic. The limits stop a loop, not normal work. Module 4 shows them working.review_date: 2027-01-15. That is less than 6 months away, as a medium tier requires.
The registry checks a form in a fixed order. The diagram shows the order and one real refusal at each step:
Text description of the diagram
The form goes to python -m estate check or register. The checks run in this order:
- Are the 15 fields of the short form filled in? If not, the answer starts with
missing:and lists them. - Is the owner still at Larkfield, and is the team known? An owner who left gives
owner usr-lee: left the company on 2026-08-31. - Is each capability in the catalog, and does its contract allow each data class? Payment data never goes to a model. An unknown capability gives
capability teleport: not in the catalog. - Is the risk tier high? For low or medium, the review date must be at most 12 or 6 months away. The form is then registered as active.
- For high, the long form must be filled in, the autonomy must not be
acts, and the review must be at most 3 months away. A missing long form giveshigh risk needs the long form: missing long_form.impact, …. A complete form is registered as pending. A person reviews it withpython -m estate review, and then it is active.
Larkfield: register the triage service
Section titled “Larkfield: register the triage service”You add the registry code, the people and teams of Larkfield, and the form’s documentation. Then you complete the triage service’s form, check it and register it.
-
In
~/projects/ai-estate, copy this lesson’s code and data from the snapshotend-of-m03:Terminal window S=../nextia-learning-labs/C32/snapshots/end-of-m03cp $S/estate/registry.py estate/cp $S/estate/cli/registry.py estate/cli/cp $S/config/people.yaml $S/config/teams.yaml config/cp $S/docs/registration-form.md docs/Terminal window $S = "..\nextia-learning-labs\C32\snapshots\end-of-m03"Copy-Item $S\estate\registry.py estate\Copy-Item $S\estate\cli\registry.py estate\cli\Copy-Item $S\config\people.yaml, $S\config\teams.yaml config\Copy-Item $S\docs\registration-form.md docs\Terminal window S=../nextia-learning-labs/C32/snapshots/end-of-m03cp $S/estate/registry.py estate/cp $S/estate/cli/registry.py estate/cli/cp $S/config/people.yaml $S/config/teams.yaml config/cp $S/docs/registration-form.md docs/config/people.yamllists Larkfield’s people, and the day a person left.config/teams.yamllists the teams. -
Check the draft form of the triage service:
Terminal window python -m estate check registrations/ticket-triage.yamlYou see the list of missing fields from the problem above, and the exit code is 1. The command
estate --helpnow also listsregister,list,show,review,suspend,resume,retire,review-dueandevents. -
Complete the form. Open
registrations/ticket-triage.yamlin VS Code, and make it the same as the form of the worked example above. You can also copy the complete form:Terminal window cp $S/registrations/ticket-triage.yaml registrations/Terminal window Copy-Item -Force $S\registrations\ticket-triage.yaml registrations\Terminal window cp $S/registrations/ticket-triage.yaml registrations/ -
Check the form again:
Terminal window python -m estate check registrations/ticket-triage.yamlThe form is complete. -
Register it:
Terminal window python -m estate register registrations/ticket-triage.yamlRegistered ticket-triage (version 1): activeA medium-risk registration is active at once.
-
Read the registration back from the registry:
Terminal window python -m estate show ticket-triageticket-triage | Ticket triage | active | version 1owner usr-amira (service) | risk medium | autonomy suggests | data personalcapabilities: fast-small, embedtools: nonebudget US$15/month | 600 requests/min | 2,500,000 tokens/day | 3 model calls per runreview by 2027-01-15 | credentials: nonecredentials: noneis the next lesson’s work. Today, the registration exists, but no agent can prove that it is the triage service.
The registry stores the whole form as JSON, with a status and a version number. Each change is also an event, with who made it and why. You read those events in The agent lifecycle.
The long form: the support workflow
Section titled “The long form: the support workflow”The support workflow is a different van. It proposes refunds, return labels and reships, and the order systems carry them out after a person approves. A wrong proposal that someone approves moves money or goods. So its registration is high risk, and it has the long form:
Text description of the diagram
The diagram shows registrations/support-workflow.yaml line by line, with a note beside each group of lines. A green note means that the registry or the gateway checks the field from this module on. A dashed note means that a later control uses it.
Short form, every agent:
id: support-workflow,name,kind: agent: its identity. The ID becomes the agent’s client ID, and every token names it. (Green.)owner: usr-amira,team: service: who answers for it. An owner who has left blocks the registration. (Green.)purpose,users,from: the inventory: what it does, for whom, and where it came from. (Green.)risk_tier: high: the long form, a review before it runs, and a review at least every 3 months. (Green.)data_classes: [personal]: the most sensitive data that it may send. Payment data never goes to a model. (Green.)capabilities: [strong-reasoning, fast-small]: the model gateway refuses any other capability. (Green.)tools: nine order tools, such asorders.get_orderandorders.request_refund. The tool gateway will refuse any other tool. (Dashed.)autonomy: acts-with-approval: a person approves every write. A high-risk agent may not act alone. (Green.)budget_usd_month: 25andlimits: 120 requests a minute, 2,000,000 tokens a day, 8 model calls per run. Hard stops that the gateway will apply. (Dashed.)evaluations: strong-reasoning, task success, minimum 0.95. The evidence that the remap gate uses before a capability changes model. (Green.)review_date: 2026-12-01:estate review-duelists it when this date has passed. (Green.)
Long form, high risk only: impact, human_oversight, failure_mode: fail_closed, incident_contact: usr-amira, data_retention and kill_switch_tested: null. They say what can go wrong, who watches, what happens when the platform fails, who to call, and which data is kept.
Notice kill_switch_tested: null. Nobody has tested the workflow’s kill switch yet, and the form says so honestly. Module 5 runs that test. A registration is a record of facts, so an empty fact stays empty until someone checks it.
Sam asks the beginner’s question: “Why not give every agent the long form? It is safer.” Kwame answers with the vans. Forty long forms take forty hours. People then copy old answers, and nobody reads them. A short form for most agents, and a long one where the harm is real, keeps the long form worth reading. Tomás has the opposite worry: “The form slows teams down.” The short form has 15 fields, and most answers are one word. Module 7 measures the friction that the platform causes.
Your turn: register the support workflow
Section titled “Your turn: register the support workflow”Change one condition: a high-risk agent. Before you run anything, predict two things. What status will the workflow get when you register it? What must happen before it can call anything?
-
Copy the complete forms of the other apps from the snapshot:
Terminal window cp $S/registrations/*.yaml registrations/Terminal window Copy-Item -Force $S\registrations\*.yaml registrations\Terminal window cp $S/registrations/*.yaml registrations/If you opened a new terminal, set
Sagain first, as in step 1 of the last steps. -
Check
registrations/support-workflow.yaml, then register it. -
Show its registration, and read its status.
-
Review it as the platform owner, with the next review on 1 December 2026:
python -m estate review support-workflow --next 2026-12-01 --note "first review". -
Register the other four forms, and review the support MCP server: it is high risk too.
Terminal window for f in doc-assistant release-judge helpdesk-assistant support-mcp; do python -m estate register registrations/$f.yaml; donepython -m estate review support-mcp --next 2026-12-01Terminal window foreach ($f in "doc-assistant", "release-judge", "helpdesk-assistant", "support-mcp") { python -m estate register registrations\$f.yaml }python -m estate review support-mcp --next 2026-12-01Terminal window for f in doc-assistant release-judge helpdesk-assistant support-mcp; do python -m estate register registrations/$f.yaml; donepython -m estate review support-mcp --next 2026-12-01 -
List the registry with
python -m estate list.
Check your work
The check and the registration:
The form is complete.Registered support-workflow (version 1): pending until a review approves it (python -m estate review support-workflow)python -m estate show support-workflow before the review:
support-workflow | Support-resolution workflow | pending | version 1 owner usr-amira (service) | risk high | autonomy acts-with-approval | data personal capabilities: strong-reasoning, fast-small tools: orders.get_order, orders.get_customer_orders, orders.get_payments, orders.search_policy, orders.get_operation, orders.create_return_label, orders.reship_item, orders.request_refund, orders.add_ticket_note budget US$25/month | 120 requests/min | 2,000,000 tokens/day | 8 model calls per run review by 2026-12-01 | credentials: noneThe review:
Reviewed support-workflow: active, next review by 2026-12-01.The four other forms: doc-assistant, release-judge and helpdesk-assistant are active at once, and support-mcp is pending until its review. Then python -m estate list:
doc-assistant active low data usr-mei fast-smallhelpdesk-assistant active medium service usr-amira fast-smallrelease-judge active medium evaluation usr-priya strong-reasoningsupport-mcp active high platform usr-kwame -support-workflow active high service usr-amira strong-reasoning, fast-smallticket-triage active medium service usr-amira fast-small, embed6 registrationsThe workflow was pending after register, because it is high risk. Until a person reviews it, it cannot get credentials or call anything. What if the form had no long form? The course team deleted the long_form block from a copy of the form, and check printed:
- high risk needs the long form: missing long_form.impact, long_form.human_oversight, long_form.failure_mode, long_form.incident_contact, long_form.data_retentionkill_switch_tested is not in that list. It may stay empty until someone tests the switch.
Run the tests: python -m pytest -q still ends with 104 passed, 1 deselected. This lesson’s own tests come with the next lesson’s files, because one of them needs the credentials.
Common mistake
A form for the weekly digest
Symptom: Tomás wants to make the weekly digest legal quickly. He writes a form in a new folder, drafts/weekly-digest.yaml, with Lee as the owner, because Lee wrote the script:
id: weekly-digestname: Weekly digestkind: scriptowner: usr-leeteam: servicepurpose: Summarises the week's customer messages for the Monday meeting.users: The service team reads the summary on Mondays.risk_tier: mediumdata_classes: [personal]capabilities: [fast-small]tools: []autonomy: suggestsbudget_usd_month: 1limits: {requests_per_minute: 1, tokens_per_day: 10000, max_calls_per_run: 1}review_date: 2027-01-15python -m estate register drafts/weekly-digest.yaml prints:
Not registered:- owner usr-lee: left the company on 2026-08-31; a registration needs an owner who is herepython -m estate list still shows 6 registrations.
Cause: config/people.yaml says usr-lee: {…, left: 2026-08-31}. A registration names the person who answers for the agent today. A person who left cannot answer for anything.
Diagnose: run python -m estate check on the form. It lists every problem, not only the first one. Here, the owner is the only problem.
Recover: a registration needs an owner who is here. Someone in the service team must decide to own the digest, or the digest must stop. Making that decision is part of the final assignment, so leave it for now. Delete the folder drafts (on Windows, Remove-Item -Recurse drafts).
Consequence in AI work: an agent without a living owner keeps running, keeps spending and keeps sending data, and nobody notices when it breaks. The digest ran every Monday for weeks after Lee left. The registry cannot stop a script that never registered, but it refuses to make an orphan look owned.
When a registration helps, and what it costs
Section titled “When a registration helps, and what it costs”A registry pays once several teams run agents with shared models and budgets, as at Larkfield. One team with one app can keep the same facts in its README. The cost is real: a form for each agent, a person who reviews the high-risk ones, and reviews that come back every few months. It also only works if there is no way around it. The next lesson makes the gateway refuse every call without a valid registration. Module 6 finds the agents that never registered.
A registration is also only as true as its answers. Nothing in the form proves that the triage service sends no payment data. The gateway checks that later, in Module 4, and the registration tells it what to check.
Knowledge check
Section titled “Knowledge check”Check your understanding
Mei wants the document assistant to answer questions about customers' orders. Today it is low risk with data_classes: [internal]. Which fields must change, and what does the registry do with the new version?
Show the answer
data_classes must list personal, because orders name customers. With personal data, the risk tier should rise from low to medium, and the review date must then be at most 6 months away. Mei registers the changed form as a new version (version 2). For low and medium agents, the registry keeps the status active, and the event lists the changed fields. If the change made it high risk, the long form would be required, and the registration would wait for a review.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Check your understanding
Predict: Tomás registers a new agent with risk_tier: high and autonomy: acts. What does the registry answer, and why is that rule in the platform and not only in the policy document?
Show the answer
It refuses: “a high-risk agent may not act without a person’s approval (autonomy: acts-with-approval)”. The policy can ask for approvals, but a person can forget it or misread it. The registry checks it on every form, so a high-risk agent that acts alone never gets a registration. Without a registration, it cannot get credentials or call anything.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Check your understanding
Why does the long form exist only for high-risk agents? Name two of its fields and what each one is for.
Show the answer
A long form for every agent costs hours, and people then copy answers without reading them. Keeping it for high risk keeps it worth reading. Any two of these:
impact: what a mistake can do, such as moving money.human_oversight: who checks before an action.failure_mode: what happens when the platform fails,fail_closedfor the workflow.incident_contact: who to call.data_retention: which data is kept, and for how long.kill_switch_tested: whether someone tested the stop.
Does your answer have the main points of ours?
Sign in and enroll in the course to save your answers. Every check counts toward the certificate.
Recap
- A registration is the record that an agent needs before its first call. The registry keeps every registration, with its status, its version and its history.
- The short form has 15 fields. They give the identity, the owner and team, the purpose and users, and the risk tier. They also give the data classes, capabilities, tools, autonomy, budget, limits and review date.
- High risk adds the long form: impact, oversight, failure mode, incident contact, data retention and the kill-switch test.
- The risk tier follows from what a mistake can do. It sets the review interval (3, 6 or 12 months). A high-risk registration starts as pending until a person reviews it.
- The registry refuses what the platform cannot allow. Examples: missing fields, an owner who left, an unknown capability, payment data for a model, or a high-risk agent that acts alone.
- Larkfield now has 6 registrations, all active. The weekly digest has none: its owner left.
You can now say who owns each agent, what it may do and what it may spend. But the registry is only a record. Every app still calls the provider with a shared or personal key, and nothing connects a call to a registration. Next, we give each agent its own identity and short-lived credentials. Then the gateway refuses every call without them.
Next: One identity per agent