Bots - Allternit Docs

Overview

Bots are packaged Allternit agents: the same runtime engine as any agent, but wrapped with a user-facing identity, discovery surface, and autonomous primitives. Every bot is an agent, and every agent can be packaged as a bot. Bots appear in the Bot Hub (inside Agent Studio), the CommRails left rail, the chat composer, and as @mention targets. Once running, a bot session exposes work progress, gate reviews, deliverables, activity history, and a virtual computer that can be paused, observed, or taken over.

Packaged identity

A bot is an agent plus a botProfile with display name, tagline, welcome message, starter prompts, and accent color.

Autonomous runtime

Connectors, vault secrets, identity channels, messaging, and a virtual computer are resolved at session start.

Multi-bot collaboration

Group chats, swarm consensus, A2A delegation, and subagent families let bots hand off work.

Observable work

WIH progress, gate reviews, deliverables, ledger events, and an activity stream keep humans in the loop.

Bot vs Agent

Allternit uses Agent as the execution primitive and Bot as the packaged, user-facing instance of that primitive.

	Agent	Bot
What it is	The autonomous execution entity: model, harness, tools, skills, character, trust tier, workspace.	A curated identity layer on top of an agent, ready for end users.
Created in	Agent Studio	Agent Studio — the same wizard, with a Bots filter and a Create Bot CTA.
Discovered in	Agent Hub, Swarms, A2A registry, Teammates roster	Bots Hub, composer `@` mentions, bot session launcher, CommRails.
Identity	`name` (system handle / `@` handle), `description`, `characterLayer`.	`botProfile.displayName`, tagline, accent color, category, welcome message, starter prompts.
Can run autonomously	Yes	Yes — it is an agent.
Can be @mentioned	Only if packaged as a bot	Yes — this is the bot UX entry point.

One-line rule: Every Bot is an Agent; not every Agent is a Bot. The canonical contract lives in surfaces/ai.allternit.com/src/lib/bots/BOT_AGENT_CONTRACT.md and is enforced by validateBot() in src/lib/bots/bot-contract.ts.

Bot Hub and discovery

Agent Studio / Bot Hub

Bots are authored and discovered inside Agent Studio. The studio header has an All / Bots / Agents filter and a context-aware Create Bot / Create Agent button. Selecting Bots shows every agent where isBot === true. Bot cards use:

botProfile.displayName
tagline
accentColor
@name handle
botCategory

Clicking a bot opens its Bot Home (viewType: bot-home), a dedicated management surface for that bot.

CommRails Bots panel

The CommRails left-rail surface aggregates active bot sessions, group chats, and WIH summaries. It exposes two dynamic sections:

Section	Type	Contents
Bots	`bots`	Active bot sessions with status (`idle`, `running`, `paused`, `completed`, `error`), WIH id, badge count, and accent color.
Groups	`groups`	Active bot group chats with member count, strategy, and consensus threshold.

The panel is backed by useCommRailsStore (src/lib/bots/comrails-store.ts) and persists to local browser storage. Inside the chat surface, a collapsible Bot Roster Sidebar lists every bot the user owns. Each row shows the bot avatar, display name, and @handle, with hover actions:

Open Bot Home
Start session
Open Inbox
Edit
Duplicate

The composer also has a Bot pill/tab. Turning it on opens the bot picker; the selected bot is rendered as an @BotName pill, and sending a message starts or continues a bot session.

Bot Session View

A bot session is a regular agent session with metadata.isBot = true, metadata.botProfile, and the bot’s autonomous primitives copied in. The session view contains:

Welcome card

When a bot session is empty, the chat surface renders a welcome card using the bot’s welcomeMessage and a set of clickable starterPrompts. In the Bot Home, the same welcome message and prompts are shown as quick-start chips.

{
  displayName: "A://",
  tagline: "Allternit's all-knowing oracle",
  welcomeMessage: "I am A://, Allternit's oracle. Ask me anything...",
  starterPrompts: [
    "Explain how CommRails coordinates multi-agent workflows.",
    "How do I create a bot group with consensus-based decision making?"
  ],
  accentColor: "#6366f1",
  groupChatEnabled: true
}

Agent Context Strip

Bot sessions render an Agent Context Strip above the chat with four drawers:

