What it means for an agent to “run.” A run is an agentic loop: the platform assembles the prompt, hands it to a chat model with three knowledge tools, and the model drives the turn itself — thinks, calls a tool, reads the result, repeats — until it has an answer. Not a workflow builder and not a single RAG call: where one search call ends and the full loop begins — the boundary with Query Engine. Whose permissions the reads run under is held by the agent’s identity.
Before every run the platform assembles the prompt in layers, in a strict order. The platform prompt goes first: safety and organizational rules, shared across all AI calls; it is owned by Admin Panel, not the agent’s author. On top of it — the agent prompt: task, tone, what to look for. The engineering layer closes it out: identity binding and tool descriptions. An employee edits only their own layer; platform rules can’t be overridden by a prompt.
the engine sets the order, not the owner: platform rules can’t be overridden by a prompt, and tool results arrive as data, not commands. The identity is likewise imposed from outside the loop — its binding is set by the Prompt library.
The assembled prompt goes to the chat model AI, and from there the model drives the turn. At each step it decides for itself: call a tool for facts, or start composing the answer. The tool result comes back into its context, and the step repeats. The tool-calling itself is not our code: it’s the shared harness, shared with Query Engine; the loop and the cap are the agentic parameterization on top of it.
The run’s model is the one the owner picked from the agent_models list (which is why an agent’s model must be able to call tools). If an admin removes the model from the list, the agent halts until it’s switched to another (the model as a start condition).
The iteration cap is a single run’s safety net: a platform setting
(platform_settings.agent_iteration_cap, one number per
organization), not a field on the agent. How many runs an employee can
afford per week is bounded by a separate
token budget.
The loop runs on a background
lane, separated from live chat.
The model always holds a core of three tools into Knowledge Store, chosen by query intent. Search, graph traversal, and SQL are KS primitives; the agent calls them rather than implementing them, always under the permissions of the agent’s identity: it sees exactly what the owner would see. The core is locked — read-only, can’t be turned off, present on every agent.
Permissions trim the results on the KS side, via an ACL pre-filter on the identity — not a post-filter in the agent. The same tool returns different results for two employees: each sees their own slice.
Empty knowledge base — no core, by derivation.
“Locked” means “can’t be turned off by hand,” not “present in any state
of the knowledge base.” When there’s nothing to search
(is_empty), the shared
harness doesn’t offer
the core — consistent with chat. The agent degrades gracefully: it runs
on the optional external tools if any are selected, otherwise it plainly
reports there’s no data. An empty knowledge base doesn’t enter the
readiness gate — it
doesn’t block the start, just as removing an added tool doesn’t; once
the knowledge base fills up, the core returns on its own.
On top of the core the owner may attach optional read-only external tools — from those the admin allowed in the tool catalog (the choice is recorded in agent_tools). Removing such a tool is graceful degradation: the agent carries on with the core, and this doesn’t enter the readiness gate (unlike a removed model, which does block the start). Write tools and MCP sources — v2.
When the loop ends, the model’s final answer is written as a row in the
run
journal together with token spend and the outcome
(succeeded / failed — a run that hit the
iteration cap also lands in failed). That’s the whole
output: the result lives in the journal and is visible on the agent’s
screen. The agent writes nothing to Knowledge Store — its access is
strictly
read-only.