A purchasing agent with a spending allowance
This example is for a finance lead or an office manager who wants an agent to buy small things on the company's behalf. You will write an instruction that says what the agent may buy, how much it may spend, from which shops, and when it must ask a person first.
The situation
The Acme office runs out of paper, ink and pens every few weeks. Someone has to notice, compare prices and order. You want an agent to do it, but only within limits:
- at most 200 EUR a month in total;
- the office manager says yes before any single payment above 50 EUR;
- only from the two shops the company already uses.
What you'll make
An instruction with four rules for the agent, the office card it pays with (a wallet), and the limits on that card (an allowance). In Preview, the allowance shows as a card marked spending limits, listing each limit.
What you need
- An instruction.md account. Every plan can write and publish this instruction.
- An app or platform that pays for the agent. instruction.md itself never makes a payment. Read What the agent's platform still decides before you start.
Steps
Start a new instruction
Choose New instruction in the side bar. A new page opens with its name selected.
Write the rules and the limits
Type or paste this text. The first part is ordinary rules. The part under Paying names the person who approves, the card, and the limits.
Office purchasing--- spec: "1" title: Office purchasing --- # Office purchasing You order office supplies for the Acme office when someone at Acme asks for them. MUST: buy only what a person at Acme asked for, and name them in the order note. BECAUSE: every purchase needs a person who wanted it. MUST: compare the price at both approved shops before you buy anything over 20 EUR. NEVER: buy gift cards, subscriptions or anything that renews by itself. SHOULD: put the requests of one day into one order. ## Paying ::person{id=office-manager title="The office manager" role=approver} ::wallet{id=office-card title="Office card" account=office-card} :::allowance{id=supplies title="Office supplies" wallet=#office-card currency=EUR budget=200 per=month approve-above=50 approver=#office-manager payees="officeshop.example,paperdepot.example"} Paper, pens, printer ink and small desk equipment. :::Check the allowance in Preview
Open Preview. The allowance is a card titled Office supplies, with the limits listed one by one. If an amount is wrong, the editor says A spending amount isn't a valid amount. Fix it in the text. See Check your instruction before you publish.
Publish it
Choose Publish… and publish version 1. instruction.md signs the version for you, unless your organization turned signing off. See Publish a version.
Pin the agent to that version
Connect the agent so that it follows Only v1, not the live version. See Pin to one version. The next section says why this matters.
What each limit means
| What you write | What it means here |
|---|---|
| The wallet, Office card | The card the agent pays with. The text names it by the name the agent's platform knows it by. It never holds a card number, a password or a key. |
| The currency, EUR | Every amount is in euros. A currency is written as its three capital letters, such as EUR, USD or GBP. |
| The budget, 200 per month | The agent may spend 200 EUR in each calendar month, counted in UTC (world time). A budget is required. Without a period, it is the total for the allowance's whole life. |
| Ask above, 50, and the approver, the office manager | A payment up to 50 EUR may go ahead. Above 50, it waits for the office manager's yes. The approver is always a person or a role, never an agent. |
| The payees, two shops | The agent may pay only these shops. Without this list, the platform's own list applies. |
| The text inside | What the money is for, in words: paper, pens, printer ink and small desk equipment. |
An allowance can also set the most for one payment, how many payments there may be, which kinds of purchase are allowed, and the dates it is valid between. A payment above the most for one payment is refused, even with a yes. So is anything else outside the limits.
Why it must be signed and pinned
An allowance lets an agent spend money, so the agent's platform is careful about which text it trusts. It applies the allowance only when all of these hold:
- The version is signed, and the signature says it has spending in it. By default, instruction.md signs every version you publish with your organization's key. When the version holds an allowance, the signature says so. This proves who published the limits and that nobody changed them on the way.
- The agent follows one exact version. This is a pin. If the agent followed the live version, anyone who can publish could change the limits for it. With a pin, new limits reach it only when someone moves the pin on purpose.
- Whoever runs the platform has turned spending on for this agent. Without that, nothing in the instruction lets the agent pay.
If any of these is missing, the agent still reads the limits as part of its instruction, but no payment is made on their strength.
What the agent's platform still decides
The instruction says what the limits are. The app or platform that holds the card applies them:
- The smallest limit wins. The platform's own limits and the card's own limits still count. An allowance can only make spending narrower. It never turns on spending the platform hasn't enabled.
- The platform keeps the count. It adds up what was spent, for this instruction and this allowance, in each month. Publishing a new version doesn't reset it.
- Lowering a limit takes effect. If you lower the budget or remove the allowance, what the platform issued under the old limit is withdrawn.
- The platform asks the approver. How the office manager is asked, and how they answer, is up to the platform.
instruction.md never pays for anything, and connecting an AI app to instruction.md doesn't give it a way to pay. Whether an app or a platform applies allowances is up to that app. To check, ask whoever runs it, or send them the page for developers.
Change the limits
Change the text, then publish a new version. An agent pinned to version 1 keeps the old limits until someone pins it to the new version.
When your instruction builds on another one, it may only narrow an allowance it takes from there: a smaller budget, fewer shops, a lower amount before asking. It may not raise an amount, add a card, change the period or the currency, or replace the approver. If it does, the editor says A spending limit goes beyond what is allowed.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
| A spending amount isn't a valid amount. | An amount isn't a plain number, or it has more than 18 decimal places. | Write amounts as numbers, such as 200 or 49.90, without the currency sign. |
| A spending limit goes beyond what is allowed. | The instruction builds on another one and widens its allowance. | Keep each limit at or below the one it comes from. |
| Part of this instruction can't be read as written. on the allowance | The budget or the currency is missing, the currency isn't three capital letters, the period isn't day, week, month, quarter, year or once, the most for one payment is above the budget, the amount to ask above is above the most for one payment (or the budget), or the approver is neither a person nor a role. | Correct the value it points to. See Check your instruction before you publish. |
| A mention points at something that isn't in this instruction. or A mention points at something of a different kind. | The wallet or the approver names something missing, or the wallet names something that isn't a wallet. | Check that the names match. In the sample, #office-card names the wallet and #office-manager names the person. |
| The agent doesn't pay at all | Its platform doesn't apply allowances, spending isn't turned on, or the agent isn't pinned. | See Why it must be signed and pinned. |
| Still stuck | Something isn't working, or ask us. |
Questions
Can an instruction let an agent spend money?
It can say how much an agent may spend, where, and when it must ask a person. The app or platform that holds the card applies those limits. instruction.md never pays. See What the agent's platform still decides.
Why must the agent be pinned to one version?
So that the limits can't change under it. A pinned agent keeps the limits of one signed version until someone moves the pin on purpose. See Why it must be signed and pinned.
Does publishing a new version reset what the agent has spent?
No. The platform counts spending for the instruction and the allowance in each period, whatever the version. Lowering a limit withdraws what was issued under the old one.
Can an agent approve a payment?
No. The approver is always a person or a role. If the approver names anything else, such as an agent, the editor marks the allowance as an error, and a version with an error can't be published. See What each limit means.