Model roles
One key can drive three different jobs, and you can point each at a different model. The three roles live under Advanced in the Add modal, and in Edit models on an existing credential.
| Role | Used for | Tool calling required? |
|---|---|---|
| Chat | The reply your visitor reads. | Yes |
| Planner | Deciding which knowledge lookups and tools to run before answering, plus internal intent classification. | Yes |
| Background | Asynchronous jobs — FAQ mining, knowledge enrichment, and similar work no visitor is waiting on. | No |
If you leave the Advanced fields alone, Planner and Background default to the same model as Chat (or the provider's default for that role), which is a perfectly good setup.
🖼️ [Image] — The Advanced section of the Add modal showing the Planner model, Background model, and Base URL override fields.
Why Chat and Planner need tool calling
Promptly doesn't hand raw text to the model and hope. Every turn goes through a planning step that calls real functions — knowledge search, product catalog lookups, your custom tools, the escalation handoff. A model that can't emit a tool call can't participate in that loop.
So a credential where verification reports Tool calling ✗ is never used for Chat or Planner, no matter what you selected. It stays usable for Background work. See What verification checks.
Background jobs summarise and classify text without calling functions, which is why a cheaper or more limited model is a sensible choice there.
Picking models per role
- Chat — favour speed and reliable tool calling over maximum reasoning depth; this is the one your visitor waits on.
- Planner — the same model as Chat is fine. A smaller, faster model here shortens time-to-first-answer, as long as it calls tools reliably.
- Background — the cheapest capable model. Nobody is waiting, and volume can be high on a large knowledge base or busy FAQ mining run.
Behaviour knobs that are not per-role — temperature, max tokens, history depth — live in Model & behavior settings.
Changing a role's model resets verification
Switching the Chat or Planner model clears the tool-calling result for that credential, because the previous check was run against the old model and says nothing about the new one. The key itself stays verified; only the tool-calling signal is dropped.
That's why Edit models saves through a Test & save button: it verifies the newly chosen chat model first and refuses to save if the connection fails. If the connection works but tool calling doesn't, you get an explicit choice — "This model can't run tools — it can't be used for chat, only for Background tasks. Save anyway?"
Changing only the Background model doesn't reset anything.