Owlish Docs

Concepts

The four primitives in Owlish — agents, knowledge, sessions, channels — and how they relate. Worth skimming before you build.

Owlish’s mental model is small on purpose. There are four primitives and they always relate the same way. If you understand this page, the rest of the docs is recipes.

Agents

An agent is a configured behavior — a persona, an instruction set, a chosen model, and a set of attached knowledge and actions. Agents are not chat sessions; they’re the configuration that drives chat sessions. You can have many agents in a workspace (e.g., a public support bot, an internal IT helpdesk, a sales qualifier).

Knowledge

Knowledge is everything the agent can ground answers in. It’s organized in folders, and each folder contains sources: websites, files (PDF, DOCX, CSV), or Direct Response answers (a question plus a canonical reply). Sources are ingested asynchronously, chunked, embedded, and made available to any agent that has access to that folder. Citations on agent answers always point back to a specific source.

Knowledge base sources table with folders, status, type, last-updated date, and attached agents.

Sessions

A session is one continuous conversation between a visitor and an agent — could be 2 messages, could be 50. Sessions are durable: every message is stored as a session_event, and reopening the same session continues where it left off. The Helpdesk inbox is the master list of all sessions across all channels.

Channels

A channel is where a session happens. The same agent can answer on the web widget, in Slack, in Teams, in Discord, in email — each one is a channel binding on the agent. Channels look different (Slack threads vs. a chat bubble) but they all produce sessions in the same shape, which is why everything ends up in one inbox.

How they fit together

Workspace
└── Agent (config)
    ├── Knowledge folders ── sources ── chunks
    ├── Channel bindings ── widget, slack, teams, …
    └── Sessions ── events (user/agent messages, citations, handoffs)

The relationships are deliberately one-way: knowledge feeds the agent, the agent runs on channels, channels produce sessions, and sessions live in the Helpdesk. There are no implicit links between, say, a Slack channel and a knowledge folder — everything goes through the agent.

Next steps