Bots and behaviour

A bot is a configured chat partner that answers with one behaviour, its repositories and its features. You build bots in the Library (/app/library), and people choose one when they start a chat.

Library viewsCopy Anchor Link

The Library (/app/library) has five views, listed in its rail with their counts:

• Overview (/app/library)
• Bots (/app/library/bots)
• Behaviours (/app/library/behaviours)
• Repositories (/app/library/repositories)
• Assets (/app/library/assets), described in Library

Library is one item in the sidebar, and the rail switches views. Every role can browse it. Browsing the Library describes how to search, filter and narrow it to your own items.

Core conceptsCopy Anchor Link

• Bots are configured chat partners that people choose when they start a chat.
• Blocks are behaviours and repositories, and bots and chats can reuse them.
• A behaviour's system prompt sets the bot's role, tone and limits. The bot answers in the language the user writes in unless the system prompt names one. OrcAI's rules for citations and formatting apply whatever the system prompt says.
• A repository holds assets with its retrieval settings.
• Assets are uploaded files that can go into repositories and be attached to chats.

A bot fixes no quota pool, and it fixes a model only when its Model step requires one. Each chat runs on the provider and model chosen in that chat, and usage is charged to the quota pool that covers the chatting person and that provider.

Bot lifecycleCopy Anchor Link

Bots (/app/library/bots) have draft and published states. The Bots view lists the published bots you can read and the drafts you can edit, newest first. Drafts have a faded band and a Draft badge. The Status filter narrows the list to Published or Drafts, and Only favourites to your favourites.

New > Bot appears for roles with create_bot (admins, managers and members).

A bot is private until it is shared. Publishing does not share it, so a published bot is usable only by the people and groups it was granted to. Listing it in the Catalogue lets everyone preview it, together with its behaviour and repositories. See Access control.

The bot pageCopy Anchor Link

A bot's page (/app/library/bots/<bot id>) shows its behaviour and repositories, and a Model in … card with the bot's model in the active organisation and whether it is recommended or required, or a note that chats pick any model. Its editors also see how many of the people and groups it is shared with have a quota pool for that model, and everyone else whether they can use it. A model that was deleted or cannot serve chats is marked Model missing. Depending on your role on the bot, the page offers:

• Start chat, for anyone who can use the bot
• Edit bot, which opens the editor
• Access & groups, which opens the access dialog
• Delete bot, in the More actions (…) menu. The chats with the bot stay with their owners but become read-only

A bot your organisation added from the Catalogue shows "From" its home organisation and is edited and deleted only there. Its admins and managers share it for use with Access & groups and take it out of the organisation with Remove from ….

On every detail page, frequent actions are buttons in the header, and rare or destructive ones sit in the More actions menu.

FavouritesCopy Anchor Link

The Favourite star on a published bot's card and next to Start chat on its page adds the bot to your favourites, and selecting it again removes it. Favourites are personal, so nobody else sees them.

Your favourites show up in four places:

• The Favourites shelf on the Library's Overview
• The Bots view with Only favourites
• The first one as the large card under Try something on the home page
• In a Favourites group above All bots when you choose a bot for a new chat, until you search

A favourite disappears while you cannot read the bot or while it is unpublished, and comes back when it is shared with you or published again.

Creating or editing a botCopy Anchor Link

New > Bot opens the editor at /app/library/bots/add. The first save creates a draft and moves the editor to /app/library/bots/<bot id>/setup, the same place Edit bot opens. The later steps unlock after that first save, and moving between steps saves your changes. The editor creates new blocks inline or links existing ones from the Library, and linked blocks you cannot edit appear read-only.

The bot editor is a guided wizard with six steps:

Bot basics [step]Copy Anchor Link

Name the bot and give it a short description and a longer Bot description for teammates who maintain it, written in the rich text editor.

Behaviour [step]Copy Anchor Link

Write a new behaviour, start from an example, or choose Use existing behaviour. The system prompt has no default. Write a behaviour explains what to put in it.

Below the behaviour, the Features section lists the built-in features the bot can enable. See Features.

Repositories [step]Copy Anchor Link

Attach published repositories that provide retrieval context. Repositories are optional: create one, choose Add existing repository, or attach none.

Sharing and access [step]Copy Anchor Link

Choose whether the bot is listed in the Catalogue, and configure groups and direct grants for the intended audience. Giving someone Can edit or Can manage on the bot also offers Can edit on its blocks, for the blocks you can share.

Model [step]Copy Anchor Link

Optionally recommend or require a model for the bot's chats in the active organisation, with Save model. Skip the step and people pick any available model. Models, quota pools and groups belong to one organisation, so the model is set per organisation. The bot's editors set it in the organisation the bot was created in. Where an organisation added the bot from the Catalogue, its admins and managers set it there with Edit on the bot's Model in … card. Remove model returns the bot to a free pick.

• Recommended (the default) starts new chats on the model and its settings, and people can switch. Later changes reach only new chats.
• Required decides every chat, so the model and settings cannot be changed in the chat, and your changes reach existing chats too. If the model is deleted, its provider is disabled, it is deprecated, it cannot call tools, or no quota pool covers it for someone, their chats with the bot are blocked with a notice until you choose another model or an admin adds a pool.

Advanced generation settings (temperature, top P, max tokens and the penalties) are optional, as in chat settings, and unset ones keep the provider's defaults.

Quota coverage lists the people and groups the bot is shared with in this organisation and whether a quota pool covers the model for each, through their group or All members. It only warns, so you can save either way. Admins get a link to Quota pools. Only the bot's editors see the list, and only the groups and email addresses they may see elsewhere.

Review and publish [step]Copy Anchor Link

