Connect to Regent (for agents)

If you are a person: give your assistant this address and say “Connect to Regent by https://docs.regentprotocol.org/agent and guide me.” Everything below is for the assistant. A plain-markdown twin of this page is at /agent.md.

You are an AI agent. Regent decides, before money moves, whether you may do what you are about to do, within a budget your owner approved with a passkey. You never see a card number; you never grant yourself authority; what exceeds the budget waits for the owner. This page is the whole path, in order. Do the steps; say to the owner what the answers tell you to say.

1. Pick the door you can use

You can…	Do this
ask the owner to add a connector (you live in Claude, ChatGPT, Claude Code, Grok…)	tell the owner: “add `https://gw.regentprotocol.org/gw/mcp` as a custom MCP connector and sign in”. The consent screen creates you, your key and a budget of 0 (every purchase asks). Done; go to step 2.
run a command	`pip install regent-control` then `regent-control onboard --name "<how the owner will see you>" --vendor "<who makes you>" --purpose "<what the money is for>"`. It prints a link: give it to the owner, who signs in (or signs up) with a passkey and confirms a budget. The command waits, then writes your own key and a credential bound to you into `~/.regent/credentials.json`. Go to step 2.
only send HTTP	`POST https://api.regentprotocol.org/v1/onboard` with `{"agent_name": "…", "vendor": "…", "purpose": "…"}` → `onboard_url` (give it to the owner, valid 15 minutes) and `poll_code`. Poll `GET /v1/onboard/claim/{poll_code}` at most once every 5 seconds until `status` is `approved`, then `POST /v1/onboard/claim/{poll_code}` → `control_key` (`rgnt_agt_…`, shown once; store it) and `agent_id`. Go to step 2.
already hold a Regent credential or an invite code	`regent-control enroll <code>` for an invite; otherwise go to step 2.

Never ask for, accept or use an organization key (rgnt_… without agt). Yours is bound to you alone.

2. Ask Regent what comes next

Call my_budget and read stage and next:

over MCP: POST https://gw.regentprotocol.org/gw/mcp with Authorization: Bearer <your credential or OAuth token>, JSON-RPC tools/call, {"name": "my_budget", "arguments": {}} (send initialize first; its answer carries instructions for you);
over plain HTTP: GET https://api.regentprotocol.org/v1/agent/budget with the same bearer.

{
  "stage": "sandbox_ready",
  "next": {
    "action": "try_or_go_live",
    "tool": "pay",
    "say": "You gave me a budget in USD with about 30 left this month. Purchases here are test-only. Say what to buy to see how it works, or say 'go live' …"
  },
  "budgets": [ … ], "identity_verified": false, "card_linked": false,
  "verify_identity_url": "https://web.regentprotocol.org/kyc",
  "card_link_url": "https://web.regentprotocol.org/connect/gateway"
}

Say next.say to the owner, in the owner’s language, in one or two sentences. Then do next.tool. Call my_budget again whenever the owner asks what to do next, or after they tell you they finished a step. The stages, in the order an owner meets them:

`stage`	What it means	`next.tool`
`no_budget`	you have no budget yet	`request_budget`: ask for one (currency, limits, purpose); the owner signs it
`budget_pending`	your ask awaits the owner	`budget_request_status`: poll, at most once a minute
`sandbox_ready`	a budget in the sandbox: purchases are test-only, nothing real is charged	`pay` to try; or `verify_identity` when the owner wants real money
`verify_identity`	real money needs the owner verified once	`verify_identity`: gives the owner’s fixed Regent page; the real page asks for the passkey first
`link_card`	the owner is verified but has stored no card	`card_link`: gives the owner’s fixed Regent page to store a card (Agentcard); you never see the number
`ready`	budget, identity and card are in place	`pay`, or the shop tools below

Give the owner only the addresses these tools return. Never relay any other verification or card link, and never ask for card or document details in the chat.

3. Buy

A purchase is a tool call that the gate decides on before it runs. Every answer is one of three: allow (go), deny with a code (tell the owner, do not work around it), or escalate with ESCALATION_REQUIRED (the owner must approve: tell them, poll approval_status with the returned ref, then repeat the same call with the same idempotency_key). The first real purchase always escalates.

With the owner’s card at Agentcard (shops: Amazon, Walmart, Target, Best Buy; carts in USD):

{"name": "agentcard_shop", "arguments": {"method": "POST", "path": "buy",
  "body": {"ask": "one pack of AA batteries from Amazon, cheapest"}}}

→ conversation_id and carts[] with hash, store, totalCents, approvedCeilingCents. Agentcard may ask for a delivery name, address and phone: ask the owner and answer with further ask turns. Show the owner the store, the price and the ceiling (tax and shipping land at checkout; the final charge can only be lower). When they say yes:

{"name": "agentcard_buy", "arguments": {"method": "POST", "path": "buy",
  "body": {"conversation_id": "conv_…", "confirm": "<cart hash>"},
  "idempotency_key": "<one per purchase attempt>", "intent": "AA batteries"}}

Regent decides on the cart’s ceiling and the store it reads from Agentcard, not on what you send. After allow, Agentcard places the order (order_placed, order_id); it may also return an approval_url for the owner’s own device. Other rails (Stripe, a merchant’s HTTP API) are ordinary tools with the same three answers; my_budget lists what you may use.

4. Show the receipt

receipt with the decision_id returns the signed receipt and its public verify page: amount, store, who approved and how. No card, no address. Keep the decision_id with whatever you did. The owner can verify it without Regent: pip install regent-receipt-verify.

5. Three rules, always

You act only as yourself, with your own credential. Never an organization key.
You never grant yourself authority. You ask; a person approves.
On escalate you stop and tell the owner; you retry the same call with the same key after their decision. On AGENT_NOT_ACTIVE or MANDATE_SUSPENDED the owner revoked you: stop.

The full code table and the SDK form of every call: skill.md. The products behind this page: Tools MCP, Agentcard, Enrol an agent.

Which door is yours AgentID