{"version":"1.1","spec":"Trusteed Agent Policy Playbooks","canonical_url":"https://trusteed.xyz/.well-known/agent-playbooks.json","canonical_scope":"Ready-to-use agent policy playbooks with ALLOW/FRICTION/REVIEW_REQUIRED/BLOCK rules. For trust framework see agent-trust-manifest.json. For full agent policies see agent-policy.json.","published_at":"2026-04-12","generated_at":"2026-08-19T00:00:00.000Z","description":"Ready-to-use policy rule sets for builders integrating shopping agents. Each playbook defines when to ALLOW autonomous action, apply FRICTION (confirm with user), or require REVIEW. Copy-paste and adjust thresholds to your use case.","action_types":{"ALLOW":"Agent proceeds autonomously. No user confirmation needed.","FRICTION":"Agent must present the action to the user and wait for confirmation.","REVIEW_REQUIRED":"Agent must pause and route to human review before any action.","BLOCK":"Agent must not proceed. Inform user and suggest alternatives."},"playbooks":[{"id":"conservative-shopper","name":"Conservative Personal Shopper","description":"High-trust, low-autonomy. Suitable for agents buying on behalf of users who want full control. Only allows autonomous action for very small amounts from verified merchants.","rules":[{"id":"allow-micro-purchase","action":"ALLOW","description":"Autonomous purchase for micro-transactions from verified merchants with fresh data","conditions":{"price_max_usd":25,"trust_score_min":0.8,"verification_levels":["STANDARD","VERIFIED"],"freshness_tiers":["fresh","recent"],"stock_confidence":["high"]}},{"id":"friction-small-purchase","action":"FRICTION","description":"Ask user before any purchase above micro threshold","conditions":{"price_range_usd":[25,500],"trust_score_min":0.5},"friction_prompt":"I found {{product.title}} for {{product.price}} {{product.currency}} at {{merchant.name}} (trust: {{merchant.trust_score}}, {{merchant.verification_level}}). Ranked: {{product.why_ranked}}. Shall I add it to your cart?"},{"id":"review-high-value","action":"REVIEW_REQUIRED","description":"Human review required for any high-value transaction","conditions":{"price_min_usd":500}},{"id":"block-untrusted","action":"BLOCK","description":"Never purchase from low-trust or suspended merchants","conditions":{"trust_score_max":0.3},"block_message":"Merchant {{merchant.name}} does not meet minimum trust requirements (score: {{merchant.trust_score}}). I recommend choosing a different merchant."}]},{"id":"balanced-shopper","name":"Balanced Personal Shopper","description":"Balanced autonomy. Allows autonomous purchase up to 100 USD from trusted merchants. Good default for most personal shopping agents.","rules":[{"id":"allow-standard-purchase","action":"ALLOW","description":"Autonomous purchase for standard amounts from trusted merchants","conditions":{"price_max_usd":100,"trust_score_min":0.7,"verification_levels":["STANDARD","VERIFIED"],"freshness_tiers":["fresh","recent","stale"],"price_confidence":["high","medium"]}},{"id":"friction-medium-purchase","action":"FRICTION","description":"Ask user for items above 100 USD or from deprioritized merchants","conditions":{"any_of":[{"price_range_usd":[100,300]},{"trust_score_range":[0.4,0.69]}]},"friction_prompt":"Before I proceed: {{product.title}} at {{product.price}} {{product.currency}} from {{merchant.name}}. Trust score: {{merchant.trust_score}}. Return window: {{merchant.return_window_days}} days. Confirm?"},{"id":"review-premium","action":"REVIEW_REQUIRED","description":"Human confirmation required for premium purchases","conditions":{"price_min_usd":300}},{"id":"block-low-trust","action":"BLOCK","conditions":{"trust_score_max":0.3}}]},{"id":"deal-hunter","name":"Deal Hunter (Discount-Optimized)","description":"Optimized for finding the best deals. Higher autonomy for discounted products from verified merchants. Prioritizes compareAtPrice discounts.","rules":[{"id":"allow-discounted-product","action":"ALLOW","description":"Autonomous purchase when discount >= 20% and merchant is trusted","conditions":{"discount_percent_min":20,"price_max_usd":150,"trust_score_min":0.65,"stock_confidence":["high","medium"]}},{"id":"friction-non-discounted","action":"FRICTION","description":"Confirm with user for full-price items","conditions":{"discount_percent_max":19},"friction_prompt":"This item ({{product.title}}, {{product.price}} {{product.currency}}) is not currently discounted. Still want to add it to cart?"},{"id":"review-large-discount-high-value","action":"REVIEW_REQUIRED","description":"Review unusually large discounts on high-value items — may indicate pricing error","conditions":{"discount_percent_min":60,"price_min_usd":200},"review_reason":"Large discount on high-value item. Verify this is intentional before purchasing."},{"id":"block-low-trust","action":"BLOCK","conditions":{"trust_score_max":0.3}}]},{"id":"fast-checkout","name":"Fast Checkout (Speed-Optimized)","description":"Maximum autonomy within safety guardrails. For agents where user has pre-authorized purchases up to a high limit. Requires verified merchants only.","rules":[{"id":"allow-pre-authorized","action":"ALLOW","description":"Autonomous purchase up to pre-authorized limit for verified merchants","conditions":{"price_max_usd":200,"trust_score_min":0.6,"verification_levels":["STANDARD","VERIFIED"]}},{"id":"friction-above-limit","action":"FRICTION","conditions":{"price_min_usd":201},"friction_prompt":"Purchase of {{product.title}} ({{product.price}} {{product.currency}}) exceeds your pre-authorized limit. Approve this one-time?"},{"id":"block-unverified","action":"BLOCK","description":"Never purchase from unverified merchants regardless of price","conditions":{"verification_levels":["NONE","BASIC"]},"block_message":"Merchant {{merchant.name}} is not verified (level: {{merchant.verification_level}}). I require at least STANDARD verification for autonomous purchases."},{"id":"block-low-trust","action":"BLOCK","conditions":{"trust_score_max":0.3}}]},{"id":"buy-shoes-vertical","name":"Fashion / Footwear Vertical Buyer","description":"Step-by-step workflow for an agent buying shoes or fashion items. Covers size variant selection, stock confirmation, trust check, and checkout — with friction for size-sensitive decisions.","workflow_steps":[{"step":1,"action":"discover","tool":"search_products","params":{"query":"{{user.query}}","category":"footwear","limit":10},"agent_note":"Filter results: trust_score >= 0.65, stock_status in [in_stock, low_stock]."},{"step":2,"action":"detail","tool":"get_product_details","params":{"product_id":"{{top_result.id}}"},"agent_note":"Retrieve variants array. Confirm size availability. If no size match → go back to step 1 with next candidate."},{"step":3,"action":"trust_check","tool":"get_merchant_profile","params":{"slug":"{{product.store_slug}}"},"agent_note":"Assert trust_score >= 0.65 and verification_level in [STANDARD, VERIFIED]. Check return_window_days >= 14 for wearables."},{"step":4,"action":"friction","description":"Present to user before adding to cart","friction_prompt":"I found {{product.title}} in size {{selected_variant.size}} for {{product.price}} {{product.currency}} at {{merchant.name}} (trust: {{merchant.trust_score}}). Return window: {{merchant.return_window_days}} days. Add to cart?"},{"step":5,"action":"cart","tool":"create_cart","params":{"product_id":"{{product.id}}","variant_id":"{{selected_variant.id}}","quantity":1}},{"step":6,"action":"checkout","tool":"complete_checkout","agent_note":"Always use URL elicitation — never attempt headless payment for fashion items."}],"rules":[{"id":"allow-known-size","action":"ALLOW","description":"Autonomous add-to-cart when size is confirmed in-stock and trust is high","conditions":{"stock_status":["in_stock"],"trust_score_min":0.75,"verification_levels":["STANDARD","VERIFIED"],"variant_confirmed":true}},{"id":"friction-low-stock-size","action":"FRICTION","description":"Confirm with user when last size available or low_stock","conditions":{"stock_status":["low_stock"]},"friction_prompt":"Only {{variant.stock_quantity}} left in size {{variant.size}}. Proceed?"},{"id":"block-out-of-stock","action":"BLOCK","conditions":{"stock_status":["out_of_stock"]},"block_message":"Size {{selected_variant.size}} is out of stock. I recommend choosing a different size or merchant."}]},{"id":"merchant-trust-verification","name":"Merchant Trust Verification Workflow","description":"Step-by-step workflow for an agent to verify a merchant before transacting. Use this before any checkout when the merchant is unknown or trust data is stale.","workflow_steps":[{"step":1,"action":"profile","tool":"get_merchant_profile","params":{"slug":"{{merchant.slug}}"},"agent_note":"Retrieve trust_score, verification_level, freshness_tier, protocols supported."},{"step":2,"action":"evaluate","description":"Apply trust gates","gates":[{"field":"trust_score","operator":">=","value":0.3,"on_fail":"BLOCK"},{"field":"verification_level","operator":"in","value":["BASIC","STANDARD","VERIFIED"],"on_fail":"REVIEW_REQUIRED"},{"field":"freshness_tier","operator":"in","value":["fresh","recent"],"on_fail":"FRICTION"}],"agent_note":"All gates must pass before proceeding to cart. If any BLOCK gate fails, do not add to cart."},{"step":3,"action":"methodology_check","endpoint":"GET /api/v1/trust/methodology","agent_note":"Optional: retrieve methodology to explain score to user if trust_score is between 0.3 and 0.69."},{"step":4,"action":"present_verification","description":"If friction gate triggered, present trust summary to user","friction_prompt":"Merchant {{merchant.name}} — Trust score: {{merchant.trust_score}} ({{trust_label}}), Verification: {{merchant.verification_level}}, Data freshness: {{merchant.freshness_tier}}. Do you want to proceed?"}],"rules":[{"id":"allow-verified-fresh","action":"ALLOW","conditions":{"trust_score_min":0.7,"verification_levels":["STANDARD","VERIFIED"],"freshness_tiers":["fresh"]}},{"id":"friction-stale-or-caution","action":"FRICTION","conditions":{"any_of":[{"freshness_tiers":["stale"]},{"trust_score_range":[0.3,0.69]}]},"friction_prompt":"Merchant data may be outdated or trust score is below preferred threshold. Proceed with caution?"},{"id":"review-unverified","action":"REVIEW_REQUIRED","conditions":{"verification_levels":["NONE"]}},{"id":"block-low-trust","action":"BLOCK","conditions":{"trust_score_max":0.29},"block_message":"Merchant {{merchant.name}} does not meet minimum trust threshold (0.30). Transaction blocked."}]},{"id":"safe-checkout-retry","name":"Safe Checkout Retry","description":"Workflow for handling checkout failures, network errors, and idempotent retries. Prevents duplicate orders and ensures agents recover gracefully without re-charging users.","workflow_steps":[{"step":1,"action":"attempt_checkout","tool":"complete_checkout","params":{"cart_id":"{{cart.id}}","idempotency_key":"{{generate_ulid()}}"},"agent_note":"Always generate a fresh ULID idempotency_key per checkout attempt. Store it before sending."},{"step":2,"action":"on_success","description":"HTTP 200 → persist order_id. Confirm to user. Do not retry."},{"step":3,"action":"on_4xx","description":"HTTP 4xx (client error) → do NOT retry automatically.","cases":[{"status":400,"action":"BLOCK","reason":"Invalid cart. Present error to user."},{"status":402,"action":"FRICTION","reason":"Payment required signal — present payment options to user."},{"status":409,"action":"FRICTION","reason":"Conflict — may be duplicate. Check order status via get_orders before retrying."},{"status":429,"action":"FRICTION","reason":"Rate limited. Wait backoff_seconds from response header. Present delay to user."}]},{"step":4,"action":"on_5xx_or_network","description":"HTTP 5xx or network timeout → idempotent retry with same idempotency_key.","retry_policy":{"max_attempts":3,"backoff_seconds":[2,5,15],"on_exhausted":"REVIEW_REQUIRED"},"agent_note":"Reuse the SAME idempotency_key from step 1 on all retries. This prevents duplicate charges."},{"step":5,"action":"verify_idempotency","description":"Before retry, check if order was created despite error","tool":"get_orders","params":{"reference_id":"{{idempotency_key}}"},"agent_note":"If order found → treat as success. Do not issue a second checkout."}],"rules":[{"id":"allow-first-attempt","action":"ALLOW","description":"First checkout attempt always proceeds if cart is valid and trust gates pass","conditions":{"attempt_number":1,"trust_score_min":0.5}},{"id":"friction-retry","action":"FRICTION","description":"Confirm with user before any retry attempt","conditions":{"attempt_number_min":2},"friction_prompt":"Checkout attempt {{attempt_number}} failed ({{last_error}}). Retry?"},{"id":"review-exhausted","action":"REVIEW_REQUIRED","description":"After max retries, route to human review","conditions":{"attempt_number_min":4},"review_reason":"Checkout failed after {{max_attempts}} attempts. Manual review required."}]}],"template_variables":{"{{product.title}}":"Product title from search/detail response","{{product.price}}":"Numeric price","{{product.currency}}":"ISO 4217 currency code","{{product.why_ranked}}":"Human-readable ranking explanation (e.g. 'title match · trust 0.82 · in stock · fresh data')","{{merchant.name}}":"Store display name","{{merchant.trust_score}}":"Numeric trust score 0.0–1.0","{{merchant.verification_level}}":"NONE | BASIC | STANDARD | VERIFIED","{{merchant.return_window_days}}":"Return window in days from merchant profile"},"related_documents":{"agent_policy":"/.well-known/agent-policy.json","agent_commerce":"/.well-known/agent-commerce.json","trust_manifest":"/.well-known/agent-trust-manifest.json","agent_pay":"/.well-known/agent-pay.json","agent_failsafe":"/.well-known/agent-failsafe.json","merchant_index":"/.well-known/merchant-index.json","mcp_server_card":"/.well-known/mcp.json","mcp_manifest":"/mcp.json","llms_txt":"/llms.txt"}}