Core Concept

Bots & Swarms

A Bot is a single autonomous unit defined in HiveLang. A Swarm is a coordinated team of bots working together — the architecture that lets Bothive scale from one helpful assistant to a full operations team. (Inside a single bot, you can also define agents — role-specialized helpers it delegates to. Those live within one bot; a swarm is about multiple bots.)

What is a Bot?

A Bot is a single autonomous unit defined in HiveLang. It has a name, a description, the tools it's allowed to call, and its own memory. A bot can run on its own — answering questions, calling APIs, taking actions — or it can be one member of a larger Swarm. (A bot can itself contain agents: role-specialized helpers it delegates to internally. Agents live inside one bot; a swarm coordinates multiple bots.)

Every bot is built from four things:

Name — a unique identifier for the agent.
Description — what it does, in plain language. The router reads this to decide when to use it.
Capabilities — the tools and integrations it may call (Slack, GitHub, web search, your own API…).
Memory — persistent state it can remember and recall across runs.

What is a Swarm?

A Swarm is a team of bots that collaborate. When a request arrives, an orchestrator routes it to the bot best suited to handle it — based on each bot's description — and can chain their outputs so one bot's result becomes the next one's input.

Why split work across multiple agents instead of one big one?

Specialization — a focused agent with a tight toolset is more reliable than a do-everything one (fewer wrong tool calls, clearer prompts).
Parallelism — independent steps can run at the same time.
Fault tolerance — if one bot fails, the others still complete their part.
Scalability — add a new bot without touching the existing ones.

How routing works

The orchestrator doesn't hard-code which agent runs. It reads each bot's description and the incoming request, then picks the best match — the same way you'd hand a task to the right teammate. That's why a clear, specific description matters: "Finds and summarizes academic papers" routes far better than "research bot".

Swarm Router

routes by reading each bot's role

Searcher

Web search

Writer

Summarize

Coder

Generate

Defining a Swarm in HiveLang

In HiveLang v5 you declare a swarm with member agent blocks, then delegate work to them. Each agent has its own role and capabilities:

research-swarm.hive

swarm ResearchSwarm {
  description: "A team of bots for research tasks"

  agent Searcher {
    role: "Finds reliable information online for a given topic"
    capabilities {
      web.search
      knowledge.search
    }
  }

  agent Summarizer {
    role: "Condenses findings into a few clear key points"
    capabilities {
      ai.generate
    }
  }

  on user.message {
    // Hand the topic to the Searcher, then pass its result to the Summarizer.
    findings = delegate to Searcher with { task: input }
    summary  = delegate to Summarizer with { task: findings }
    respond with summary
  }
}

Chaining agents

Pass one bot's output as the next's input to build a pipeline — Searcher → Summarizer → Publisher. The builder does exactly this with a drag-and-drop graph if you'd rather not write it by hand.

When to use one Bot vs. a Swarm

Start with a single bot. Reach for a Swarm when a task naturally breaks into distinct skills (research vs. writing vs. posting), when steps can run in parallel, or when one bot's tool list is getting so long that it starts picking the wrong tool. If you find yourself writing "and then, and then, and then" in one bot's instructions, that's the signal to split it.

Next steps

Proactive Agents

Run agents from schedules and event-driven surfaces.

Tools & Actions

Give each bot real capabilities to call.

Agent Memory

Let bots remember context across runs.

Parallel Execution

Run independent agent steps at the same time.