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.
Tools are how the entity interacts with the world — not “services for the user,” but senses and reach. The entity decides when and how to use tools based on conversation context. Both reflex and deliberate reasoning profiles share the same tool registry, and the agent loop executes multiple tool calls in parallel when the model emits them in one step.
When presence.tool_activity is enabled, tool use surfaces in chat with short status lines so the user can see what the entity is doing.
Tools are registered at startup based on YAML configuration and installed extras. During each turn, the perceive pipeline routes to either reflex or deliberate reasoning. Both profiles have access to the full tool registry — the difference is token budget and thinking mode.
The bounded agent loop runs tool calls, inspects results, and decides whether to continue (more tools needed), produce a final reply, or report a failure. A context-aware nudge after each tool round tells the model which tools ran and whether they succeeded, referencing the user’s original question. A completion gate prevents thin acknowledgements from escaping as final replies.
The entity can chain tools across multiple rounds. For example, a question about current weather might trigger get_weather, while a research question might chain search_web into fetch_url into a synthesized reply. The maximum number of tool rounds per turn is controlled by cognition.tool_continuation_rounds (default 21).
Every built-in tool, its harness configuration key, and default state. Tools marked “always on” have no enabled gate — they register whenever the harness starts. Others are toggled via tools.<key>.enabled in configs/default.yaml or per-entity YAML.
Web and search
| Tool | Harness key | Default | Description |
|---|
search_web | — | on | Web search (DuckDuckGo by default; optional Firecrawl) |
fetch_url | — | on | Fetch and extract text from a URL |
Shell and processes
| Tool | Harness key | Default | Description |
|---|
run_command | shell | on | Run a shell command (denylist + timeout) |
run_background | shell | on | Start a background shell command |
check_process | shell | on | Inspect a tracked background job |
kill_process | shell | on | Stop a background job |
Filesystem
| Tool | Harness key | Default | Description |
|---|
read_file | — | on | Read a file under the execution workspace |
write_file | — | on | Write or create a file |
append_file | — | on | Append to an allowed file path |
list_directory | — | on | List files under the workspace directory |
search_files | — | on | Search by pattern under the workspace |
apply_patch | — | on | Apply a unified diff hunks to workspace files (atomic multi-file edits) |
send_file | — | on | Send a workspace file to the active chat (Telegram/Discord) with optional caption |
Episodic memory
| Tool | Harness key | Default | Description |
|---|
search_past_conversations | — | on | Semantic search over episodic summaries (natural-language query; embedding-backed) |
Session planning
| Tool | Harness key | Default | Description |
|---|
todo_add | — | on | Add an item to the in-session todo list |
todo_list | — | on | List pending session todos |
todo_complete | — | on | Mark a session todo done |
todo_remove | — | on | Remove a session todo |
Human-in-the-loop
| Tool | Harness key | Default | Description |
|---|
ask_user | — | on | Ask a short clarifying question and wait for a reply (structured follow-up) |
delegate_task | — | on | Run a bounded sub-task with a reduced tool subset (delegation platform) |
Code execution
| Tool | Harness key | Default | Description |
|---|
execute_python | code | on | Run Python in a sandboxed helper |
execute_javascript | code | on | Run JavaScript in a sandboxed helper |
code_task_session | code | on | Structured multi-step code work inside an isolated session (files, tools, history) |
Knowledge and journal
| Tool | Harness key | Default | Description |
|---|
update_knowledge | — | on | Add, update, or remove knowledge.md sections |
read_journal | journal | on | Read recent private journal entries |
write_journal | journal | on | Append a private journal entry |
Voice
| Tool | Harness key | Default | Description |
|---|
speak | voice | on | Send a TTS voice note to the active chat |
get_tts_voice | voice | on | Current Edge-TTS voice ID |
set_tts_voice | voice | on | Set Edge-TTS voice for this process |
list_tts_voices | voice | on | List available Edge-TTS voices (filterable) |
Messaging
| Tool | Harness key | Default | Description |
|---|
send_dm | messaging | on | DM on Telegram or Discord (confirmation flow) |
send_message_to | messaging | on | Message a platform target or resolved person |
list_known_contacts | messaging | on | Known people and routes from prior interactions |
Automations
| Tool | Harness key | Default | Description |
|---|
create_automation | automations | on | Create a scheduled routine (cron, prompt, optional delivery) |
edit_automation | automations | on | Edit routine fields |
delete_automation | automations | on | Remove a routine |
list_automations | automations | on | List all routines |
toggle_automation | automations | on | Enable or disable a routine |
run_automation_now | automations | on | Trigger a routine immediately |
Reminders
| Tool | Harness key | Default | Description |
|---|
set_reminder | reminders | on | Schedule a reminder (DB + APScheduler) |
list_reminders | reminders | on | List active reminders |
cancel_reminder | reminders | on | Cancel a scheduled reminder |
Browser (optional)
| Tool | Harness key | Default | Description |
|---|
browser_navigate | browser | off | Open a URL in the automated browser |
browser_click | browser | off | Click an element (Playwright) |
browser_type | browser | off | Type into the page |
browser_screenshot | browser | off | Screenshot the current page |
Remote desktop sessions (optional)
| Tool | Harness key | Default | Description |
|---|
desktop_session_click | remote_session | off | Click at screen coordinates |
desktop_session_keypress | remote_session | off | Send key presses or shortcuts |
desktop_session_open_url | remote_session | off | Open a URL inside the remote desktop |
desktop_session_status | remote_session | off | Inspect the active session |
desktop_session_stop | remote_session | off | Stop the active session |
desktop_session_type | remote_session | off | Type text into the session |
desktop_session_view | remote_session | off | Capture the current frame |
Image generation (optional)
| Tool | Harness key | Default | Description |
|---|
generate_image | imagegen | off | Text-to-image (Fal or local SD WebUI-compatible) |
IoT / Environment
| Tool | Harness key | Default | Description |
|---|
get_ha_state | iot | on | Check the current state of a Home Assistant entity |
set_ha_state | iot | on | Call a Home Assistant service to change state |
Observation
| Tool | Harness key | Default | Description |
|---|
tail_file | observation | on | Read the last N lines of a file (useful for fast log monitoring) |
check_file_modified | observation | on | Check the last modified time and size of a file |
Social Broadcast
| Tool | Harness key | Default | Description |
|---|
post_mastodon_status | social | on | Post a status update to a configured Mastodon account |
read_mastodon_timeline | social | on | Read the latest posts from the Mastodon home timeline |
post_zweet_status | social | on | Post a zweet (status update/tweet) to an X (Twitter) account |
Local RAG / Indexing
| Tool | Harness key | Default | Description |
|---|
index_text | rag | on | Index a block of text into a local SQLite vector DB using Ollama embeddings |
search_collection | rag | on | Semantically search a specific RAG collection for information |
| Tool | Harness key | Default | Description |
|---|
get_current_time | — | on | Current local date and time (timezone-aware) |
get_weather | weather | on | Weather for a location |
get_news | news | on | News headlines by topic |
get_system_info | system | on | Host and system snapshot |
Content
| Tool | Harness key | Default | Description |
|---|
read_pdf | pdf | on | Extract text from a PDF path |
read_reddit | reddit | on | Browse a subreddit |
read_reddit_post | reddit | on | Read a Reddit post thread |
read_wikipedia | wikipedia | on | Wikipedia summary or full article |
get_youtube_transcript | youtube | on | Transcript for a YouTube video |
search_youtube | youtube | on | Search YouTube |
Discovery
| Tool | Harness key | Default | Description |
|---|
search_tools | — | on | Search registered tools by keyword |
describe_tool | — | on | Full name, description, and JSON Schema for one tool |
Agency and flow control
| Tool | Harness key | Default | Description |
|---|
think | — | on | Private scratchpad thought (not shown to users) |
say | — | on | Send a message mid-turn to the active chat |
end_turn | — | on | End the current turn (mood / parting thought optional) |
end_wake_session | — | on | During sustained autonomous wake, signal no further rounds after this perceive completes |
wait | — | on | Pause briefly before the next action |
observe | — | on | Fetch recent messages from a channel (where supported) |
compact_context | — | on | Request proactive context compaction |
end_wake_session only affects multi-round autonomous wake. end_turn ends a single perceive round.
Enabling and disabling
Each tool category has an enabled flag in configs/default.yaml:
tools:
shell:
enabled: true
deny: ["rm -rf /", "sudo rm", "shutdown"]
timeout: 30
browser:
enabled: false
voice:
enabled: true
imagegen:
enabled: false
tools: block in entity YAML.
Runtime discovery
The live registry depends on YAML toggles, installed extras, and any MCP servers attached. The entity can inspect its own capabilities at runtime:
search_tools — find tools by keyworddescribe_tool — get the full JSON Schema for a specific tool
MCP
Attach external tools via Model Context Protocol stdio servers. Their tools register dynamically at startup, prefixed with the server name so they stay distinct from native tools.
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
configs/entities/example.yaml for a commented template.
Zapier MCP
Zapier exposes MCP over Streamable HTTP, but Bumblebee only spawns stdio servers today. Bridge with mcp-proxy:
mcp_servers:
zapier:
command: mcp-proxy
args: ["--transport", "streamablehttp", "https://actions.zapier.com/mcp/YOUR_ID/sse"]
env:
API_ACCESS_TOKEN: "your_zapier_secret"
pip install 'bumblebee[voice]' # Edge-TTS voice notes
pip install 'bumblebee[browser]' # Playwright browser tools
pip install 'bumblebee[imagegen]' # fal image generation
pip install 'bumblebee[pdf]' # PDF reading
pip install 'bumblebee[youtube]' # YouTube transcripts
pip install 'bumblebee[full]' # everything
Execution layer
Shell, filesystem, and code tools run via the execution layer. Where they execute depends on your deployment:
- Local — same machine as Bumblebee
- Railway — inside the container (
RAILWAY_ENVIRONMENT is set)
- RPC — remote execution host via
BUMBLEBEE_EXECUTION_RPC_URL
See Hybrid deployment for details on execution safety and configuration.
