> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Talk to agents

> Wire chat into your product — channels, sessions, dispatch modalities, relevancy gating, personal agents. The build-side surface for hybrid workforce conversations.

Last updated 2026-11-11

·
applies to 2026-05-11

·
main

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](https://docs.gloo.com/forge/concepts/workforce.md). For the architectural picture of the dispatch path, see [Agent dispatch](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch).

When to reach for something else

If your product already has its own chat substrate (Intercom, Crisp, your homegrown UI) and you only need an agent to *answer* — not to be governed, audited, or coordinated with other agents — call the Platform API's chat endpoint and skip the channel/session model entirely. Channels exist because Forge needs a stable place to attach memory, governance, syndication, and entity links. If your conversation is a one-shot Q\&A, it's overkill. If your conversation will involve multiple agents, persist across sessions, link to a workflow run or task, or syndicate to Slack — channels are the right abstraction.

***

## 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.

CHAT — TWO LEVELS, SIX BEHAVIORS

<ol aria-label="CHAT — TWO LEVELS, SIX BEHAVIORS" />

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 | Owner | Typical use |
| - | - | - |
| `factory` | Factory | Team-wide channel created during factory provisioning. Purposes: `requests`, `support`, `general`, `engineering`, `custom`. |
| `project` | Project | Cross-factory channel attached to a specific initiative. |
| `team` | Team | Department or functional team room. |
| `direct` | Two users | 1:1 DM between humans. Each participant's Personal Agent is auto-added. |
| `personal` | One user | Private channel between a user and their Personal Agent. |
| `group` | Ad-hoc | Multi-party channel not tied to a structural entity. |
| `system` | System | Framework-owned channels (Workflow Architect drafts, platform notifications) — filtered from the user's `/chat` sidebar. |

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:

| Modality | Behavior |
| - | - |
| directed | **Default.** Message addressed to a specific agent — explicit @mention or DM. Only the targeted agent is dispatched. |
| relevance\_gated | Multi-agent channels. Every assigned agent is scored against the message; only those above their threshold reply. |
| round\_robin | Agents take turns. Useful for structured panels or review boards where every voice should speak in order. |
| broadcast | Every assigned agent replies to every message. Reserved for small panels — cost grows linearly. |

**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.

### Recommended defaults

| Channel kind | Mode | Threshold | Loop depth |
| - | - | - | - |
| DM (single agent) | `heuristic` or `hybrid` | `0.0` | n/a |
| Factory `general` (many agents) | `hybrid` | `0.5` | `3` |
| Specialist panel (3–5 focused agents) | `hybrid` | `0.6` | `5` |
| Broadcast channel | — | — | `2` |
| Experimental / noisy | `llm` | `0.7` | `3` |

***

## 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](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-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](https://docs.gloo.com/forge/concepts/workforce.md). For the dispatch and memory mechanics, see [Agent dispatch](https://docs.gloo.com/forge/architecture/system-overview.md#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:

```typescript theme={null}
// 1. Provision the agent (idempotent — safe to call on every user login)
const provisionRes = await fetch("https://api.forge.gloo.com/api/v3/agents/find-or-create", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${appToken}`,
    "X-Forge-User-JWT": userJwt,        // your app's JWT for the current user
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentType: "PERSONAL",
    name: `${user.displayName}'s Assistant`,
    model: { default: "claude-sonnet-4-5" },
  }),
});
const { data: { agent } } = await provisionRes.json();
// provisionRes.status === 201 → first time; 200 → returning user

// 2. Discover available models for the agent
const modelsRes = await fetch(
  `https://api.forge.gloo.com/api/v3/agent-available-models?agentId=${agent.agentId}`,
  { headers: { "Authorization": `Bearer ${appToken}` } }
);
const { data: models } = await modelsRes.json();
// models → [{ id: "claude-sonnet-4-5", object: "model", ... }]

