Skip to navigation
Advanced Usages

Predefined Card Schemas

The four predefined card_kind values plus example payloads.

carousel — selectable items list

{
  "title": "Choose a flight",
  "subtitle": "London → Edinburgh, 2026-06-25",
  "items": [
    {
      "id": "off_123",
      "image": "https://example.com/ba.png",
      "title": "British Airways",
      "subtitle": "Direct · 1h 15m · Economy",
      "badges": [{"label": "Direct", "variant": "info"}],
      "secondary_text": "USD 88.16",
      "primary_cta": {
        "label": "Select",
        "selection": {"offer_id": "off_123"}
      }
    }
  ]
}

Selection shape: whatever you put in primary_cta.selection.

detail — detail view with sub-options + CTAs

{
  "title": "British Airways · LHR → EDI",
  "hero_image": "https://example.com/hero.png",
  "summary_rows": [
    {"label": "Departure", "value": "21:50 · LHR"},
    {"label": "Arrival", "value": "23:05 · EDI"}
  ],
  "sub_options": {
    "name": "cabin",
    "kind": "radio",
    "label": "Cabin class",
    "choices": [
      {"value": "economy", "label": "Economy", "secondary_text": "USD 88"},
      {"value": "business", "label": "Business", "secondary_text": "USD 220"}
    ]
  },
  "ctas": [
    {"label": "Continue", "selection": {"action": "continue"}, "primary": true},
    {"label": "Back", "selection": {"action": "back"}}
  ]
}

Selection shape: {cabin: "economy", action: "continue"} (sub-option value merged with CTA selection).

form — labeled inputs with submit

{
  "title": "Passenger details",
  "fields": [
    {"name": "first_name", "kind": "text", "label": "First name", "required": true},
    {"name": "email", "kind": "email", "label": "Email", "required": true},
    {
      "name": "country",
      "kind": "select",
      "label": "Country",
      "options": [{"value": "GB", "label": "United Kingdom"}]
    }
  ],
  "submit_cta": {"label": "Continue", "selection": {"action": "submit"}}
}

Field kinds: text, number, email, select, checkbox. select requires non-empty options.

Selection shape: {first_name: ..., email: ..., country: ..., action: "submit"}.

review — key-value review with confirm/reject

{
  "title": "Confirm booking",
  "summary_rows": [
    {"label": "Flight", "value": "BA1437"},
    {"label": "Total", "value": "USD 88.16"}
  ],
  "approve_cta": {"label": "Confirm booking", "selection": {"action": "confirm"}, "primary": true},
  "reject_cta": {"label": "Cancel", "selection": {"action": "cancel"}}
}

Selection shape: approve_cta.selection or reject_cta.selection depending on which the user clicked. The planner’s natural-language forward to your agent will mention confirm vs. cancel (or whatever you put in the CTA selection) and convey the user’s approve/reject intent in prose.