Quickstart

This walks through building a minimal Ask Agent chat surface with @firmly/ask-agent-sdk on top of the Vercel AI SDK UI (@ai-sdk/svelte’s Chat). Every SDK call below uses the real exported function names and parameters — nothing here is illustrative pseudocode. A few host-supplied glue functions (e.g. currentShopper, runMerchantHook) are your own code, not SDK exports — each is marked inline where it appears.

Install

@firmly/ask-agent-sdk isn’t on npm yet — it’s available on request. Contact Firmly for access to the package.

The SDK ships as an ES module with a single optional peer dependency:

package.json

"peerDependencies": {
  "ai": "^6.0.0"
}

ai (v6) is only required once you actually construct a transport or chat — a host that only needs defineCapabilities/createToolDispatcher can import the SDK without it. For this Svelte walkthrough, also install the AI SDK’s Svelte binding:

npm install @ai-sdk/svelte ai

Fetch the merchant's config

fetchAskAgentConfig calls the backend’s /api/embed/capabilities endpoint and returns only client-safe data — the merchant’s effective tool/component set and presentation config, never the system prompt or hook implementations.

import { fetchAskAgentConfig } from '@firmly/ask-agent-sdk';

const config = await fetchAskAgentConfig({ merchant: 'your-store.com' });
// config.enabledComponents -> capability keys the merchant has turned on

Declare capabilities

Tell the SDK which UI components your host can render. It resolves that list down to the concrete tool names — supportedTools — that ride on every chat request. Your declaration can only narrow the merchant’s enabled tool set, never widen it.

import { defineCapabilities } from '@firmly/ask-agent-sdk';

const { supportedTools } = defineCapabilities({
  components: config.enabledComponents
});

Bootstrap the session

A standalone host running on the merchant’s own origin needs a first-party browser-session token before it can call /api/chat. createSession mints or refreshes it over the shopper’s existing session cookie — no API keys in the browser.

import { createSession } from '@firmly/ask-agent-sdk';

const { ensureSession } = createSession({ merchant: 'your-store.com' });
await ensureSession();

Create the transport

createAskAgentTransport returns an AI SDK v6 ChatTransport that posts to /api/chat and injects pageContext/shopperContext/supportedTools into the request body on every turn.

import { createAskAgentTransport } from '@firmly/ask-agent-sdk';

const transport = createAskAgentTransport({
  api: '/api/chat',
  merchant: 'your-store.com',
  supportedTools,
  getPageContext,
  getShopperContext
});

getPageContext and getShopperContext are functions you supply, each returning a plain object (or a Promise of one) fetched fresh per turn — e.g. the current PDP/category the shopper is on, or { user, orders } from your own session state.

Build the tool dispatcher

Some tools are client-executing: the agent asks a question only your host page can answer (because only the merchant’s own JavaScript has the shopper’s session), and your dispatcher handlers answer it.

import { createToolDispatcher } from '@firmly/ask-agent-sdk';

const dispatch = createToolDispatcher({
  handlers: {
    runDataHook,
    onCheckout,
    onBuyNow
  }
});

runDataHook({ name, input }) — runs the merchant’s data-hook JS for the requested hook name and returns its JSON-serializable result; the SDK feeds it back to the model via addToolResult.
onCheckout(input) — fires when the agent calls proceed_to_checkout; swap your UI into checkout. The server tool already resolved, so this handler does not call addToolResult.
onBuyNow(input) — resolves a buy_now call (variant lookup + cart/checkout handoff) and returns output the SDK feeds back so the model can confirm the action.

Wire the chat

Drop the transport and dispatcher into @ai-sdk/svelte’s Chat:

<script>
  import { Chat } from '@ai-sdk/svelte';
  import { stepCountIs, hasToolCall } from 'ai';
  import { shouldResumeAfterHook } from '@firmly/ask-agent-sdk';

  const chat = new Chat({
    transport,
    onToolCall: ({ toolCall }) =>
      dispatch({ toolCall, addToolResult: chat.addToolResult }),
    sendAutomaticallyWhen: ({ messages }) => shouldResumeAfterHook(messages),
    stopWhen: [stepCountIs(25), hasToolCall('suggest_followups')]
  });
</script>

Complete example

Putting the six pieces together in one component:

<script>
  import { Chat } from '@ai-sdk/svelte';
  import { stepCountIs, hasToolCall } from 'ai';
  import {
    fetchAskAgentConfig,
    defineCapabilities,
    createSession,
    createAskAgentTransport,
    createToolDispatcher,
    shouldResumeAfterHook
  } from '@firmly/ask-agent-sdk';

  const MERCHANT = 'your-store.com';

  const config = await fetchAskAgentConfig({ merchant: MERCHANT });
  const { supportedTools } = defineCapabilities({
    components: config.enabledComponents
  });

  const { ensureSession } = createSession({ merchant: MERCHANT });
  await ensureSession();

  function getPageContext() {
    return { url: window.location.href };
  }
  function getShopperContext() {
    return { user: currentShopper() }; // currentShopper: your own implementation — not part of the SDK
  }

  const transport = createAskAgentTransport({
    api: '/api/chat',
    merchant: MERCHANT,
    supportedTools,
    getPageContext,
    getShopperContext
  });

  const dispatch = createToolDispatcher({
    handlers: {
      runDataHook: ({ name, input }) => runMerchantHook(name, input), // runMerchantHook: your own implementation — not part of the SDK
      onCheckout: (input) => goToCheckout(input), // goToCheckout: your own implementation — not part of the SDK
      onBuyNow: (input) => resolveBuyNow(input) // resolveBuyNow: your own implementation — not part of the SDK
    }
  });

  const chat = new Chat({
    transport,
    onToolCall: ({ toolCall }) =>
      dispatch({ toolCall, addToolResult: chat.addToolResult }),
    sendAutomaticallyWhen: ({ messages }) => shouldResumeAfterHook(messages),
    stopWhen: [stepCountIs(25), hasToolCall('suggest_followups')]
  });
</script>

{#each chat.messages as message (message.id)}
  <!-- render message.parts with your own components -->
{/each}

shouldResumeAfterHook is the hooks-only baseline for sendAutomaticallyWhen — it resumes the turn once every data-hook tool call in the latest message has a result. Hosts that also intercept custom UI components or buy_now outside the dispatcher (as Firmly’s own dogfood widget does) may need a richer resume predicate that additionally accounts for those tool calls.

The SDK is framework-agnostic (built on AI SDK v6): the same defineCapabilities, createSession, createAskAgentTransport, and createToolDispatcher calls work unchanged with React’s useChat or any other AI SDK UI binding — only the chat hook itself differs.

Perfect for the headless SDK
Consider the drop-in embed instead

You need the assistant to match your app’s design system, render inline in a native (non-iframe) surface, or run inside a framework shell the drop-in embed can’t reach.

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Complete example

Next steps

Reference

Overview

​Complete example

​Next steps

Reference

Overview

Complete example

Next steps