Enabling agent delegation from chat

Admin

The chat LLM (the general chat assistant) can call admin-enabled special-purpose agents as named tools — delegating a research task to a research agent, having a review agent verify it, or letting an agent prepare write actions that the user confirms in chat. This article explains how to enable and secure that.

Not the same as “Agents in Chat”

There are two similarly named features that are easy to confuse:

Feature	What it is	Layer
Agents in Chat	An agent gets its own contact in user-to-user messaging and is addressed like a colleague via DM.	Messaging (`Mode = ChatMessage`)
Agent delegation from chat (this article)	The chat LLM calls special-purpose agents as tools inside the normal chat assistant.	LLM chat view (`Mode = ChatDelegated`)

Both use the same agent runner but are different entry points.

Global kill switch — `Agents:ChatDelegationEnabled`

Turns chat delegation on or off instance-wide. Set it via the environment variable Agents__ChatDelegationEnabled or under Administration → System settings.

Mode-aware default: Desktop = on, Web = off. Web deployments must therefore enable delegation deliberately.
When the kill switch is off, no delegation tool is materialized (not even verified_research).

Enable Web first: In Web mode nothing happens without this switch, no matter how the agents are configured.

Enable per agent

In the agent detail (Administration → Agents, Tools tab), in the “Available in chat” block:

Field	Meaning	Default
`ExposeInChat`	Exposes the agent as a chat delegation tool.	off
`ChatToolName`	Tool name, slug form `^[a-z0-9_]+$`, unique vault-wide. Empty ⇒ automatic `slug(agent name)`.	empty
`ChatToolDescription`	The tool description the LLM sees — it governs when the LLM delegates.	empty

Steps:

Check the kill switch (Web: on).
Enable ExposeInChat.
Set ChatToolName (e.g. research_pharma) — or leave it empty for the auto slug.
Write a precise ChatToolDescription — the LLM decides whether to delegate based on it.
Save. The tool is immediately available in chat.

Slug form and uniqueness are enforced server-side in every write path — a duplicate ChatToolName is rejected.

Sync cap — `Agents:ChatDelegationCapSeconds`

How long a delegation waits synchronously for the sub-run result before switching to catch-up mode. Default 75 s.

Finishes within the cap ⇒ the result goes straight into the answer.
Cap exceeded ⇒ the run continues in the background; the LLM fetches the result later via an internal re-poll (check_agent_run).

The value is clamped internally against the chat tool timeout so the wait returns its “still running” handle before the tool dispatcher tears the call down.

Write confirmation (two-phase)

If a delegated agent contains write tools, a notice banner appears in the agent detail: every write tool call of a delegated run requires confirmation in chat.

Phase 1 (default, dry run): Reads run, writes are suppressed and collected. If writes were planned, the assistant presents the user with a plan list and asks for approval. If nothing was written, the dry-run result is already the final result (pure read delegation passes through without a prompt).
Phase 2 (after “yes”): The run executes for real and writes are performed.

A delegated agent can therefore never write without confirmation.

`verified_research`

An optional configured tool of type VerifiedResearch: it chains an admin-chosen research/review agent pair deterministically (research → review → revision if needed). The review step cannot be skipped. It is created like other configured tools. → Configurable tools

Security & limits

Identity: The sub-run runs with the identity and rights of the chat user (RunAsUserIdOverride == chatUser), never elevated. A delegated agent can see or do nothing the triggering user couldn’t do themselves — the non-negotiable core safeguard.
Opt-in per agent: ExposeInChat is off by default; no agent is exposed by accident.
Fixed limits (code constants, not settings): maximum delegation depth 2 (a delegated agent may itself delegate one more level) and at most 3 delegations per chat turn — a brake against recursion and cost blow-up.

Audit

Every delegated run appears under Administration → Agents → Runs with Mode = ChatDelegated, Origin = chat-delegation, and the ParentRunId of the triggering run. → Audit log

Known limits

No automatic delivery (async push): for long runs the result must be requested in chat; it does not (yet) appear on its own.
Cap exceeded during a dry run: if a dry run hits the cap, the result comes back as text — the machine-readable plan list is lost in this edge case. Safety is preserved, since a dry run never performs a write anyway.

Agent delegation in chat (for users) — what end users see
Admin tab: Agents · Configurable tools
Agents (feature) · Agent model