| name | fuel-price |
| description | When a user asks for China Fuel Price by province or a recharge promo → return current/previous prices or promo result. |
China Fuel Price API – Provinces & promo (agent-ready)
When to use
- User wants current (or previous) fuel prices in China by province, or recharge promo math for a province.
- Triggers: phrases about fuel price / gasoline grade + province / Guangdong (or other province) price / recharge promo (any language).
- Do not call for non-China fuel data unless the API is extended.
- Do not overuse: unrelated intent → do not call.
Hard boundaries (must check before call)
- This module is China province fuel pricing only. If the target market is outside China, do not call it.
- Promo calculation requires explicit numbers (
amount, bonus); if missing, ask once and stop guessing.
Pre-check (before tool call)
- Confirm target market/province belongs to China coverage.
- Confirm required fields are complete for the chosen route (province, amount, bonus, optional fuelType).
Fallback (when not suitable)
- If user asks for non-China fuel prices, explain coverage limitation and avoid tool call.
- If promo parameters are incomplete, ask for missing numeric values once.
Retry policy
- Retry only for transient 5xx failures.
- Do not retry unchanged invalid params/path (400/404) until inputs are corrected.
Multi-turn / Missing parameters
- All provinces: no path params —
GET /api/fuel-price.
- Single province: need province path segment (format accepted by the API, often locale-specific or English). Parse first; if missing, ask once.
- Promo: need
province, amount, bonus; optional fuelType (b92|b95|b98|b0, default b92). If missing, ask — do not guess amounts.
Parameters
- Path
:province — province name for single-province and promo routes.
- Promo query:
fuelType (optional), amount (required), bonus (required).
Steps
- Conversation cache: Same full URL (path + query) already 200 in this conversation → reuse
data.
- Choose endpoint: all provinces vs one province vs promo; validate required params.
- Call the appropriate GET (see Request).
- Check HTTP status and response shape (JSON as returned by route).
- Extract
current / previous / latestUpdated or promo fields from payload.
- Format a short summary (prices per grade or promo outcome).
Request
All provinces:
GET /api/fuel-price
Single province:
GET /api/fuel-price/{province}
Example: GET /api/fuel-price/Beijing (or encoded/locale slug your deployment accepts)
Promo (recharge):
GET /api/fuel-price/{province}/promo?fuelType=b92&amount=500&bonus=50
Response
JSON with current / previous arrays of province rows (b92, b95, b98, b0, etc.) and timestamps; promo route returns shape defined by implementation — read live data for edge fields.
Say to the user (one line)
- Quote relevant grades and province; for promo, state computed benefit in plain language.
Output language
- Use user’s language for explanations; keep numeric and API field names as returned where helpful.
Idempotency & cache (conversation)
- Reuse identical GET results in the same conversation.
Examples
- User: “Today’s fuel price in Beijing” →
GET /api/fuel-price/Beijing (or matching slug) → summarize current.
- User: “Fuel prices nationwide” →
GET /api/fuel-price.
- User: “DNS lookup example.com” → Do not call this API.
Agent rules
GET only for these paths; follow Steps.
Error handling (HTTP)
- 400 / 404 (if used): fix province or query params; do not retry same bad URL.
- 5xx: suggest retry later.
