Core 3/4: Quote with live price, stock and the mandate check
request_quoteGenerate a signed, expiring quote with live prices and availability from Valio Aimo, including mandate checks and alternatives, without placing an order.
Instructions
Get a signed, expiring quote with live prices and availability from Valio Aimo. Places no order.
delivery_date: YYYY-MM-DD.
items: one per need: {product_ids: [...], amount, unit: 'L' | 'KG' | 'SALES_UNIT', substitute_for?, use?}
(use: what the product is for, e.g. 'coffee', 'dessert', 'ingredient-in-recipe:Tiramisu'; a substitute that
doesn't suit it, like another brand of whipping cream for a dessert, waits for a person)
(pack, packs mean SALES_UNIT = cartons/packs as sold; 'ST' (PCS, KPL) counts pieces when the product has
them: 20 ST of a carton of 6 = 4 cartons, rounded up, and the line says so in unit_note).
Give several candidate ids per need and an amount in L or KG: the gateway picks the cheapest orderable
one per L/KG, splitting across products when stock is short. Mark substitutes with substitute_for.
Always pass mandate_id: the quote then includes mandate_preview (silent | notify | ask | block, and why).
Check quote.lines[].orderable, quote.uncovered and mandate_preview, then place_order with quote.id
before quote.expires_at.
If quote.options is present, an item can't be covered as asked (stock short, later date, cut-off passed,
undeliverable). Each option is a complete alternative for that item (kind, lines, total, delivery_dates,
tradeoff, substitute, mandate_preview), best first. Present them to the buyer, or pick per the mandate
(an option whose mandate_preview is silent/notify needs no human). Never silently drop the uncovered amount.
option_id: to take an option, call request_quote again with only agent_id, mandate_id and option_id
(e.g. 'Q-1A2B3C4D.O2'): you get a fresh signed quote with that item's lines replaced; then place_order it.
rationale: one sentence on the buyer's business need (e.g. "breakfast milk for 400 guests"); it is signed into
the quote and shown to the humans who audit or approve. State the need, not your reasoning steps.
declared_risks: optional, up to 5 short sentences (200 chars each) on what YOU are unsure about (e.g. "not sure
10 L covers Saturday"). Each one holds the order for a human (rule agent.declared_risk) with your words; it
can never make an order go through more easily. Say it here rather than ordering on a guess.
buyer_request: the buyer's own message to you, verbatim (at most 2,000 characters), not your summary. Signed
into the quote; the gateway reads its quantities ("1 539 litraa" = 1,539 L) and, when the quote has none of
them, asks a person (rule quantity.request_mismatch). mandate_preview.request_quantities shows what it read.
offer_id: a Valio Aimo offer from list_offers (e.g. 'OF-1A2B3C4D'), only when the buyer wants it: name the
offer's product_ids in items; they are priced at min(offer price, live price) and the quote carries offer.
The mandate decides as always (rule offer.applied tells the buyer).
agent_id: optional when your credential covers mandate_id (see my_mandates); required without a mandate.
agent_token: only if you can't send the Authorization: Bearer header and the mandate requires agent auth.
Returns {quote (schema /schemas/quote.json), jws (sous-quote+jws over quote)}.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "request_quote"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | ||
| agent_id | No | ||
| offer_id | No | ||
| option_id | No | ||
| rationale | No | ||
| mandate_id | No | ||
| agent_token | No | ||
| buyer_request | No | ||
| delivery_date | No | ||
| declared_risks | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jws | Yes | Compact JWS over `quote`, verifiable with /.well-known/jwks.json | |
| quote | Yes |