Skip to main content

Swarms

A swarm is a group of agents that a user chats with together in a chat room. Swarms are private: each swarm belongs to the person who created it, and only that person can see, edit and chat in it. The Swarms page (/admin/swarms) is therefore a read-only oversight list for administrators: you see every swarm in the instance and can delete it, but you cannot open or edit it. How a swarm behaves in conversation is covered by the Swarm chat concept.

note

Swarms are not the same as teams: a team is a group of people with a shared workspace, a swarm is a group of agents.

Swarms administrationSwarms administration

The swarm list​

The overview shows all existing swarms in a table with the columns:

ColumnDescription
NameThe swarm's name
OwnerThe person who created the swarm. Your own swarms show as You; swarms created before swarms became private show No owner (created before swarms were private)
MembersThe number of swarm members

Rows are not clickable: the right to list and delete swarms does not grant read access to someone else's swarm. When there are no swarms yet, the page shows No swarms yet.

If the feature is not enabled for your instance, the page shows Swarms are not enabled for this instance instead. Swarms are a premium feature.

Deleting a swarm​

The row action Delete removes a swarm together with all of its conversations. A confirmation ("Delete swarm?") guards against mistakes; deleting cannot be undone.

Who creates and uses swarms​

Swarms are not created in the admin area but by users themselves:

  • Anyone with the Create swarms permission (team:create) sees a Swarms section in the left sidebar with a New swarm button. Administrators have the permission anyway.
  • In the dialog you give the swarm a Name, choose its Agents (only agents you may use are offered) and pick which one is the Lead. At least one agent and a lead are required.
  • The swarm then appears in the creator's sidebar and is reachable at /swarm/<swarm-id>. Other people, administrators included, get "Swarm not found" there.

The Manage swarms permission (team:manage) is a narrow tenant-wide lever: it lets you list every user's swarms and delete any of them, but not read them or chat in them.

Hop cap and cost ceiling​

Two per-turn limits can be stored on a swarm. The dialog in the interface has no fields for them; they are set through the management API as the swarm's hopCap and costCeiling fields:

  • Hop cap (hopCap): the maximum number of member activations per turn.
  • Cost ceiling (costCeiling): the maximum total token usage per turn.

For both, 0 = unlimited. If a limit is reached during a running conversation, BasePeak.AI stops the turn automatically and leaves a system notice in the room (e.g. "Stopped: hop cap reached (5 / 5).") instead of running on unchecked. Values that are set are preserved when the swarm is edited in the interface.

A member always runs with the own knowledge and own tools of the underlying agent. You assemble a swarm from existing agents; their configuration stays unchanged and is reused for the swarm chat.