Overview

Limio's conversational agent and the client SDK for building your own chat experiences on top of it.

A Limio agent is a conversational AI assistant that runs inside your shop. Visitors ask it questions in plain language; it replies with formatted text and can surface interactive components inline, such as an offer card or a file upload. The agent powers the built-in chat widget, and you can build your own chat surface on the same primitives.

You configure an agent entirely in the Limio admin: its instructions, how the chat looks, the tools it can use, the knowledge it draws on, and the outcomes it works towards. No code is required until you want a custom chat surface.

An agent does not know where it runs. A workflow is what puts it on a domain, and what decides between agents when you have more than one. Publishing an agent is not enough on its own.

The agent client SDK (@limio/sdk/ai) is available from Release 117 onwards. If your environment is on an earlier release, contact your Limio admin about upgrading.

Where the agent appears

Surface	What it is
Chat widget	The built-in floating chat launcher, configured and styled in Limio. No code required.
Chat Panel component	An inline, in-page chat surface you drop onto a page in the Page Builder, as an alternative to the floating widget.
Custom surface	Your own React component built on the client SDK: an exit-intent popup, a full-page assistant, a sidebar, whatever fits your page.
Chat embed	The same floating widget on a website outside Limio, added with a script tag. See Chat Embed.

The widget, the panel and the embed are ready to use. The custom surface is what the SDK pages cover.

What the agent can do

An agent with no tools can only converse. Tools and outcomes are what make it useful:

• Answer questions from knowledge sources you attach, instead of guessing.
• Recommend offers by reading your catalogue, so it quotes real names and prices.
• Build checkout links prefilled with the details the shopper gave in conversation, attributed to the agent for reporting.
• Request documents from the visitor, with an upload control inline in the chat.
• Capture leads when a conversation reaches an outcome you configured, never on its own initiative.
• Record a disposition for every conversation, so you can see in the admin which conversations qualified, converted, or need follow-up.

Configuring an Agent covers the setup; Outcomes covers goals, lead capture, and dispositions.

The conversation model

Every chat surface talks to the same Chat API and works with the same four concepts.

Session. Identifies the visitor, either a signed-in user or a guest. It is created when the surface loads and carries the agent's configured greeting. Authentication is automatic: pages on your shop domain use the visitor's Limio session cookie, so there are no keys to manage.

Conversation. A thread of messages. It is created lazily, on the visitor's first message, so an open but unused chat surface costs nothing.

Message. Has a role (user or assistant) and content. Content is an array of blocks, not a plain string.

Content blocks. Each message carries one or more typed blocks:

Block type	Used for
text/markdown	Agent replies and the greeting. Render formatted: bold, lists, links, tables.
text/plain	The visitor's own words. Rendered literally, never parsed as markdown.
application/vnd.limio.component+json	An interactive component the agent surfaces inline, such as a file upload. Rendered through a component registry, and ignored if your surface does not handle it.

You do not manage sessions, conversations, or optimistic message state yourself. The useChat hook in the client SDK does it for you.

Building on the agent

The client SDK is published as a subpath of the Limio SDK:

import { useChat } from "@limio/sdk/ai"

It gives you three things:

• useChat is a headless conversation hook: session bootstrap, lazy conversation creation, optimistic messages, a pending reply bubble, and error rollback. You supply the UI.
• The transport is a set of typed functions for the Chat API, if you need to call it directly.
• MessageContent renders a message's content blocks into React, markdown-aware, with a registry for component blocks.

Because it is headless, you bring your own markup and styles. The built-in widget and the Chat Panel component are built on these same primitives, so a custom surface behaves the way they do.

Next steps

• Configuring an Agent: instructions, presentation, tools, knowledge, and publishing
• Workflows: route a domain to an agent, and choose between agents by page, country or sign-in state
• Theming an Agent: brand colours, bubble style, and the live preview
• Outcomes: goals, lead capture, and conversation dispositions
• Getting Started: build your first chat surface with @limio/sdk/ai
• SDK Reference: useChat, the transport, the renderer, and the component registry
• Vibe Coding a Chat Surface: have Claude Code build the surface for you