Widget quickstart

{
  "metadata": { "name": "Travel concierge", "externalId": "travel-concierge" },
  "spec": {
    "description": "Plans trips with questions, the traveler's home airport, and destination cards",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_RANDOM"
  }
}

{
  "metadata": { "name": "Travel concierge", "externalId": "travel-concierge-v1" },
  "spec": {
    "systemPromptTemplate": "You are a friendly travel concierge. Before you suggest anything, call cdy_widget_get_page_context to learn the traveler's home airport, so your ideas make sense from where they start. When you need preferences, such as budget, season, or pace, ask with cdy_widget_ask_user instead of in prose. Show each destination with cdy_widget_display_details: put the flight time, best season, and rough budget in fields. You plan trips. You don't book them."
  }
}

CADENYA_API_KEY=your-api-key
CADENYA_WORKSPACE_ID=your-workspace-id
CADENYA_WIDGET_ID=external_id:travel-concierge

import Cadenya from "@cadenya/cadenya";

export const runtime = "nodejs"; // The server SDK needs Node, not the Edge runtime.
export const dynamic = "force-dynamic"; // Never cache a minted token.

// Module scope lets every request reuse one client.
const client = new Cadenya();

export async function POST() {
  const session = await client.widgetSessions.create({
    spec: {
      widgetId: process.env.CADENYA_WIDGET_ID!,
      // Every session names a tenant and a subject, and sessions with the same
      // pair share conversation history. Swap in your signed-in user's IDs.
      tenant: { id: "travel-concierge", name: "Travel concierge" },
      subject: { id: "quickstart-traveler" },
    },
  });

  if (!session.info?.host) {
    return Response.json({ error: "The Widget Session came back without a host" }, { status: 502 });
  }

  return Response.json(
    { token: session.spec.token, host: session.info.host },
    { headers: { "Cache-Control": "no-store" } },
  );
}

"use client";

import "@radix-ui/themes/styles.css";
import "@cadenya/widgets-ui-react/styles.css";
import { useCallback, useEffect, useState } from "react";
import { Theme } from "@radix-ui/themes";
import { CadenyaWidgetProvider, ConversationsPanel } from "@cadenya/widgets-ui-react";

type Session = { token: string; host: string };

async function mintSession(): Promise<Session> {
  const response = await fetch("/api/session", { method: "POST" });
  if (!response.ok) throw new Error("Could not start a Widget Session");
  return response.json();
}

export function Concierge() {
  const [session, setSession] = useState<Session | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    mintSession().then(setSession, (err: Error) => setError(err.message));
  }, []);

  // Tokens last about 15 minutes. On a 401, the provider calls this and
  // retries the request once with the new token.
  const getToken = useCallback(async () => (await mintSession()).token, []);

  if (error) return <p role="alert">{error}</p>;
  if (!session) return <p>Packing your bags…</p>;

  return (
    <Theme accentColor="teal" grayColor="slate" radius="large">
      <CadenyaWidgetProvider host={session.host} token={session.token} getToken={getToken}>
        <ConversationsPanel />
      </CadenyaWidgetProvider>
    </Theme>
  );
}

import { Concierge } from "@/components/concierge";

export default function Home() {
  return (
    <main style={{ height: "100dvh", padding: 16, boxSizing: "border-box" }}>
      <Concierge />
    </main>
  );
}

"use client";

import "@radix-ui/themes/styles.css";
import "@cadenya/widgets-ui-react/styles.css";
import { useCallback, useEffect, useState } from "react";
import { Box, Flex, Select, Text, Theme } from "@radix-ui/themes";
import {
  CadenyaWidgetProvider,
  ConversationsPanel,
  PageToolsProvider,
} from "@cadenya/widgets-ui-react";
import { WidgetTools } from "@cadenya/widgets-ui-react/widget-tools";

type Session = { token: string; host: string };

async function mintSession(): Promise<Session> {
  const response = await fetch("/api/session", { method: "POST" });
  if (!response.ok) throw new Error("Could not start a Widget Session");
  return response.json();
}

export function Concierge() {
  const [session, setSession] = useState<Session | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [airport, setAirport] = useState("PDX");

  useEffect(() => {
    mintSession().then(setSession, (err: Error) => setError(err.message));
  }, []);

  const getToken = useCallback(async () => (await mintSession()).token, []);

  if (error) return <p role="alert">{error}</p>;
  if (!session) return <p>Packing your bags…</p>;

  return (
    <Theme accentColor="teal" grayColor="slate" radius="large" style={{ height: "100%" }}>
      <Flex direction="column" gap="3" height="100%">
        <Flex align="center" gap="2">
          <Text as="label" size="2">
            Flying from
          </Text>
          <Select.Root value={airport} onValueChange={setAirport}>
            <Select.Trigger />
            <Select.Content>
              <Select.Item value="PDX">Portland (PDX)</Select.Item>
              <Select.Item value="JFK">New York (JFK)</Select.Item>
              <Select.Item value="LHR">London (LHR)</Select.Item>
              <Select.Item value="NRT">Tokyo (NRT)</Select.Item>
            </Select.Content>
          </Select.Root>
        </Flex>
        <Box flexGrow="1" minHeight="0">
          <CadenyaWidgetProvider host={session.host} token={session.token} getToken={getToken}>
            <PageToolsProvider>
              {/* The latest render's value answers, so the agent always reads the current pick. */}
              <WidgetTools pageContext={{ homeAirport: airport }} />
              <ConversationsPanel toolPlacement="inline" />
            </PageToolsProvider>
          </CadenyaWidgetProvider>
        </Box>
      </Flex>
    </Theme>
  );
}

"use client";

import { usePageTool } from "@cadenya/widgets-ui-react";

export function ShortlistTool({ onSave }: { onSave: (city: string) => void }) {
  usePageTool("save_destination", ({ args }) => {
    // Arguments come from the model, so check them before you use them.
    const city = (args as { city?: unknown } | undefined)?.city;
    if (typeof city !== "string") throw new Error("save_destination needs a city");
    onSave(city);
    return { saved: city };
  });
  return null;
}

.concierge-panel {
  --cdny-bubble-user-bg: #0d9488;
  --cdny-bubble-user-fg: white;
  --cdny-bubble-assistant-bg: var(--gray-a3);
  --cdny-scroll-shadow: var(--gray-a4);
}

/* Give the question and destination cards a little room to breathe. */
.concierge-panel .cdny-ask-user,
.concierge-panel .cdny-details {
  margin-block: var(--space-2);
}