UCP Product Discovery

中文摘要：UCP 的"发现"环节靠商家发布 Merchant Center 商品 feed + /.well-known/ucp profile，由 Google(AI Mode/Gemini)索引后把可购买商品呈现给 agent。核心 UCP 没有给 agent 调用的"目录搜索"REST 端点——发现是 feed/索引驱动的。

⚠️ Accuracy note / 准确性说明

An earlier draft of this repo modeled discovery as an agent calling a merchant catalog.search REST endpoint. That is not how core UCP works. The UCP technical spec defines capabilities for checkout (incl. cart management), fulfillment, discount, order, and common identity_linking — no standalone catalog/search/cart spec. Product discovery happens through the merchant's product feed (Merchant Center) which Google indexes for AI surfaces. 早期草稿把发现建模成 agent 调商家搜索接口,这是错的;实际靠商品 feed。

When to use / 何时使用

• A merchant wants their products eligible to appear in agentic shopping on Google.
• You're reasoning about the step before a checkout session: how the agent got item.ids.
• You're auditing whether a merchant's feed + UCP profile are discovery-ready.

UCP mapping / UCP 映射

Discovery is enabled by two published artifacts, not a callable capability:

1. Product feed — submitted via Merchant Center (title, price, availability, GTIN, etc.).

Google indexes it; agents on AI Mode / Gemini surface matching items to users.

1. UCP profile at /.well-known/ucp (public, no auth) — declares the merchant's

ucp.services["dev.ucp.shopping"] endpoint + ucp.capabilities, so once a user picks a product, the agent knows where to open a checkout session.

The product id a user lands on becomes line_items[].item.id in the checkout session.

Inputs & Outputs / 输入与输出

Merchant-side inputs: a complete product feed + a valid /.well-known/ucp profile.

What the agent actually receives (from Google's index, not a merchant API):

{ "item": { "id": "sku_8821", "title": "Trail Runner GTX", "price": 11900 },
  "merchant_profile": "https://merchant.example/.well-known/ucp" }

price is an integer in the currency's minor units (e.g. cents). 价格为最小货币单位整数。

Workflow / 工作流 (merchant enablement)

1. Publish the product feed in Merchant Center; keep availability and price fresh —

stale data fails at checkout, not discovery.

1. Serve `/.well-known/ucp` declaring ucp.version, ucp.services (transport rest,

endpoint, schema), and ucp.capabilities (e.g. dev.ucp.shopping.checkout).

1. Verify eligibility in Merchant Center; fix feed disapprovals.
2. Hand off: the discovered item.id seeds ucp-checkout-session.

Edge cases & failure modes / 边界与失败

• Treating discovery as a live API → it isn't; don't design an agent to "search the

merchant". Search/ranking is Google's; the merchant supplies data.

• Feed/profile mismatch → product indexed but profile lacks checkout capability → not buyable.
• Stale price/availability → discovery may show it; checkout re-validates and may reject.
• Region/currency → feed targeting controls where items are eligible.

Worked example / 示例

Merchant onboards "Trail Runner GTX".

1. Feed row: id=sku_8821, price=11900 USD, availability=in_stock, gtin=….
2. /.well-known/ucp declares dev.ucp.shopping REST endpoint https://merchant.example/ucp/v1.
3. User on Gemini asks for trail shoes → Google surfaces sku_8821 → agent opens a checkout

session at the declared endpoint with line_items:[{item:{id:"sku_8821"}, quantity:1}].

References / 参考

• UCP profile (/.well-known/ucp): https://developers.google.com/merchant/ucp/guides/ucp-profile
• UCP integration in Merchant Center: https://developers.google.com/merchant/ucp/guides/integration-ui/overview
• Next: ucp-checkout-session