> 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/agents/limio-agents/configuring-an-agent.md).

# Configuring an Agent

Set up a Limio agent in the admin console: instructions, presentation, tools, knowledge, and publishing.

Agents are configured in the Limio admin under **AI → Agents**. Each agent has instructions, a presentation, a set of tools, optional knowledge sources, and [outcomes](https://docs.limio.com/agents/limio-agents/outcomes.md). You edit a draft, test it in place, and publish a version when it is ready. Nothing changes for visitors until you publish.

## Creating an agent

An agent's name is a short identifier: lowercase letters, digits, hyphens, and underscores. It cannot be changed after creation. The name carries no special meaning: which agent answers on a domain is decided by a [workflow](https://docs.limio.com/agents/limio-agents/workflows.md), not by what the agent is called.

## Instructions

The Details tab holds the agent's instructions: who it is, what it sells or supports, and how it should behave. Write them the way you would brief a new team member. A typical structure:

* Who the agent is and what the shop sells.
* How to qualify a visitor before recommending anything.
* How to handle common objections.
* When to hand off to a human.

The platform adds rules around your instructions, so you do not need to write them yourself:

* **On every agent**, the agent helps only with requests that fit the purpose your instructions give it. It declines other requests, for example to write code, or to give medical, legal or financial advice that is not part of your business. If a visitor asks whether they are talking to a person, the agent says that it is an AI assistant for your business. It never names the AI company or model behind it. These rules take priority over your instructions, so an instruction such as "help with every request" does not remove them.
* **When an agent has tools**, it also never exposes internal mechanics, only quotes offers and prices that a tool returned, and presents checkout links as clickable links.

The platform adds no persona of its own. Who the agent is comes entirely from your instructions.

Write your instructions to describe your business clearly. The agent uses them to decide which requests are in scope. If your business gives advice, for example on consumer rights, say so, and the agent answers those questions.

The agent tries not to reveal your instructions, but do not rely on this. A visitor can also ask the agent to repeat any fact in a knowledge document. Do not put internal or confidential information in your instructions or in a knowledge document.

## Presentation

The Presentation tab controls how the chat surface looks before and during a conversation.

| Setting              | What it does                                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat title           | Heading shown above the conversation.                                                                                                                                                 |
| Greeting             | Opening message the agent sends when a conversation starts. Leave blank for the agent to stay silent until the visitor speaks.                                                        |
| Composer placeholder | Hint text in the message box.                                                                                                                                                         |
| Pointers             | Up to four starter questions shown as clickable chips beneath the greeting. They disappear once the conversation starts.                                                              |
| Footer               | Optional markdown shown beneath the message box.                                                                                                                                      |
| Launcher and popup   | The launcher's icon, a slide-out label, and an optional greeting popup with its own message and delay. See [Theming an Agent](https://docs.limio.com/agents/limio-agents/theming.md). |
| Theme                | Brand colours and bubble style for this agent's chat, with a live preview. See [Theming an Agent](https://docs.limio.com/agents/limio-agents/theming.md).                             |

## Tools

Tools let the agent act rather than just talk. Attach them on the Tools tab.

| Tool                    | What the agent can do with it                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Fetch offers            | Read the published offers carrying a given offer label, so recommendations quote real names and prices. Configure the label to scope which offers the agent sees. See [Offers the agent can see](#offers-the-agent-can-see).                                                                                                                                                                                                                                             |
| Create checkout session | Create the basket for the offer the shopper chose and hand back a secure link to pay. The link carries the shopper's session, so the order they place is tied to the conversation that sold it — the agent can then answer "what did I just order?" later in the same chat. Prefilled with the email collected in conversation and tagged `utm_source=limioagent`. If the agent's reply ever omits the link, the platform appends it, so the shopper always receives it. |
| Build checkout link     | Builds a link without creating a basket, so the resulting order is not tied to the conversation. Only needed for offers configured with an external checkout URL, which **Create checkout session** cannot handle — attach it alongside for those catalogues.                                                                                                                                                                                                            |
| Get order items         | Read what the shopper bought, for use on the order-complete page.                                                                                                                                                                                                                                                                                                                                                                                                        |
| Documents               | Request documents from the visitor. An upload control appears in the chat; configure which documents the agent may ask for.                                                                                                                                                                                                                                                                                                                                              |

Beyond the built-ins, toolsets created from your tenant's connectors (**AI → Connectors**) also appear in the picker, so an agent can call systems you have connected.

Lead capture is deliberately not in this list: the agent cannot write a lead on its own initiative. Capture runs through [outcomes](https://docs.limio.com/agents/limio-agents/outcomes.md), where you control exactly when it fires and which fields it records.

### Offers the agent can see

The **Fetch offers** tool reads published offers only. When you change an offer, for example its price, its label or its AI Description, the agent does not see the change until you publish a page that uses the offer. Saving the offer is not enough.

To give the agent more detail about an offer, use the offer's **AI Description** field. The agent reads it with the offer. Shoppers never see it. Use it for facts the agent needs but that are not on the page, for example the MSRP:

> MSRP for 2 years: $99.98

State the term that a price covers. The agent uses the text as written, so "MSRP/Yr" on a 2-year offer makes it compare a yearly price with a 2-year price.

If your offers do not show an AI Description field, add it to your offer template in **Catalog → Config → Templates → Offers**.

## Knowledge

The Knowledge tab attaches document sources to the agent. When a visitor asks something a document covers, the agent reads the document and answers from it instead of guessing. Attached sources appear as a catalogue the agent can consult; it never reveals to the visitor that it is reading documents.

## Outcomes

Outcomes are the goals the agent works towards in every conversation: qualify and send a checkout link, capture a lead, hand off to sales. They have their own tab and their own page: see [Outcomes](https://docs.limio.com/agents/limio-agents/outcomes.md).

## Advanced

Two per-reply caps, both optional:

| Setting           | Default | What it caps                                                                                                                                                                                                                                          |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Max output tokens | 4096    | The length of a single reply.                                                                                                                                                                                                                         |
| Steps per reply   | 8       | How many times the agent can call the AI model to answer one message. Each round of tools uses one, and the final answer uses one, so 8 allows up to 7 rounds of tools. Every new message starts again, so a long conversation does not use up steps. |

Most agents do not need to change either.

### Stream replies

**Stream replies** is off by default. Turn it on and the reply appears as the agent writes it, a few words at a time, rather than arriving whole once the agent has finished. Streaming changes when the first words appear, not when the reply completes.

It does not make the agent faster. An agent that calls tools spends most of its turn on them and cannot write the answer until they return, so the pause before the text starts is as long as it ever was.

A model often writes a short line, such as "let me check our offers", before it calls a tool. What happens to it depends on **Show progress messages**:

* **Off:** the platform tells the agent not to write this line. If the agent writes it anyway, the line shows for a short time and then goes when the tool call starts. Only the answer remains in the transcript.
* **On:** the line stays as its own message, before the answer. See [Show progress messages](#show-progress-messages).

Either way, while tools run, the chat shows a short status line, such as "Getting your checkout ready...".

Streaming also needs a model that supports it. If you turn the toggle on and replies still arrive whole, the model behind your tenant cannot stream: ask Limio, rather than looking for another setting on the agent.

The toggle is part of the agent, so **Save** and **Publish latest** apply as they do to any other change. Once published, new conversations pick it up within a minute. A visitor with the page already open keeps the behaviour they loaded with until they reload.

### Show progress messages

**Show progress messages** is off by default. Turn it on and, before the agent calls a tool, it can write one short sentence about what it is doing for the visitor, for example "I'll find the plans that suit a team of five." The sentence stays in the transcript as its own message, and the answer follows in a new message. The agent skips the sentence when it has nothing useful to say.

With streaming on, the visitor sees the sentence while the tools run. With streaming off, the sentence arrives with the answer.

## Editing as YAML

The YAML tab shows the whole agent as one document: instructions, presentation, tools, and outcomes together. The tab flags problems as you type. When you leave the tab or click **Save**, your edits apply. A draft that applies replaces what the other tabs hold, and there is no undo. To throw an edit away, click **Discard YAML changes**, which returns the tab to the last applied version. If the draft has a problem, you cannot leave the tab or save until you fix it or discard it. Use the tab to review an agent in one place or to copy a configuration between environments. The model and the version are not part of the YAML: Limio manages them, and Limio blocks a draft that sets them.

```yaml
description: Inbound sales agent
systemPrompt: >-
  You are an inbound sales agent on the pricing page...
presentation:
  title: Sales
  greeting: Hi! What brings you here today?
toolsets:
  - name: fetch_offers
    config:
      label: pricing-page
outcomes:
  - id: qualified_send_link
    label: Qualified - Send checkout link
    criteria: The shopper is ready to buy one of the offers you can sell.
    whatToDo: Use @create_checkout and present the link in your reply.
    tools:
      - id: create_checkout
        tool: create_checkout
```

## Testing with Try it

**Try it** opens a test conversation against your current draft, unsaved edits included. The full agent runs: tools fetch real offers and build real links. Outcome follow-up actions are the one exception: they are dry-run and nothing is recorded, so testing never creates a lead.

## Versions and publishing

Publishing an agent makes that version the live one, but it does not put the agent on a site. A [workflow](https://docs.limio.com/agents/limio-agents/workflows.md) is what routes a domain to an agent. Until one does, chat on that domain will not start.

**Save** creates a new draft version; the live agent is untouched. When the draft is ready, **Publish latest** puts it live. The Versions tab lists the history, and any version can be published, so rolling back is publishing the version that worked. Unpublishing the live version takes the agent offline.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limio.com/agents/limio-agents/configuring-an-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
