← All Articles

UCP Catalog Capabilities: Product Discovery for AI Agents

PR #55 adds Catalog Search and Catalog Lookup operations — agents can now discover products directly through the protocol, completing the end-to-end commerce loop.

Why This Matters

Until now, UCP has focused on the transaction side of commerce: carts, checkout, payments, and order management. But there was a gap — how does an agent find products in the first place? The answer was typically "use a search API separately" or "scrape the website," neither of which integrates cleanly with the structured UCP flow.

PR #55 closes this gap by adding two new capabilities to the protocol:

• Catalog Search — Query a business's product catalog with natural language or structured filters
• Catalog Lookup — Retrieve detailed product information by identifier

This is significant because it means an AI agent can now handle the complete purchase journey — from "I need running shoes under $150" through to order confirmation — entirely within UCP.

What Changed Technically

The PR introduces a new catalog capability with two operations:

Catalog Search

{
  "operation": "catalog/search",
  "query": {
    "text": "wireless noise-canceling headphones",
    "filters": {
      "price_max": 300,
      "in_stock": true,
      "category": "electronics/audio"
    },
    "sort": "relevance",
    "limit": 20
  }
}

The search operation supports both free-text queries and structured filters. Businesses can advertise which filter fields they support in their capability declaration, allowing agents to adapt their queries accordingly.

Catalog Lookup

{
  "operation": "catalog/lookup",
  "identifiers": [
    { "type": "sku", "value": "HDPH-NC-500" },
    { "type": "gtin", "value": "0123456789012" }
  ],
  "include": ["pricing", "availability", "variants", "media"]
}

Lookup retrieves detailed product information, with optional include fields to control response size. This is useful when an agent needs to refresh pricing before checkout or present detailed options to a user.

Pagination and Cursors

For large result sets, the search operation supports cursor-based pagination:

{
  "results": [...],
  "cursor": "eyJvZmZzZXQiOjIwfQ==",
  "has_more": true,
  "total_estimate": 150
}

Agents can pass the cursor in subsequent requests to retrieve additional pages. The total_estimate field is intentionally approximate — businesses aren't required to provide exact counts, which allows for more efficient implementation.

Integration with Version Negotiation

This capability builds on the version negotiation overhaul from PR #200 (merged yesterday). Businesses can declare catalog support in their service definition:

{
  "capabilities": {
    "catalog": {
      "version": "1.0",
      "operations": ["search", "lookup"],
      "search_filters": ["category", "price_min", "price_max", "in_stock", "brand"]
    }
  }
}

The combination of declarative capabilities and the requires constraint system means agents can discover what a business supports before making requests, reducing error handling complexity.

Why Not Just Use Existing Search APIs?

Fair question. Many businesses already have search APIs, and there are aggregators like Google Shopping that provide product discovery. Three reasons why native UCP catalog capabilities matter:

1. Session continuity — Product identifiers returned from catalog operations are guaranteed to work with cart/checkout operations in the same session. External APIs require additional mapping.
2. Unified authentication — The same auth context that allows checkout also authorizes catalog access. No separate API key management.
3. Structured agent interaction — Agents can declaratively understand what filtering is supported rather than guessing or falling back to unstructured search.

Implementation Considerations

For businesses implementing catalog capabilities:

• Search backends vary — The spec is intentionally flexible about ranking algorithms. A business can use Elasticsearch, Algolia, their own ML-based ranking, or simple database queries.
• Start with lookup — If full search is complex, implement lookup first. Agents can use external discovery and then lookup via UCP for the transaction.
• Filter advertising matters — Declare which filters you support so agents can construct valid queries without trial and error.

What's Next

With catalog capabilities in place, several follow-on features become possible:

• Recommendations — "Related products" and "customers also bought" as catalog operations
• Inventory holds — Reserve items during cart session to prevent overselling
• Price alerts — Subscribe to price changes via the emerging A2A pub/sub patterns

The full PR is available at Universal-Commerce-Protocol/ucp#55.