// 3. Send completions to the agent
const completionRes = await fetch("https://api.forge.gloo.com/api/inference/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${userToken}`,   // user-scoped inference token
    "X-Forge-Agent-Id": agent.agentId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "claude-sonnet-4-5", messages: [...] }),
});
```

`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.

Scopes required

`findOrCreateAgent` requires `agents:write` scope on your external application. `listAvailableModelsForAgent` requires `agents:read`. An app's authority is its role grants: give the app a role that carries both (`POST /api/v3/governance-holders/{holderId}/roles` with `actorKind: "external_app"`, or the Console's Access page). `PATCH /api/v3/external-apps/{externalAppId}` cannot write `allowedScopes` (`400 allowed_scopes_removed`).

Full reference: [findOrCreateAgent](https://docs.gloo.com/forge/reference/http-api/external/findOrCreateAgent.md) · [listAvailableModelsForAgent](https://docs.gloo.com/forge/reference/http-api/external/listAvailableModelsForAgent.md) · [External App endpoints](https://docs.gloo.com/forge/reference/http-api/external.md)

***

## 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](https://docs.gloo.com/forge/reference.md). 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](https://docs.gloo.com/forge/reference.md).

***

## 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.

| Source | How it's authored |
| - | - |
| **Builtin skills** | Add a `slashCommand:` block to the skill's `forge.yaml`, including its `riskLevel`. Forge registers the declaration as a slash command when it syncs the built-in skills. A block with no `riskLevel` fails skill generation, and the sync does not register it: nothing defaults it to `read`. |
| **Workspace skills** | Configure in the skill editor in Forge Console; the skill update mutation creates or updates the `chatSlashCommands` row atomically. |
| **Tools** | Add a `slashCommand` field to the `toolDefinitions` row. Risk level inherits from the tool's `riskLevel`. |

### 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:

| Risk Level | Default | Override |
| - | - | - |
| `read` | Allowed | Disable via `slashCommandDisabled` on the assignment |
| `write` | Denied | Requires explicit enable |
| `financial` | Denied | Requires explicit enable |
| `destructive` | Denied | Requires explicit enable |

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](https://docs.gloo.com/forge/run/webhooks.md) 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](https://docs.gloo.com/forge/quickstart.md). 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](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) 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**

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/chat-channels?scope=project&status=ACTIVE&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {id, name, scope, activeSessionCount}'
```

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

**2. Open the session**

```bash theme={null}
SESSION_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/chat-channels/$CHANNEL_ID/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: march-close-session-v1" \
  -d '{"title": "March close questions"}' \
  | jq -r '.data.id')
```

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**

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/chat-sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: march-close-session-message-1-v1" \
  -d '{"content": "Which entities are still open for March?", "contentType": "text"}' \
  | jq '.data.messageId'

curl -sS "$FORGE_BASE/api/v3/chat-sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {role, agentName, text, authoredByCaller}'
```

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:

```json theme={null}
{
  "operationId": "sendChatMessage",
  "idempotencyKey": "march-close-session-message-1-v1",
  "input": { "sessionId": "<session id>", "content": "Which entities are still open for March?", "contentType": "text" }
}
```

***

## See also

* [Define an agent](https://docs.gloo.com/forge/build/define-an-agent.md) — the rows that fill your channel
* [Author a skill](https://docs.gloo.com/forge/build/author-a-skill.md) — the guidance the agents in your channel will follow
* [Workforce concept](https://docs.gloo.com/forge/concepts/workforce.md) — why agents are workers, why every conversation has a session
* [Agent dispatch](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) — how agent turns are dispatched
* [Forge API](https://docs.gloo.com/forge/reference.md) — the channel/session/message endpoints
* [HTTP API reference](https://docs.gloo.com/forge/reference.md) — for products integrating with Forge
* [Console — Chat](https://docs.gloo.com/forge/console/chat.md) — the operator walkthrough of the Bell


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.