The two-level model — channels contain sessions
Every Forge conversation is a session inside a channel. The two-level model is the foundation that makes chat navigable, auditable, and linkable to other platform entities. A channel is a long-lived, scoped conversation space. Its row inchannels carries identity (name, description, emoji, status), scope (scope, scopeEntityType, scopeEntityId), and behavior config (relevancyThreshold, maxAgentLoopDepth, relevancyScoringMode, agentResponseMode, judgeAgentId). Behavior config is inherited by every session inside the channel — channel-level decisions cascade.
A session is a finite conversation inside a channel. Sessions make conversations time-bounded (lifecycle: active → paused → stopping → completed → archived), auditable (every state transition logged), and linkable (can pin to a workflow run, a task, an approval, a project, or any other platform entity via conversationEntityLinks).
Sessions are backed by @convex-dev/agent threads — one per assigned agent. The thread is the source of truth for streaming fidelity (tokens arrive token-by-token through Convex subscriptions). The chatMessages table is the cross-agent ledger — it mirrors assistant turns so memory recorders, peer agents, syndication, and the operator UI all see one consistent timeline. This dual-write pattern is the key architectural choice behind multi-agent chat — streaming comes from threads, durability and cross-visibility come from chatMessages.
Pick a channel scope
Seven scopes, each tied to a platform entity:
Scope drives access.
conversationParticipants rows gate visibility — a user sees a channel in their sidebar only while they (or their Personal Agent) are an active participant.
Pick a dispatch modality
When a human sends a message into a channel, the dispatch orchestrator decides which agent(s) respond. One of four modalities applies:
Relevance-gated is the default for multi-agent channels because it amortizes cost: the vast majority of messages are obviously on- or off-topic for an agent. Only the ambiguous middle pays the LLM price.
For the gating internals — heuristic, LLM, and hybrid scoring; loop detection; the
[PASS] self-determination contract — see the operational parameters below.
Tune relevancy gating
Three knobs on the channel row govern multi-agent behavior:relevancyThreshold— float 0–1. Common settings:0.2permissive (most agents reply),0.5balanced (default),0.7strict,1.0directed-only.relevancyScoringMode—heuristic(rule-based keyword match — fast, free),llm(Haiku rates the message — accurate, costs tokens),hybrid(heuristic first; LLM only for borderline cases — the default).maxAgentLoopDepth— integer; typical values 3–5. Caps consecutive agent turns without a human in between. @-mentioned agents bypass the suppression so a human can break a stalemate.
relevancyScoringModeOverride for experimentation without mutating the channel. Every gate decision is logged to relevancyGateLog with the evaluated agents, scores, threshold, mode, loop snapshot, and timestamps — operators can see why an agent did or didn’t speak on any historical message.
Recommended defaults
Personal Agents — every user has one
A Personal Agent (PA) is a user-ownedagentDefinitions row with agentType: "PERSONAL" and a userId pointer. PAs are auto-provisioned on first hire via channels.provisionPersonalChannel, which clones the platform-published personal-agent template, creates the agent definition row, creates the personal channel, and adds the PA as the sole agent participant.
PAs appear in two places:
- The personal channel. A user’s private space —
scope: "personal", the PA is the only other participant. Useful for drafting, kicking off workflows, asking about platform state. - Every DM the user participates in.
channels.addPAsToDirectMessageruns on DM creation. A DM between Alice and Bob silently includes Alice’s PA and Bob’s PA — the relevancy gate applies, so PAs only speak when their threshold is cleared. Either user can mute their own PA in a specific DM viachannels.mutePA(a soft-delete of that PA’sconversationParticipantsrow).
Provisioning Personal Agents from an external app
If you are building an external application (a product that embeds Forge as its AI backbone), you can provision a Personal Agent for each of your users via the External App endpoints of the HTTP API rather than through the Forge Console hire flow. The two paths create the same kind of agent row — the difference is ownership: Console-hired PAs are owned by the platform user principal; External App PAs are owned by your application principal on behalf of the user. The two-call pattern for a new user:findOrCreateAgent is idempotent — calling it on every login is safe and cheap. The 201 Created / 200 OK status distinction tells you whether the agent was just created or already existed.
The External App endpoints use the same external-app bearer token as inference. User identity flows through the X-Forge-User-JWT header on first call; subsequent calls can pass the Forge userId directly once you’ve cached it from the first response.
Full reference: findOrCreateAgent · listAvailableModelsForAgent · External App endpoints
Open a session from your code
The Platform API exposes channel and session CRUD endpoints. The minimal session-open path:- Resolve or create the channel.
channels.listByScope(scope, scopeEntityType, scopeEntityId)finds existing channels for the scope;channels.createprovisions a new one if needed. For DMs,channels.getOrCreateDMis idempotent. - Open the session.
sessions.create(over HTTP,createChatSession) produces achannelSessionsrow inACTIVEstate.linkedEntityType+linkedEntityIdpin a session to a workflow run, task, or approval for the Forge Console’s “Related conversations” panel; set them from Console, becausecreateChatSessionrefuses them with400. - Send the first message. Over HTTP,
sendChatMessagerecords the human turn in the session, but it starts no agent turn, so no agent replies to it.
channels.listMy, messages.listBySession, and the per-agent thread streams as an implementation detail. External products should use the documented HTTP API.
Live tool-call visibility — render ToolCard and tripwires
Agents in chat stream two kinds of system messages alongside their prose:
- Tool calls — each
sandbox_action,file_put,file_get, or external-tool invocation renders as aToolCardrow with status (started,completed,failed), arguments, and result. The conversation stores the tool message; the underlying sandbox and file operations retain their own governed records. - Budget tripwires — soft and hard budget warnings render as system-authored notices inline in the thread. Persisted via
createTripwireMessage.
ToolCard UI; copy that surface or import the shared components from @gloo/ui if you’re embedding chat in another React app.
Slash commands — shorthand for skills and tools
Free-form prompts are how chat ships its default surface; slash commands are the shorthand for the cases where the intent is well-known. An operator types/code-review file.ts and the message routes to a specific agent with the backing skill pre-activated — no @mention, no full prompt composition, no “which agent owns this?” round trip.
A ChatSlashCommand is a named entry point backed by a skill or a tool. It declares a trigger (kebab-case, no leading slash), a description (shown in the typeahead), an optional argHint, a riskLevel (read · write · financial · destructive), and a targetKind (skill or tool) with the corresponding ID. Slash commands are declared as part of the capability they back — never as standalone entities — which keeps the relationship tight and prevents orphans.
Availability and governance
A slash command is available in a channel only when the backing skill or tool is assigned to at least one participant agent. The typeahead disambiguates when multiple agents share the same trigger. The default policy by risk level:
Opt-out applies at the agent-skill (or agent-tool) assignment level without revoking the underlying capability — useful when an agent has a skill for other purposes but the slash entry point would surprise operators.
Invocation
When a user submits a slash command:- The composer materializes a
chatMessagesrow with aslashCommandRefannotation (thechatSlashCommandId, theagentId, thetrigger) for display. - The slash prefix is stripped from the user-visible content; the remainder is the free-text prompt.
- The message routes to the specific agent associated with the command (or user-disambiguated when multiple agents share the trigger).
- The agent receives the primed context — skill pre-activated or tool pre-selected — and handles the request as a normal turn. It may request clarification or additional arguments.
Stop a runaway conversation
A session header in the Forge Console exposes a Stop agents action. It transitions the session toSTOPPING and flips a flag the dispatch actions honour:
- An agent mid-
streamTextaborts after its next tool call completes. - Any queued per-agent dispatches for the session are skipped before they start.
- A 10s scheduler reconciles to
COMPLETED.
sessions.stopSession.
What you should double-check before shipping
- Channel scope matches the audience. A factory channel for cross-factory work is a smell — pick
projectinstead. - Dispatch modality matches the cost tolerance.
broadcaston a 10-agent channel will burn tokens fast. Default torelevance_gatedfor anything bigger than a panel of three. - Loop depth is set. A multi-agent channel without
maxAgentLoopDepthwill eventually loop. Default to 3. - Tool-call rendering is wired. If your custom UI hides
ToolCardrows, operators lose the audit trail. Render them. - Session linking is done where it matters. A session that exists in isolation from the workflow run, task, or approval that prompted it is a session that’s hard to find again.
- For Slack syndication, check governance stays in Forge — see Webhooks for the bidirectional rules and link-time controls.
Do it over the API
The session-open path above has HTTP equivalents. These calls use theFORGE_BASE set up in the Raw HTTP tab of the quickstart. The quickstart’s ACCESS_TOKEN does not carry every scope they need, so mint it again with scope=chat:read chat:manage chat:use from an app whose roles hold them (see Requesting scopes at token mint), or send a Personal key whose scopes include them. Over HTTP only factory, project and team channels are visible, and only at homes where the credential holds the route’s permission; direct, personal, group and system channels never are.
1
Find the channel
chat:read. A page can be short while meta.hasMore is true; follow meta.nextCursor to read on.2
Open the session
chat:manage at the channel’s home. linkedEntityType and linkedEntityId are refused over HTTP with 400; link a session to a run, task or approval from Console.3
Post a message and read the transcript
chat:use; reading needs chat:read. A message posted over HTTP is recorded in the session, but it starts no agent turn, so no agent replies to it.forge_call_operation posts the same message. It is in the default start job:
See also
- Define an agent — the rows that fill your channel
- Author a skill — the guidance the agents in your channel will follow
- Workforce concept — why agents are workers, why every conversation has a session
- Agent dispatch — how agent turns are dispatched
- Forge API — the channel/session/message endpoints
- HTTP API reference — for products integrating with Forge
- Console — Chat — the operator walkthrough of the Bell

