Requests
What an agent sends, what comes back, and the one field it may act on.
A request is one question from an agent: may I do this? It is answered once, and the answer never changes.
What the agent sends
- agent
- The agent's name, the same every time, 1 to 200 characters.
- action
- A short machine-friendly name such as email.send. Rules match on it.
- summary
- One plain sentence for the person deciding, up to 2,000 characters.
- details
- Optional. A JSON object with supporting facts: the message text, the code change, the items. See How details are shown.
- amount
- Optional. The money the action would move, as a number or a string such as "129.00", with at most 4 decimals. Rules with a limit go by it. Needs currency.
- currency
- Optional. The three-letter code of the amount, such as EUR.
- wait_seconds
- Optional. Wait up to this many seconds (0 to 30) for a decision, and answer as soon as it is made.
- ttl_seconds
- Optional. How long to wait, 10 seconds to 7 days. Default 15 minutes.
What comes back
- id
- The request's id, to read the answer with later.
- status
- pending, approved, denied, expired or withdrawn.
- allowed
- The only field an agent should act on. True only after an approval, and never while the workspace or the agent's key is paused.
- amount, currency
- The amount the request stated, when it stated one.
- approved_summary, approved_amount
- Once approved, what the agent may do: the wording to act on, and the most money it may move, in currency. Act on these, never on summary and amount.
- changed
- True when the person approved a narrower version than the agent asked: new wording, a lower amount, or both.
- paused, pause
- paused is true while a person has paused the workspace or this agent's key; pause then says which, workspace or agent.
- key_name
- The name of the key the request was made with, as an owner wrote it.
- decided_by
- Email of the person who decided, or who wrote the rule that did.
- by_rule
- True when a standing rule made the decision.
- approvals_needed, approvals
- How many different people must approve, and who has so far. One denial is enough to stop it.
- decision_note
- The reason, if the person gave one.
- expires_at
- When the request stops accepting a decision.
- outcome, outcome_note
- How the approved action went, once the agent reported it: succeeded or failed.
The one rule
Only allowed: true means go. Everything else means stop.
- A decision is final. Nobody can turn an approval into a denial.
- A request nobody answers in time expires and can no longer be approved.
- An agent key can ask, and read, withdraw or report on its own requests. It cannot see another key’s requests, list the inbox, decide, or change any setting.
- An agent in one workspace can never see a request from another.
Approved with changes
The person deciding can change what is approved before approving it: reword the summary, or lower the amount. The agent may then do only the changed version. The answer has changed: true, and approved_summary and approved_amount hold what was approved, while summary and amount keep what was asked, for the record.
- A change only ever narrows. The amount can go down or stay the same, in the same currency. It can never go up, and a request that stated no amount cannot be given one.
- Only an approval can carry changes, not a denial.
- Changes apply to that one request, so they cannot be remembered as a rule.
- When a request needs several people, everyone approves the same changes. An approval with different changes, or none after the first made some, is refused and not counted: approve the same version, or deny it.
- A budget counts what was approved, so a lowered amount uses up only the lower amount.
An agent that can only do what it asked must not act on a changed approval. The TypeScript guard does nothing in that case unless told it can, variantgate run does not run its command, and the hooks deny the tool call.
Waiting for the answer
Pass wait_seconds when asking or reading, and the call stays open until a person decides or the time is up, for at most 30 seconds. One call usually brings the answer, and none of the waiting counts against the rate limit.
curl 'https://api.variantgate.com/v1/requests/REQUEST_ID?wait_seconds=30' \
-H 'authorization: Bearer gl_YOUR_KEY'Taking a request back
If the plan changes before anyone decides, the agent withdraws the request. It leaves the inbox, nobody can approve it any more, and the record shows it was withdrawn.
curl -X POST https://api.variantgate.com/v1/requests/REQUEST_ID/withdraw \
-H 'authorization: Bearer gl_YOUR_KEY'Saying how it went
An approval says an action may happen. After acting, the agent reports whether it did, once, with a short note such as a message id or an error. The record then shows both: who allowed it, and what came of it.
curl -X POST https://api.variantgate.com/v1/requests/REQUEST_ID/outcome \
-H 'authorization: Bearer gl_YOUR_KEY' \
-H 'content-type: application/json' \
-d '{ "outcome": "succeeded", "note": "Sent as message 4411" }'Only the key that asked can withdraw a request or report its outcome.
Two names
An agent picks its own name, so agent can say anything. The key it asked with has a name too, written by an owner, and the agent cannot change that one. When the two differ, the inbox and the record show both, and rules always go by the key.
Finding a request
Above the inbox, one row narrows the list: by agent key, by action (email.send, or email.* for a family), and by an amount it must be above, in whatever currency each request states. The record has the same row, with a search box. Both keep what you chose in the address, so a filtered view can be bookmarked or shared.
Keyboard shortcuts
The inbox can be worked without a mouse. Press ? to see every shortcut. None of them fire while you type in a field, or with Ctrl, Cmd or Alt held.
- j and k
- Move to the next or the previous request.
- Enter
- Open the selected request on its own.
- a
- Approve, exactly as the Approve button does.
- d
- Deny.
- e
- Edit the request, then approve the changed version.
- /
- Go to the search box, or the filters in the inbox.
- g, then a letter
- Go to a section: i for the inbox, n insights, r the record, u rules, a agents, p people, s settings.
A shortcut presses the same button a click would. A request that needs two people still waits for the second, and a request a rule sends to someone else still cannot be decided by anyone but them and the owners.
Writing a good summary
The person deciding reads the summary first, often on a phone. Say exactly what will happen, with the amount, the recipient or the number of things affected.
- Weak
- Send email
- Strong
- Send the March invoice (€1,240.00) to billing@acme.example
- Weak
- Clean up files
- Strong
- Delete 214 files in /exports/2024, 1.8 GB in total
How details are shown
The inbox shows details as the agent sent them, so the person deciding reads exactly what they approve. Everything is shown as text: HTML and markdown in a value are never interpreted.
- Text keeps its line breaks and spacing. Text longer than about eight lines starts collapsed, with a button to show all of it.
- A field whose name says it holds code, such as
sql,query,command,script,jsonoryaml, also with words around it as inraw_sql, is set in a fixed-width font. - Text in unified diff format, as
git diffwrites it, is shown as a diff: added lines green with their+, removed lines red with their-. httpandhttpsaddresses become links that read as the whole address. Nothing else is linked.- An object is shown indented under its name. A list of plain values is a list; a list of objects with the same few keys (up to five) is a table, and other lists are numbered.
- Past four levels the rest is shown as JSON. A list longer than 50 shows the first 50, says how many more there are, and shows them on a click.
Tips for agents
- Put the text of a message in a field such as
body, whole, not a description of it. - Put a code change in
diffas a unified diff, SQL insql, and a shell command incommand. - Send items, such as order lines or files, as a list of objects with the same keys.
- Details share the request’s 64 KB limit. For something larger, send the first part and say how much is left out.
{
"details": {
"body": "Hi Ana,\n\nSorry the lamp arrived broken. We have refunded €129.00 to your card; it shows within 5 days.\n\nYour order: https://shop.example/orders/4471\n\nBest,\nNorthwind support",
"lines": [
{
"item": "Desk lamp",
"price": "109.00",
"qty": 1
},
{
"item": "Bulb, warm",
"price": "10.00",
"qty": 2
}
],
"order": "4471",
"to": "ana@customer.example"
}
}support-agent
refund.create · asked just now
Refund Ana €129.00 for order 4471 and email her
€129.00as stated by the agent
- body
Hi Ana, Sorry the lamp arrived broken. We have refunded €129.00 to your card; it shows within 5 days. Your order: https://shop.example/orders/4471 (opens in a new tab) Best, Northwind support
- lines
item price qty Desk lamp 109.00 1 Bulb, warm 10.00 2 - order
4471
- to
ana@customer.example