Drawer	Contents
Workspace	Session scope, tags, canvas count.
Tools	Tools available to the bot.
Automation	Runs and cron status.
Runtime	Resolved env vars (harness, secrets, connectors), connector bindings, secret refs, and missing required keys.

The Runtime drawer mirrors the Runtime tab in Bot Home, so users can verify exactly what the bot can access while it is running.

WIH progress

Bots participate in CommRails DAG/WIH work. A WIH (Work-In-Hand) tracks a node of work through its lifecycle:

Status	Meaning
`open`	Work item created but not yet picked up.
`ready`	Ready for pickup.
`signed`	Picked up and signed by an agent.
`in_progress`	Currently executing.
`blocked`	Blocked by dependencies or policy.
`closed` / `archived`	Completed or cancelled.

The Bot Home Tasks tab lists every session/task scoped to the bot, grouped by date, and the CommRails bot row can surface the active wihId and badge count.

Gate review

When a bot’s work crosses a policy gate, a review request is emitted to the Rails ledger and surfaced in Agent Activity. Review threads can be:

Code-diff reviews — linked to a diffRef.
Decision reviews — a plain human approval/denial ask.

From the Agent Activity detail view, operators can Approve (key 1) or Deny (key 2). The decision is recorded as a ReviewDecision ledger event. Gate endpoints are exposed through the Rails API:

Method	Path	Description
`GET`	`/rails/gate/status`	Current gate status.
`POST`	`/rails/gate/check`	Check if an action is allowed.
`POST`	`/rails/gate/decision`	Submit a gate decision.

Deliverables

Bot outputs are collected as artifacts and canvases. The Bot Home Artifacts tab shows code, markdown, diagrams, browser captures, and images produced across all sessions. Artifacts are extracted from agentElementsParts on assistant messages. When a WIH is closed, the bot can attach evidence (links, files, verification steps) via the WIH close request:

POST /rails/wihs/{wih_id}/close
Content-Type: application/json

{
  "status": "completed",
  "evidence": ["https://ci.allternit.com/run/123", "agents/bot_abc/report.md"]
}

Bot automation

Bots can own scheduled and recurring work through the Automation API and the bot-scoped Routines panel. The three primitives are:

Primitive	Scope	Purpose
Goal	Platform-owned	A long-term objective that groups routines and loops.
Routine	Persistent	A scheduled job (cron, interval, manual, once).
Loop	Session-scoped	A recurring job tied to a session, optionally expiring.

Automation API

Base URL:

https://api.allternit.com/api/v1/automation

Key endpoints:

Method	Path	Description
`GET` / `POST`	`/api/v1/automation/goals`	List / create goals.
`GET` / `POST`	`/api/v1/automation/routines`	List / create routines.
`POST`	`/api/v1/automation/routines/:id/run`	Trigger a routine immediately.
`GET`	`/api/v1/automation/routines/:id/runs`	List routine runs.
`GET` / `POST`	`/api/v1/automation/loops`	List / create loops.
`GET`	`/api/v1/automation/local-schedules`	List local-domain schedules.

Routines and loops can execute in local or cloud domains. Cloud schedules are dispatched through the Gizzi cron daemon.

Example: create a bot-scoped routine

curl -X POST https://api.allternit.com/api/v1/automation/routines \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily standup summary",
    "schedule_type": "cron",
    "schedule_expression": "0 9 * * *",
    "execution_domain": "cloud",
    "agent_id": "agent_550e8400",
    "config": { "jobType": "agent" }
  }'

The Bot Home Automation Tasks tab and the bot session Routines side pane both render routines scoped to the active bot via agent_id.

Multi-bot collaboration

Bot group chat

Bots can be added to persistent group conversations. A group is defined by:

id, name, status
members — bot id, display name, SwarmRole, weight, status
strategy — swarm coordination strategy
consensusThreshold — default 0.6

The useBotGroupStore (src/lib/bots/bot-group-store.ts) manages group creation, membership, and per-member status updates. Groups appear in the CommRails Groups section. A bot must have botProfile.groupChatEnabled === true to be added to a group.

Swarm consensus

Group strategies map to SwarmStrategy values:

Strategy	Behavior
`round-robin`	Each member takes a turn.
`hierarchical`	Leader delegates to workers.
`democratic`	Voting-based decisions.
`competitive`	Agents compete; best result wins.
`collaborative`	All agents work together.
`specialist`	Route to a specialist based on task.
`adaptive`	Dynamic strategy based on context.

