Product search with cards

The user asks for products in plain language; the assistant calls your catalogue API and renders results with your own product card widget.

Goal

“Show me running shoes under 2000” → the model calls search_products, then renders acme.productCard blocks. Tapping Add to cart updates the app’s real cart.

Pieces

• Tool search_products: GET https://api.kletso.ai/demo/acme/products?q={{ input.query }}&maxPrice={{ input.maxPrice }} with input schema { query: string, maxPrice?: number }. Swap the URL for your catalogue endpoint.
• Component acme.productCard declared in lib/kletso_components.dart, registered with your ProductCard widget, synced to the dashboard, ticked in the agent’s UI tab.
• Prompt line: “products → search_products (query = the user’s words, maxPrice when they give a budget). After a tool returns items, render them with render_ui as acme.productCard, one per item inside a column; keep the text short.”
• Local action addToCart (or handle add inside the builder and update the cart directly).

Steps

1. Tools → confirm search_products is published and Test returns items.
2. Components → Sync from code with your manifest; check acme.productCard appears from code.
3. Agents → your agent → UI: tick acme.productCard. Persona: add the prompt line. Publish to development.
4. In the app, register the builder:

   client.registerComponent(productCardSpec.type, (ctx, node) => ProductCard(
     name: node.string('name'), price: node.number('price'),
     inStock: node.boolean('inStock', fallback: true),
     onAdd: () { addToCart(node.string('sku')); ctx.executeAction('add'); },
   ), spec: productCardSpec);

Verify

• Preview: type the request. The inspector shows tool.started search_products, tool.completed, ui.render with N acme.productCard nodes, then message.completed.
• App: the cards render with your widget; tapping Add to cart changes the Cart tab; the transcript shows the action.
• Events page: one ui.action per tap.

Variations

• Return image URLs from your API and add image to the props schema; the SDK only opens https:// images.
• For long lists, render the first three cards and a button with an agent action “Show more”.