Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt

Use this file to discover all available pages before exploring further.

Presence is how the same entity speaks on different channels. Each social adapter (platform implementation) converts a vendor’s APIs and events into Bumblebee’s internal message shape and delivers replies back — including typing indicators, chunking, attachments, and tool-activity lines when enabled.

​
Declarative wiring

Platforms are listed under presence.platforms in the entity YAML. Each entry has a type (telegram, discord, cli, …) plus type-specific options (tokens via env vars, allowlists, channels, proactive targets). The harness starts only the platforms that are configured and authenticated (e.g. missing TELEGRAM_TOKEN skips Telegram with a warning).

​
First-class social adapters today

PlatformRole
TelegramLong-polling bot; optional per-user / per-chat allowlists, operator controls, concurrent updates, poll tuning.
DiscordBot token + channel list; optional proactive channel; chunk replies and presence sync with emotion state.
CLIInteractive terminal for local development; disabled automatically in bumblebee worker so headless servers do not wait on a TTY.
Platform-specific guides: Telegram, Discord.

​
Shared pipeline

For every inbound message (any platform):
  1. The adapter builds a normalized input (person id, channel, text/media metadata).
  2. Entity.perceive runs the full cognition pipeline — memory, routing, tools, reply assembly.
  3. The adapter sends the reply (chunked if needed), updates typing/presence, and surfaces tool activity if presence.tool_activity is on.
So you do not duplicate personality or memory per network — one entity, many sockets.

​
Security and boundaries

  • Allowlists (Telegram allowed_user_ids / allowed_chat_ids) limit who can trigger the bot in untrusted environments.
  • Tokens should stay in environment variables or secret managers, not committed YAML.
  • Worker mode assumes untrusted cloud: combine with execution policy (BUMBLEBEE_EXECUTION_REQUIRE_RAILWAY, RPC URLs) if tools must not run arbitrary commands on the worker host.

​
Building a new adapter (advanced)

The platform layer is an abstract interface: connect, on_message, send_message / chunking helpers, send_tool_activity, presence hooks, and person identity helpers. A new adapter:
  1. Implements that contract against the vendor’s SDK or HTTP API.
  2. Registers with the entity in the same loop that constructs Telegram/Discord today (main / presence bootstrap).
Keeping adapters thin — translate I/O only — preserves testability and avoids duplicating cognition logic. Deeper internal background: Architecture: Presence.