Swarm roles include leader, worker, critic, planner, specialist, and observer. A swarm can be represented as a single agent via swarmToAgent() (src/lib/agents/swarm-as-agent.ts), giving it an agent card and making it @mentionable.

A2A delegation and subagents

Bots delegate work through agent-to-agent (A2A) messaging. The useA2ADelegation hook handles three cases:

Swarm agent — @swarm_<id> starts a swarm run.
Delegating agent — an agent with agentCard.canDelegate === true receives an A2A direct message.
Regular agent — no delegation layer; message is routed directly.

// Mention a delegating bot in chat or another bot's inbox
@code-reviewer review this diff

Subagents are declared with parentAgentId on the agent record, or modeled through SubagentConfig in src/lib/agents/agent-advanced.types.ts. The bot family tree is derived from:

parentAgentId — direct parent/child relationships.
agentCard.canDelegate — which agents may spawn subagents.
relationships on AdvancedAgentConfig — typed relationships (parent, child, peer, depends-on, delegates-to).

A2A and direct messages are routed through the agent communication store and Rails mail endpoints:

Method	Path	Description
`POST`	`/rails/mail/threads`	Ensure/create a thread.
`POST`	`/rails/mail/send`	Send a message.
`GET`	`/rails/mail/inbox/:agent_id`	Poll an agent’s inbox.
`POST`	`/rails/mail/review`	Request a review.
`POST`	`/rails/mail/decide`	Approve or deny a review.

Computer attachment, idle, and takeover

A bot can be configured with a virtual computer through vmOperator on the agent record. This lets the bot run commands, operate browsers, read/write files, and stream a desktop inside an isolated sandbox.

VM operator configuration

{
  vmOperator: {
    enabled: true,
    provider: "opensandbox", // or docker, kubernetes, local, custom
    image: "opensandbox/desktop:v1.0.0",
    allowedActions: ["command", "browser", "file", "desktop", "code"],
    networkPolicy: "restricted", // isolated | restricted | open
    persistence: "persistent",   // ephemeral | session | persistent
    timeoutMinutes: 30,
    vncEnabled: true,
    autoStart: true,
    resources: { cpu: "2", memory: "4Gi", disk: "20Gi" }
  }
}

At session start, buildBotRuntimeEnv() injects ALLTERNIT_VM_* environment variables from the config, and useStartBotSession() can create or reuse the bot’s persistent sandbox.

Desktop states

The Bot Home Desktop tab streams the sandbox desktop over VNC/noVNC. Control states:

State	Meaning
`bot_controls`	The bot is using the desktop autonomously.
`human_controls`	A human has taken over and bot actions are paused.
`human_observing`	Human is watching without taking control.

When a human takes over, isBotDesktopPaused(agentId) returns true, and the runtime stops issuing sandbox commands until the desktop is handed back. The platform endpoints are:

Method	Path	Description
`GET`	`/api/v1/bots/:bot_id/desktop`	Desktop status.
`POST`	`/api/v1/bots/:bot_id/desktop/take-over`	Human takes control.
`POST`	`/api/v1/bots/:bot_id/desktop/hand-back`	Bot resumes control.

This lets a bot work autonomously, idle while a human investigates, and resume exactly where it left off.

Bot activity stream and event store

Every bot action leaves a trace in the Allternit event store. The primary surfaces are:

Agent Activity panel — a bell-icon slide-over listing threads across every agent.
Agent Activity page — a full-page view at /agent-activity.
Thread detail — messages, ledger events, receipts, and review requests for a single thread.

Events collected

The unified store (src/lib/agents/unified.store.ts) merges several event sources into a per-thread timeline:

Source	Examples
Mail messages	`@mention` handoffs, bot-to-bot replies.
Ledger events	`review`, `decide`, `guard`, `reserve`, `wih.*`.
Receipts	Tool-call posts, model usage, cost.
Logs	Runtime info, warnings, errors.
Stream events	`run.started`, `tool.call.result`, `artifact.created`, `run.completed`.

Session analytics

getSessionAnalytics(threadId) returns a computed summary including:

