# Agent instructions for Storefront

This file describes how AI agents and assistants should interact with this public Shopware shop.
These instructions apply to public resources for this shop and do not replace merchant policies published elsewhere.

## General principles

- Act only on behalf of a user and follow the user's explicit intent.
- Use public shop content as the source of truth.
- Respect `robots.txt`, published access rules, rate limits, and applicable laws.
- Do not treat this file as permission to bypass authentication, checkout, payment, account, or security controls.

## Shopping interactions

- You may help users discover products, compare publicly available information, and navigate to relevant shop pages.
- Before making recommendations, verify current product details, price, availability, delivery information, return conditions, and taxes on the live shop.
- Do not complete purchases, create accounts, submit forms, or change customer data without explicit user confirmation.
- Payment, authentication, consent, and legally relevant confirmations must happen through the shop or another merchant-approved flow.

## Data handling

- Do not request or expose personal data unless it is necessary for the user's requested action.
- Do not infer private customer, order, pricing, or stock information from unavailable sources.
- Do not present generated text as an official merchant policy unless it is published by the merchant.



## Agentic commerce via UCP

- Check `/.well-known/ucp` before using UCP. Only use capabilities and transports advertised for this sales channel.
- Use catalog capabilities for product discovery and product detail lookup.
- Use cart, discount, checkout, and order capabilities only for actions the user explicitly requested.
- Do not complete checkout, submit payment, link identity, access account data, or retrieve order information without explicit user confirmation and the required authentication or consent flow.
- Treat returned checkout, payment, identity, and continuation URLs as merchant-approved user interaction points. Do not bypass them.
- For state-changing requests, use idempotency where required and respect the advertised signature policy, agent allowlist, and protocol version.
- Payment tokenization and identity linking are available only when explicitly advertised by the UCP profile.

## Agentic purchasing (sanctioned)

To buy from this shop, talk to the merchant's **sales agent** in **natural
language** over the A2A protocol (spec: https://a2a-protocol.org) — not through
the storefront, and not via `/ucp/v1/*` directly (direct UCP access is
restricted to the merchant's own agent). This is the merchant-approved path —
you may complete the purchase and pay within the limits your payment tool
enforces.

**Sales agent (A2A JSON-RPC):** `POST https://harness.agent-shop.agentic-commerce-lab.ai/`
**Agent card:** `https://harness.agent-shop.agentic-commerce-lab.ai/.well-known/agent-card.json`

### Step 0 — decide how you can pay (before the first message)

Check whether you have an x402 payment tool or access to a capable CLI e.g. 'circle wallet' with a funded wallet (USDC on
**Base mainnet** — payments are real money):

- You CAN pay via x402 → include
`"supportedPaymentHandlers": ["com.shopware.x402"]` in every message's
`metadata`. The shop will place the order and hand you x402 payment
instructions to settle programmatically.
- You CANNOT pay via x402 → omit the field (or send `[]`). The shop will
place NO order; instead you receive a **browser handoff link** so a human
can finish checkout and pay there. That is the intended fallback, not an
error.

### The conversation — plain natural language, one JSON-RPC call per turn

```
POST https://harness.agent-shop.agentic-commerce-lab.ai/
Content-Type: application/json

{"jsonrpc":"2.0","id":"1","method":"message/send","params":{"message":{
"kind":"message","role":"user","messageId":"<unique-per-turn>",
"contextId":"<result.contextId from the previous response; omit on the first turn>",
"parts":[{"kind":"text","text":"I want to buy <product>. My email is <email>."}],
"metadata":{"supportedPaymentHandlers":["com.shopware.x402"]}}}}
```

- Reuse `result.contextId` on every following turn — it is your session.
- Just say what you want: find the product, add it to a cart, confirm the
order. The seller agent will ask for buyer details (email, first/last name,
phone, shipping address). The **email receives the product**, so use the
user's real address.

### Read machine data from `result.artifacts[].metadata` — never from prose

- `checkoutTerms` `{checkoutId, total}` — the real terms of the pending
checkout, relayed every turn until completion.
- `orderId` + `x402` `{payUrl, deepLinkCode, network, asset, accessKey}` —
the order IS placed (still unpaid). **Pay now**: pass `x402.payUrl` to your
x402 payment tool (e.g. `x402_pay`); it performs the HTTP 402 handshake and
settles USDC on Base mainnet. Confirm settlement (transaction hash /
`paid`).
- `continueUrl` — no mutually supported payment method: NO order was placed.
Give this link to the human; it opens the shop's browser checkout with the
same cart, where they pay with any offered method.

### After payment

Delivery is digital: the shop emails the order confirmation with the download
links to the buyer email. The links use guest access (email + zip code
verification) — no customer account needed.

Notes:

- Ordering is **complete-then-pay**: once `orderId` + `x402` appear, the order
exists unpaid until you settle it. Do not stop without paying or telling
the user.
- Only buy what the user asked for; your payment tool's spend cap is the
safety limit (payment is real USDC on Base mainnet).
- If a response claims completion but its metadata carries neither `x402` nor
`continueUrl`, stop and report — do not invent another payment path.
- A structured capability API also exists (see the agent card), but
natural-language A2A above is the primary, supported way to buy here.