Review the publishing checks, then choose Save draft to keep the bot as a draft or Publish bot. Publishing asks for confirmation and summarises who gains access, how the provider and model are chosen, and that the bot fixes no quota pool.

FeaturesCopy Anchor Link

Features are built-in capabilities that work alongside the behaviour and repositories. They belong to the bot and not to its behaviour, so switching the behaviour keeps the bot's features and the same behaviour can be used with or without them. Each feature is a switch in the Features section of the Behaviour step and is saved with the bot.

Generative UI lets the model show structured results, such as checklists, in its answer. It is on by default for new bots. See Generative UI.

Web search lets the model search the web and cite the pages it used, as the organisation's web search setting allows. It is off by default. Allowed domains limits the search to those domains and their subdomains, such as example.org, and with none it searches the whole web. While the organisation's web search is off, or the setting is the model's own search and the chat's model has no search of its own, the chat shows a notice and the bot answers without searching. See Web search.

Questions and quizzes lets the model ask you structured questions in the chat and run quizzes it grades. It is off by default. See Questions and quizzes.

Chats started from the bot use the bot's features, and the chat settings cannot change them.

Bot cards and the bot page show the bot's enabled features.

Publish readiness rulesCopy Anchor Link

Publish bot stays disabled until:

• A behaviour is linked
• The behaviour is Published
• Every linked repository is Published
• Every linked repository has at least one attached asset

Assets that are still being prepared or that failed do not hold publishing back. When a linked repository has such assets, the publish confirmation adds an Assets note per repository, for example "Handbook: 38 of 120 assets ready. 2 failed.", since only ready assets are searchable. A repository linked read-only in the editor marks each asset that is not ready with its state.

Block typesCopy Anchor Link

A block is a behaviour or a repository, and a bot links one behaviour and any number of repositories. New > Behaviour opens /app/library/behaviours/add, and New > Repository opens /app/library/repositories/add. Both need create_block.

Each block has a publication status, Draft or Published, with its metadata and a version. It can be listed in the Catalogue and shared through grants, and your access to it decides whether you can edit or delete it and manage its access.

A block's page sits under its kind, at /app/library/behaviours/<block id> or /app/library/repositories/<block id>, and a block opened under the other kind's path is not found. It offers Edit block (<page>/edit) and Access & groups, with Delete block in the More actions menu.

Detailed descriptionsCopy Anchor Link

The Bot description of a bot and the Detailed description of a behaviour or repository are rich text, for the people who maintain them. The bot's page and the block's page show them, and the model does not read them. A behaviour's System prompt stays plain text.

A toolbar above the text has, in this order, undo and redo, headings, bold, italic, underline, strikethrough, inline code, Text colour and highlight, links, bulleted and numbered lists, quotes, alignment, the inserts Insert table, Insert YouTube video and Horizontal rule, and Clear formatting. On a phone the toolbar scrolls sideways. Selecting text also opens a smaller menu with the paragraph type, the text styles and the alignment.

A new table has three rows and three columns with a header row. Clicking into a table opens a menu that adds and deletes rows and columns, merges and splits cells, and deletes the table. Insert YouTube video takes the link to a video, and pasting such a link on its own line embeds it as well. Videos play from youtube-nocookie.com, YouTube's privacy-enhanced mode, and fill the width of the text.

The repository pageCopy Anchor Link

A repository's page lists its attached assets and its retrieval configuration:

• Retrieval mode: Dense, Sparse or Hybrid
• Passages per answer: Minimum, Default and Maximum
• Passages per asset, Candidate limit and Score threshold, under the advanced settings

Passages per asset keeps one long asset from crowding out the others, because a search takes at most that many passages from each asset first. When that leaves the results short, the best remaining passages fill the free places.

Above the assets of a published repository, Explore opens its passages at /app/library/repositories/<block id>/explore.

Each asset card shows its state in this repository: Queued, Processing (the file is read), Indexing (its passages are added to this repository's index), Ready or Failed. Only Ready assets are searchable. A summary above the cards says how many of the repository's assets are ready and how many failed, and refreshes while assets are being prepared. A failed card says why. If you can edit the repository, Retry on a failed card runs the failed step again, which is reading the file when that failed and otherwise indexing in this repository. Prepare failed assets again next to Explore retries every failed asset at once. Neither is offered for a file OrcAI cannot read or one without any text or images, since retrying cannot help.

Exploring a repositoryCopy Anchor Link

Explore shows the passages a published repository's assets were split into, 50 at a time with Load more:

• With All assets, passages of every asset, in no particular order.
• With one asset chosen, its passages in reading order: page by page, the images of a page after its text.
• A search shows the best matches first, as many as Top 10, Top 25 or Top 50, with each passage's score, using the retrieval mode you choose (Hybrid, Dense or Sparse). Unlike a bot's search, it does not limit how many passages come from one asset.

The search, mode, asset and result count are kept in the page's address, so a link opens the same view.

Use it to:

• Check passage quality
• See how each retrieval mode behaves
• Find missing or weak results before you attach the repository to bots

Sharing and accessCopy Anchor Link

Bots, blocks and assets expose the same access dialog, Access & groups, for the Catalogue listing, groups, and direct grants. The bot editor's sharing step embeds it.

A grant gives one of three roles:

• Can view can find, use and read the bot, block or asset. On a bot this is enough to chat with it.
• Can edit can also edit it.
• Can manage can also delete it and manage its access.

The owner of a bot, block or asset holds every action on it. Whoever creates it owns it until they hand it over. Access control has the details, including how access passes from a bot to its blocks and assets.

For a full setup sequence from assets to a published bot, see Organisation setup.