Total messages, unread count, participants
Ledger event count, tool-call count
Token usage and estimated cost
Tool/model breakdown
Session duration
Status (active, idle, complete, error)

Ledger API

Method	Path	Description
`POST`	`/rails/ledger/tail`	Recent events.
`POST`	`/rails/ledger/trace`	Trace events by `node_id`, `wih_id`, or `prompt_id`.

Secret redaction for bots

Bots never store raw credential material in the agent record. Secrets are declared as secretRefs:

{
  secretRefs: [
    {
      name: "GitHub token",
      key: "GITHUB_TOKEN",
      vaultRef: "vault://...",
      description: "Used to read repos",
      required: true
    }
  ]
}

Sealing and resolution

Values are sealed server-side via POST /api/v1/agents/:agent_id/secrets/:key and stored encrypted in the agent_secrets table using token_crypto::seal.
Responses from the agent API never include the value field.
At session start, resolveAgentSecrets() calls POST /api/v1/agents/:agent_id/secrets/resolve, returning decrypted values only for that runtime invocation.
Resolved secrets are merged into runtimeEnv by buildBotRuntimeEnv() and passed in AgentContext.

The Bot Home Runtime tab and the session Runtime drawer show:

Resolved keys (with values masked in the UI)
Missing required keys
Connector bindings and their allow-lists

The same pattern applies to connector credentials via resolveAgentConnectors() and POST /api/v1/agents/:agent_id/connectors/resolve.

Creating bots with `defineAgent()`

Programmatic creation must go through defineAgent() (src/lib/agents/agent-definition.ts). The factory takes industry-standard definition fields (name, description, instructions, model, tools) plus platform-specific overrides, fills canonical defaults, and validates against both the zod schema and the AGENT_CREATION_CHECKLIST.

import { defineAgent } from '@/lib/agents/agent-definition';

const bot = defineAgent({
  name: 'release-notes-writer',
  description: 'Drafts release notes from git history.',
  instructions: 'You are a technical writer...',
  type: 'specialist',
  capabilities: ['git', 'writing'],
  tools: ['git-tools', 'file-tools'],
  isBot: true,
  botProfile: {
    displayName: 'Release Notes Writer',
    tagline: 'Ship clear release notes',
    welcomeMessage: 'Paste a commit range and I will draft release notes.',
    starterPrompts: ['Draft notes for last week', 'Summarize v2.3 changes'],
    accentColor: '#8b5cf6',
    groupChatEnabled: true,
    botCategory: 'writing'
  },
  allowedSurfaces: ['chat', 'cowork'],
  trustTier: 'standard',
  harness: { mode: 'cloud' }
});

The checklist covers: canonical schema & identity, registry contract, harness configuration, workspace artifacts, character layer, allowed surfaces/skills, mode surface wiring, routines/loops/goals, tests, and documentation. See AGENT_CREATION_CHECKLIST.md for the full list.

Character layer and 5-layer workspace

Every agent and bot is initialized with a character layer and a 5-layer workspace.

Character layer

The character layer defines how the bot behaves and speaks:

Component	Contents
Identity	`setup`, `className`, `specialtySkills`, `temperament`, `personalityTraits`, `backstory`.
Role card	`domain`, `inputs`, `outputs`, `definitionOfDone`, `hardBans`, `escalation`, `metrics`.
Voice	`style`, `rules`, `microBans`, tone dimensions (`formality`, `enthusiasm`, `empathy`, `directness`).
Progression	Class, stats, level formula.
Avatar	Mascot template, colors, style.

Hard-ban categories include publishing, deploy, data_exfil, payments, email_send, file_delete, system_modify, external_communication, code_execution, and other.

5-layer workspace

Agent creation triggers workspace initialization (/api/v1/agents/:id/workspace/initialize). The persisted manifest contains:

Layer	Purpose
`cognitive`	Reasoning, memory, context.
`identity`	Role card, voice, avatar.
`governance`	Trust tier, hard bans, escalation, policy.
`skills`	Tools, connectors, allowed skills.
`business`	Deliverables, workflows, routines, goals.

The workspace file tree and generated documents (identity, role card, hard bans, escalation, voice rules) are written through agentWorkspaceService.

API references

Agents API

The Agents API is the primary surface for creating, updating, discovering, and running agents and bots.

