Skip to main content
This guide is for the engineer or operator wiring chat into a Forge-backed surface — the Forge Console’s Bell, an embedded factory channel, a Slack syndication, or a custom UI that opens sessions through the Platform API. The thing you are filling in is rows in channels, channelSessions, and chatMessages; the thing it becomes is a governed conversation between humans and agents. For the conceptual frame — why every conversation runs inside a session, why sessions are time-bounded, why the data model has both per-agent threads and a cross-agent message ledger — see Workforce concept. For the architectural picture of the dispatch path, see Agent dispatch.

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 in channels 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.2 permissive (most agents reply), 0.5 balanced (default), 0.7 strict, 1.0 directed-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.
A session may override the channel’s mode via 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.

Personal Agents — every user has one

A Personal Agent (PA) is a user-owned agentDefinitions 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:
  1. 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.
  2. Every DM the user participates in. channels.addPAsToDirectMessage runs 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 via channels.mutePA (a soft-delete of that PA’s conversationParticipants row).
PAs go through the same agent composition as any other chat agent. The user’s permissions gate what their PA can do — a PA can use any platform skill and any tool set the user is entitled to. Memory accumulates the same way: session, channel (a multi-year journal in the personal channel; counterpart-specific knowledge in DMs), long-term (vector-indexed, surfaces across conversations months later). Users can inspect and forget specific memory fragments from the UI — consent is preserved throughout. For the conceptual frame, see Workforce concept. For the dispatch and memory mechanics, see Agent dispatch.

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:
  1. Resolve or create the channel. channels.listByScope(scope, scopeEntityType, scopeEntityId) finds existing channels for the scope; channels.create provisions a new one if needed. For DMs, channels.getOrCreateDM is idempotent.
  2. Open the session. sessions.create (over HTTP, createChatSession) produces a channelSessions row in ACTIVE state. linkedEntityType + linkedEntityId pin a session to a workflow run, task, or approval for the Forge Console’s “Related conversations” panel; set them from Console, because createChatSession refuses them with 400.
  3. Send the first message. Over HTTP, sendChatMessage records the human turn in the session, but it starts no agent turn, so no agent replies to it.
For the platform’s domain architecture, see Forge API. Forge Console subscribes to 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 a ToolCard row 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.
This makes the agent’s behavior auditable in real time — operators see why an agent paused, what it ran, and whether it hit a governor. If you build a custom chat surface, render these system rows alongside agent prose; filtering them out hides the most important debugging signal the platform produces. The Forge Console’s Bell renders the canonical 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:
  1. The composer materializes a chatMessages row with a slashCommandRef annotation (the chatSlashCommandId, the agentId, the trigger) for display.
  2. The slash prefix is stripped from the user-visible content; the remainder is the free-text prompt.
  3. The message routes to the specific agent associated with the command (or user-disambiguated when multiple agents share the trigger).
  4. 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.
Slash commands do not bypass the rest of the chat pipeline. Relevancy gating, governance preflight, budget gates, tool-execution audit — all run as they would for a free-form prompt. The shorthand is operator ergonomics; the dispatch is identical.

Stop a runaway conversation

A session header in the Forge Console exposes a Stop agents action. It transitions the session to STOPPING and flips a flag the dispatch actions honour:
  • An agent mid-streamText aborts 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.
This is the escape hatch for runaway multi-agent conversations — cheaper and safer than cancelling every in-flight action individually. Wire the same action into any custom chat UI; the mutation is 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 project instead.
  • Dispatch modality matches the cost tolerance. broadcast on a 10-agent channel will burn tokens fast. Default to relevance_gated for anything bigger than a panel of three.
  • Loop depth is set. A multi-agent channel without maxAgentLoopDepth will eventually loop. Default to 3.
  • Tool-call rendering is wired. If your custom UI hides ToolCard rows, 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 the FORGE_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

This needs chat:read. A page can be short while meta.hasMore is true; follow meta.nextCursor to read on.
2

Open the session

This needs 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

Posting needs 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.
Over MCP, forge_call_operation posts the same message. It is in the default start job:

See also