How Halo Works - HaloAgents

The four building blocks

Halo is intentionally composable. Once you understand these four concepts, every screen in the dashboard maps cleanly to one of them:

Concept	What it is	Lives at
Agents	Configurable AI personas with instructions, skills, escalation rules, and connected tools.	AI Agents in the sidebar
Channels	Where an agent runs: the web widget, an email mailbox, a Slack workspace, your help center.	Each agent’s Channels tab
Knowledge	What the agent can search and cite: docs, files, help articles, distilled meeting transcripts.	Knowledge in the sidebar
Context	Live data about the current user: traits, company, integration status, errors, metrics.	Sent via the Web Widget or API

Everything else — Inbox, Automation, Integrations, Help Center — sits on top of these four primitives.

Agents

An agent is a row in your workspace with its own configuration. You can have multiple agents and Halo picks the right one based on the channel a message arrives on. Each agent has:

Instructions — system prompt that defines tone, voice, scope, do’s and don’ts.
Skills — capabilities turned on for that agent: knowledge search, web search, UI highlighting, ticket creation, voice mode, video avatar (Live Help).
Channels — where the agent answers: web widget, email mailbox, Slack channels, the help center widget.
Actions — things the agent can do besides answering: create a HubSpot deal, log a Linear bug, request a billing change, post to Slack.
Escalation rules — when and how to hand off to a human, including who to assign tickets to and which segments get priority.
Style — colors, avatar, trigger icon, greeting, suggested messages.

Agent types include customer_facing (the default), internal (team-facing), sales, and help_center (powers the chat on your published help center). Most teams start with one customer-facing agent and add more as they grow. See AI Agents Overview for the full breakdown.

Channels

A channel is a deployment of an agent. The same agent can run on multiple channels, or you can dedicate one agent per channel. Built-in channels:

Web widget — installed via a script tag on your site or app. Includes chat, voice, and Live Help (real-time video avatar) modes.
Email — every workspace gets a default [email protected] inbound address. You can also add verified custom domains so emails come from [email protected].
Slack — connect your workspace and map channels to agents so the AI replies in-channel.
Help Center — the chat widget embedded on your published help center site.

Channels are where incoming messages enter Halo. Once a message arrives, the agent assigned to that channel takes over.

Knowledge

The agent’s brain. There are several ways to add knowledge:

URL sources — point Halo at your help center or docs site and it crawls every page, including images, video transcripts, and meta descriptions.
File uploads — PDF, Markdown, plain text, CSV, HTML, JSON, XML. Useful for runbooks, internal SOPs, exported KB articles.
Internal docs — write articles directly in the dashboard.
Help Center articles — every published help center article is automatically indexed for the AI (unless you opt out).
Synced from integrations — HubSpot engagements, Zoom and Fathom transcripts, PandaDoc contracts, Intercom history, and Slack channel history can all be ingested as knowledge.

Halo uses a dual-chunking strategy (small precise chunks for matching, larger parent chunks for context) and Voyage AI embeddings for semantic search. Re-ingestion is incremental — unchanged content is skipped via content hashing. A separate concept called Learning Rules lets you tell the AI what topics to learn from synced data and what to ignore. See Learning Rules for details.

Context (the part that makes Halo Halo)

Context is the live data your app pushes about the current user. It’s the difference between answering “I don’t know what your Stripe setup looks like” and “Your Stripe integration’s webhook hasn’t fired in 6 days — let’s check the endpoint.” There are three kinds of context:

Kind	Use it for	Set via
User traits	Who the user is: name, email, role, plan, custom flags	`identify()` in SDK or /users/identify
Company traits	Their company: name, plan, MRR, employee count, renewal info	`identifyCompany()` or /companies/identify
Context entries	Their current state: integration status, active errors, usage metrics, feature flags	`setContext()` or chat request body

Context flows two ways:

Stored — when you call identify(), traits and context land in the user’s record. Every future message sees them.
Per-request — every chat call can include fresh context that overrides stored data. Useful for things that change between page loads.

See Contacts & Companies Overview for the full data model and Planning Your Context Strategy for how to design what you send.

A message, end-to-end

Here’s what happens when a user types “Why isn’t my Slack integration working?”:

Channel routes the message

The widget posts to /api/sdk/chat/stream with the user’s session, context, and message. Halo identifies the channel (web widget) and looks up the agent assigned to it.

Context gets merged

Halo loads the user’s stored traits + company + context, merges in any per-request context from the SDK, and renders it as structured text in the system prompt:

[User Profile]
Name: Jane Doe, Plan: Pro, Role: Admin

[Connected Integrations]
- Slack: connected, ERROR -- channel mapping missing
- HubSpot: connected, active

Agent picks tools

The agent’s instructions, skills, and registry actions are turned into AI tools. For this question, knowledge search runs first to find docs about Slack channel mapping.

Agent responds (or acts)

The agent streams back a response and may invoke tools — highlight the channel mapping setting in your UI, create a Linear ticket if it detects a bug, or escalate by creating a Halo ticket if confidence is low.

Activity flows to the inbox

The conversation appears in Inbox > Conversations in real time. If the agent escalated or the user asked for a human, a ticket is created with the full transcript attached and routed by your escalation rules.

What the rest of Halo adds

Once the basics are in place, Halo’s other features layer on:

Inbox — your team’s view of every conversation and ticket. Includes filters, segments, custom inboxes, internal notes, and AI-drafted replies.
Automation — broadcasts (one-shot emails), series (multi-step sequences), in-app messages, and banners. Triggered by events, segments, manual activation, or the API.
Help Center — a hosted, themeable, customer-facing knowledge site with collections, articles, AI editor, SEO, custom domains, and analytics. Articles auto-feed your AI.
Integrations — bidirectional connections to HubSpot, Slack, Stripe, Linear, Intercom, Zoom, Fathom, and PandaDoc. Each can ingest data, expose actions to agents, and/or send notifications.
Contacts & Companies — every user and company you identify shows up here with profiles, conversation history, health scores, renewal data, and editable fields.

Where to go next

Quickstart

Install the widget and ship your first AI conversation.

Setup Checklist

The full setup journey end-to-end.

AI Agents

Configure your first agent’s instructions, skills, channels, and escalation.

Web Widget

Install the widget and start sending user context.

​The four building blocks

​Agents

​Channels

​Knowledge

​Context (the part that makes Halo Halo)

​A message, end-to-end

​What the rest of Halo adds

​Where to go next