> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/ai/limio-agents/limio-agents.md).

# Overview

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](/ai/limio-agents/outcomes.md) it works towards. No code is required until you want a custom chat surface.

An agent does not know where it runs. A [workflow](/ai/limio-agents/workflows.md) 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.

{% hint style="info" %}
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.
{% endhint %}

## 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](/ai/chat-embed/chat-embed.md).      |

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 when a conversation reaches an outcome, so you can see in the admin which conversations qualified, converted, or need follow-up.

[Configuring an Agent](/ai/limio-agents/configuring-an-agent.md) covers the setup; [Outcomes](/ai/limio-agents/outcomes.md) 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:

```ts
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](/ai/limio-agents/configuring-an-agent.md): instructions, presentation, tools, knowledge, and publishing
* [Workflows](/ai/limio-agents/workflows.md): route a domain to an agent, and choose between agents by page, country or sign-in state
* [Theming an Agent](/ai/limio-agents/theming.md): brand colours, bubble style, and the live preview
* [Outcomes](/ai/limio-agents/outcomes.md): goals, lead capture, and conversation dispositions
* [Getting Started](/ai/limio-agents/getting-started.md): build your first chat surface with `@limio/sdk/ai`
* [SDK Reference](/ai/limio-agents/sdk-reference.md): `useChat`, the transport, the renderer, and the component registry
* [Vibe Coding a Chat Surface](/ai/limio-agents/vibe-coding-a-chat-surface.md): have Claude Code build the surface for you


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.limio.com/ai/limio-agents/limio-agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.