Method	Path	Description
`POST`	`/api/v1/agents`	Create an agent or bot.
`GET`	`/api/v1/agents`	List agents/bots.
`GET`	`/api/v1/agents/:id`	Get one agent/bot.
`PUT`	`/api/v1/agents/:id`	Update an agent/bot.
`DELETE`	`/api/v1/agents/:id`	Delete an agent/bot.
`POST`	`/api/v1/agents/:id/secrets/resolve`	Resolve secret refs at runtime.
`POST`	`/api/v1/agents/:id/connectors/resolve`	Resolve connector credentials.
`POST`	`/api/v1/agents/:id/identity/{email,phone,wallet}`	Provision identity channels.

For the remote-model-compatible surface, see Agents v1 API.

Automation API

Manage goals, routines, and loops:

Method	Path	Description
`GET` / `POST`	`/api/v1/automation/goals`	Goals CRUD.
`GET` / `POST`	`/api/v1/automation/routines`	Routines CRUD.
`POST`	`/api/v1/automation/routines/:id/run`	Trigger a routine.
`GET` / `POST`	`/api/v1/automation/loops`	Loops CRUD.
`GET`	`/api/v1/automation/local-schedules`	Local schedules.

Full details: Automation API.

Proposed: Bot Activity API

A dedicated /api/v1/bot-activity group would unify bot-specific activity endpoints that today span Rails, Photon, and the agent API:

Method	Path	Description
`GET`	`/api/v1/bot-activity`	List activity threads for the user’s bots.
`GET`	`/api/v1/bot-activity/:thread_id`	Thread detail with messages, ledger events, receipts.
`POST`	`/api/v1/bot-activity/:thread_id/decide`	Approve or deny a review.
`GET`	`/api/v1/bot-activity/:bot_id/metrics`	Per-bot metrics and session analytics.
`GET`	`/api/v1/bot-activity/:bot_id/desktop`	Desktop status and VNC URL.

This is not yet implemented; use the Rails mail/ledger endpoints and the agent metrics endpoint (/api/v1/agents/metrics) in the meantime.

Error codes

HTTP	Code	Meaning
200	—	Success.
201	—	Resource created.
400	`invalid_request`	Missing or invalid fields.
401	`unauthorized`	Missing or invalid bearer token.
404	`not_found`	Bot, session, routine, or WIH not found.
409	`invalid_state`	Invalid state transition (e.g., desktop already under human control).
422	`validation_failed`	Bot contract or agent creation checklist failed.
501	`not_implemented`	Cloud action attempted on a local-domain schedule.
500	`internal_error`	Runtime or database error.

​Overview

Packaged identity

Autonomous runtime

Multi-bot collaboration

Observable work

​Bot vs Agent

​Bot Hub and discovery

​Agent Studio / Bot Hub

​CommRails Bots panel

​Bot Roster Sidebar

​Bot Session View

​Welcome card

​Agent Context Strip

​WIH progress

​Gate review

​Deliverables

​Bot automation

​Automation API

​Example: create a bot-scoped routine

​Multi-bot collaboration

​Bot group chat

​Swarm consensus

​A2A delegation and subagents

​Computer attachment, idle, and takeover

​VM operator configuration

​Desktop states

​Bot activity stream and event store

​Events collected

​Session analytics

​Ledger API

​Secret redaction for bots

​Sealing and resolution

​Creating bots with defineAgent()

​Character layer and 5-layer workspace

​Character layer

​5-layer workspace

​API references

​Agents API

​Automation API

​Proposed: Bot Activity API

​Error codes

​Related links

Overview

Bot vs Agent

Bot Hub and discovery

Agent Studio / Bot Hub

CommRails Bots panel

Bot Roster Sidebar

Bot Session View

Welcome card

Agent Context Strip

WIH progress

Gate review

Deliverables

Bot automation

Automation API

Example: create a bot-scoped routine

Multi-bot collaboration

Bot group chat

Swarm consensus

A2A delegation and subagents

Computer attachment, idle, and takeover

VM operator configuration

Desktop states

Bot activity stream and event store

Events collected

Session analytics

Ledger API

Secret redaction for bots

Sealing and resolution

Creating bots with `defineAgent()`

Character layer and 5-layer workspace

Character layer

5-layer workspace

API references

Agents API

Automation API

Proposed: Bot Activity API

Error codes

Related links