Skip to content

Docs: a recipe for agent spending limits and offline receipts (intent grants) - #830

Merged
LoopGlitch26 merged 2 commits into
mainfrom
agent/spending-recipe
Nov 14, 2026
Merged

LoopGlitch26 merged 2 commits into
mainfrom
agent/spending-recipe

Conversation

@LoopGlitch26

Copy link
Copy Markdown
Member

What it adds

  • docs/quickstarts/agent-spending.md: "Spending limits and receipts for any agent". An OpenAI Agents SDK agent pays through a send_payment tool on the dev signer:
    1. the first payment (30 USD) is held (TK-M001, TK-M002);
    2. the person approves it with a grant: two payees, at most 50 USD each, 120 USD in all, for 1h (tracekit approvals approve ID --grant ...);
    3. the next two payments run on their own, each signed flag with TK-GRANT and what is left (45 of 120 USD left, 20 of 120 USD left);
    4. a 40 USD payment past the total is held, with the signed reason grant g-…: 100 of 120 USD used; this call needs 40 USD, and the person rejects it;
    5. the run is exported and tracekit verify checks it offline, with the intent grants line passing. The .tkb and trust.json are the receipt. A copy with one payment edited reads TAMPERED.
      The page is marked experimental. It ends with what the receipt shows and its limits: dev signer, self-approved, T1, fields not checked against arguments, one run.
  • examples/v2/openai_agents/spending.py: the runnable example. It uses a scripted model and needs no API key. --scripted runs the person's commands as a second process, the way the other v2 examples do. Without it, it prints them and waits.
  • tests/test_grants.py::TestAgentSpending: the same flow in-process, with the adapter and a real SignerService on the dev pack. It checks each step: held, granted (self-approved, first payment counted), released within bounds with exact reasons and ext.grant fields, held over the total with the reason, the rejected call never ran, and the bundle verifies with the grant check passing.
  • tests/test_examples_v2.py::test_openai_agents_spending: runs the example end to end.
  • Links: docs/quickstarts/README.md (a new Recipes list), docs/intent-grants.md, and docs/limits.md. The page has a limits section, and test_docs requires limits.md to link it. Also a short section in examples/v2/openai_agents/README.md.

How I ran it

  • I ran python examples/v2/openai_agents/spending.py --scripted in a fresh HOME and runtime dir with this branch's code. The output on the page is from that run, and every output line on the page was checked against it. I ran tracekit verify (short form) on the receipt and on an edited copy by hand.
  • I ran it without --scripted. It printed the person's commands and waited. I stopped it there and did not approve as the agent.
  • make lint: passed.
  • pytest tests/test_grants.py tests/test_docs.py tests/test_examples_v2.py: 61 passed, 7 skipped (frameworks not installed). Both new tests ran.
  • pytest tests/test_wiki.py tests/test_eval_docs.py: 11 and 3 passed.
  • python scripts/wiki.py OUT: 132 pages. The new page is Quickstarts-Agent-Spending, in the Get started sidebar.

Not run: the full make test, make build and make test-ts. The CI Linux run is the gate for those.

Found while writing it, not changed here

  • For a call that a live grant held, tracekit approvals show prints the rules' reasons (sending money (TK-M001); moving money (TK-M002)), not the grant's reason. Its grant line also offers a new grant. The approval record has no reason field. The exact reason is only in the signed decision (reasons) and the decide response.
  • The OpenAI Agents adapter doesn't pass the decide reason to the app on an ask. So the example prints the reason from the bundle after export.

… grants)

docs/quickstarts/agent-spending.md: an OpenAI Agents SDK agent pays through a
send_payment tool on the dev signer. The first payment is held, the person
approves it with a payment grant (two payees, 50 USD each, 120 USD in all, an
hour), the next two run within it, one past the total is held with the signed
reason, and the exported bundle verifies offline with the intent grants line.
The output on the page is from a run of the example.

examples/v2/openai_agents/spending.py runs it with a scripted model (no API
key); tests/test_grants.py runs the same flow in-process and checks each step;
tests/test_examples_v2.py runs the example end to end. Linked from the
quickstarts index, intent-grants.md and limits.md.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
Say which agents the recipe covers (payments through a tool Tracekit gates),
that on the dev signer the agent itself could have issued the grant or approved
a payment, where the example prints the signed decisions, and that --scripted
plays the person.

Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
@LoopGlitch26
LoopGlitch26 enabled auto-merge (squash) November 14, 2026 01:08
@LoopGlitch26
LoopGlitch26 merged commit 6bde2c3 into main Nov 14, 2026
32 of 34 checks passed
@LoopGlitch26
LoopGlitch26 deleted the agent/spending-recipe branch November 14, 2026 04:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant