AI agent

The agent answers messenger visitors from your published help-center articles. It is off until you enable it, and it only takes unassigned conversations on a messenger channel. Once a human or a team holds the conversation, the agent is out.

Model tiering is your own key. FIKADESK_LLM_AGENT_MODEL names the model as provider:model, with the matching API key beside it. The classifier and escalation tiers fall back to the agent model, and embeddings always use the OpenAI-compatible endpoint. Unset the agent model or the embedding endpoint and the agent sink is absent: no visitor message reaches a model, and published articles are not indexed for retrieval.

Grounding

On each turn the agent embeds the visitor's question and retrieves the top four article chunks by cosine distance. It answers only from those chunks, and the prompt says so in the first sentence: answer using only the help-center articles provided, and cite the article titles you use.

The model returns a structured verdict, not prose to parse: an answered boolean, the answer and a list of citations. The runtime keeps only citations whose titles were actually retrieved, so the model cannot cite a source it never saw.

Handoff

Four things hand the conversation to a teammate, and each writes a reply saying so. The visitor asks for a human. The retrieval score falls below the confidence threshold. The agent has answered six times in this conversation, the loop guard. Or the model declined to answer twice in a row.

• human_request when the visitor's message asks for a person.
• low_retrieval when the best chunk scores below confidence_threshold.
• rate_cap after six replies in one conversation.
• unanswered after two consecutive refusals.

A handoff assigns the conversation to the channel's default team and posts the configured handoff_message. The assignment is system-authored with the agent origin, so the agent's own sink skips it and a handoff never cascades.

Configuration

One row per workspace, read and replaced by admins at GET and PUT /api/agent. A workspace that has never saved a config reads the defaults, with enabled false.

curl -X PUT http://127.0.0.1/api/agent \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer fk_<key>' \
  -d '{"enabled":true,"name":"Support assistant","tone":"Plain, no jargon","handoff_message":"I will connect you with a teammate.","confidence_threshold":0.6}'

A failed model call is retried through the job queue. The last attempt writes a refusal instead of failing the job, so a visitor is never left silent; a model that declines twice hands off.