# How the Linkubit AI agent works: every setting, and what it changes

> What happens on every customer message, which setting controls each step, and which parts are enforced in code rather than asked of the AI.

Source: https://www.linkubit.com/docs/how-the-ai-agent-works  
Section: Linkubit help centre › How the AI agent works  
Updated: 2026-10-09

## In short

Each customer message runs one turn: account checks, the live goal, rule checks, the reply, then extraction, scoring and workflows. Goals and their stance steer the conversation; fields are what it collects; rules and escalation are enforced in code; scoring and workflows act on what was learned. Most surprises come from two settings acting on each other, not from the AI.

## The parts, and what each one controls

| Setting | Where | What it controls | Enforced or asked |
| --- | --- | --- | --- |
| Agent role | Settings › AI settings › Agent roles | The persona (system prompt), what the agent may do, and the goal a new conversation starts on. One role is active at a time. | Persona is asked; **What it may do** is enforced |
| Conversation goals | Settings › AI settings › Conversation goals | What the agent is working towards, how to behave while doing it (the **stance**), and which fields complete it. | Stance is asked; completion is computed in code |
| Fields you collect | Settings › Fields you collect | The details the agent captures about each customer. Goals, rules, scoring, stages and workflows all refer to them. | Captured by the AI, stored as data |
| Agent rules | Settings › AI settings › Agent rules | Limits: block an action until fields are captured, need a person before an action, or add a standing instruction. | Enforced, except **Append instruction** |
| Human escalation | Settings › AI settings › Human escalation | Topics that always go to a person. | Enforced |
| Scoring rules | Settings › Scoring rules | Points for what a customer did or said. | Computed in code |
| Workflows | Settings › Workflows | When something happens, do something — qualify, open a deal, create a task, escalate. | Run by code |
| Pipeline stages | Settings › Pipeline stages | The board's columns, and fields a contact needs before entering each. | Enforced |
| Follow-ups | Settings › Follow-ups | When the agent chases a customer who went quiet, and when the lead counts as cold. | Run by code |
| Knowledge and Catalogue | Knowledge, Catalogue | What the agent answers from, and the only prices it may quote. | Prices checked in code |

## What happens on one customer message

1. **The conversation is checked.** If it is in human mode (a person took over, or it was escalated), the agent does not reply — the message waits in the inbox. Then the account: a blocked contact, an empty credit balance, a contact past the Free plan's cap, a flood of messages or a daily limit each stop the turn, with a reason on the conversation.
2. **The live goal is resolved.** If no goal is running, the role's **Goal it pursues** starts — once per conversation; a goal that ended is not restarted by the next message.
3. **Escalation topics are checked** against the message, and the built-in frustration check runs. Either can hand the conversation to a person before the reply.
4. **The agent writes its reply**, using Knowledge and the Catalogue through its tools. Every tool call passes the rule gate first; a refused call is shown to the agent as refused.
5. **The reply is verified** — prices against the catalogue, and no claim that something was booked or sent unless a tool did it this turn. A reply that fails is not sent; the customer gets a holding message and the conversation goes to a person.
6. **After the reply is sent**, one extraction call reads the conversation for your fields. Captured values are written to the contact, goals are settled (a lead is created from the first required field captured, a goal completes when all its required fields are in), the score is recomputed, and events such as `contact.scored`, `lead.qualified` and `goal.completed` run your workflows.

> **Most surprises are two settings meeting.** Step 6 is a chain: a captured field moves the score, a score band qualifies the lead, `lead.qualified` runs every workflow listening for it. A workflow that escalates on `lead.qualified` therefore hands over as soon as the score clears the band — which on the starter rules can be the fifth message. See [From a conversation to a lead to a deal](https://www.linkubit.com/docs/conversation-to-lead-to-deal).

## Enforced versus asked

A setting that reaches the AI as text — the persona, a goal's stance, an **Append instruction** rule — is guidance: the agent usually follows it and nothing stops it if it does not. A setting checked in code — what the agent may do, the rule gate, escalation topics, catalogue prices, goal completion, the human-mode stop — holds whatever the AI writes. If something must never happen, it belongs in the second group.

## Where to see what happened

- **The conversation thread** — the **automatic events** row between messages expands to every score change, rule that took effect, lead, deal, task and hand-over on that message.
- **The contact** — the score breakdown lists every rule that added or removed points.
- **Settings › Audit log** — every workflow run (`workflow:<trigger>`, with each action's result), every skipped turn (`agent.turn_skipped`, with its reason), every event.
- **The Test agent conversation** in Inbox — try a change before customers see it.

## Related
- [Conversation goals and stance](https://www.linkubit.com/docs/conversation-goals-and-stance)
- [From a conversation to a lead to a deal](https://www.linkubit.com/docs/conversation-to-lead-to-deal)
- [Why did the agent hand over or stop replying?](https://www.linkubit.com/docs/why-the-agent-handed-over-or-stopped-replying)