This guide explains how Flexus bots work under the hood. Understanding these concepts is essential for building effective agents.
Flexus bots are built around two fundamental concepts: Personas and Experts.
Persona: The Bot's Identity
A Persona is a specific, configured instance of a bot. It defines what the bot is and what it’s responsible for.
Each Persona has:
persona_setup) that controls behaviorExpert: The Bot's Brain
An Expert provides the core logic and capabilities. It defines how a bot thinks and what it can do.
Each Expert has:
The Persona/Expert split enables powerful patterns:
Example: You have one “Jira Expert” that knows how to interact with Jira. You can create multiple Personas:
┌─────────────────────────────────────────────────────────────┐│ FLEXUS BACKEND ││ ││ ┌─────────┐ ┌───────────┐ ┌─────────┐ ││ │Scheduler│───►│ Advancer │◄───│ Pubsub │ ││ └────┬────┘ └─────┬─────┘ └────┬────┘ ││ │ │ │ ││ │ ┌─────▼─────┐ │ ││ │ │ LLM │ │ ││ │ │ (LiteLLM)│ │ ││ │ └─────┬─────┘ │ ││ │ │ │ ││ ▼ ▼ ▼ ││ ┌─────────────────────────────────────────────────────┐ ││ │ PostgreSQL │ ││ │ (threads, messages, tasks, personas, experts) │ ││ └─────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────┘ │ │ GraphQL Subscription ▼┌─────────────────────────────────────────────────────────────┐│ BOT POD ││ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │RobotContext │ │Tool Handlers│ │ Integrations│ ││ │ (rcx) │───►│ @on_tool_* │───►│ Slack, etc │ ││ └─────────────┘ └─────────────┘ └─────────────┘ │└─────────────────────────────────────────────────────────────┘LLM calls happen on the backend (Advancer service), not in your bot code. Your bot only receives tool calls and posts results. This keeps bots simple and focused.
Flexus has two types of tools:
These run as backend services, shared across all bots:
| Tool | Purpose |
|---|---|
flexus_bot_kanban | Kanban board operations |
web | Web search and fetch |
flexus_vector_search | Vector similarity search |
flexus_hand_over_task | Delegate to other bots (A2A) |
flexus_colleagues | List available bots |
You don’t need to implement these — they’re built-in.
Tools defined in your bot that run in your bot’s process:
from flexus_client_kit import ckit_cloudtool
# Define the toolMY_TOOL = ckit_cloudtool.CloudTool( strict=True, name="my_custom_tool", description="Does something specific", parameters={ "type": "object", "properties": { "input": {"type": "string", "description": "The input"}, }, "required": ["input"], "additionalProperties": False, },)
# Handler in your main loop@rcx.on_tool_call(MY_TOOL.name)async def handle_my_tool(toolcall, args): result = do_something(args["input"]) return f"Result: {result}"Every tool in your TOOLS list must have a corresponding @rcx.on_tool_call handler. Missing handlers cause tool calls to be ignored.
Each Persona has a kanban board for task management:
┌─────────┐ ┌─────────┐ ┌────────────┐ ┌─────────┐│ INBOX │──►│ TODO │──►│ IN_PROGRESS│──►│ DONE │└─────────┘ └─────────┘ └────────────┘ └─────────┘ │ │ │ │ │ │ Tasks Bot Scheduler arrive sorts assigns here these tasksflexus_bot_kanban to mark completeBots define schedules in their install script:
| Type | When It Runs | What Happens |
|---|---|---|
SCHED_TASK_SORT | Inbox has items | Bot sorts inbox to todo |
SCHED_TODO | Todo has items | Assigns task, starts chat |
SCHED_ANY | Time-based only | Runs sched_first_question |
SCHED_CREATE_TASK | Time-based only | Creates and assigns task |
For complex tasks, bots can spawn subchats — isolated conversations that run in parallel:
@rcx.on_tool_call("complex_analysis")async def handle(toolcall, args): # Create 3 parallel subchats subchats = await ckit_ask_model.bot_subchat_create_multiple( client=fclient, who_is_asking="parallel_analysis", persona_id=rcx.persona.persona_id, first_question=["Analyze aspect 1", "Analyze aspect 2", "Analyze aspect 3"], first_calls=["null", "null", "null"], title=["Analysis 1", "Analysis 2", "Analysis 3"], fcall_id=toolcall.fcall_id, fexp_name="analyst", # Use specific expert ) raise ckit_cloudtool.WaitForSubchats(subchats)Subchats:
Lark kernels are Starlark scripts that run on backend before/after each LLM call:
# Example Lark kernelmsg = messages[-1]
# Check spendingif coins > budget * 0.8: post_cd_instruction = "Budget running low. Wrap up soon."
# Detect completion markerif "TASK_COMPLETE" in str(msg.get("content", "")): subchat_result = msg["content"]
# Kill unwanted tool callsif msg.get("tool_calls") and "dangerous_tool" in str(msg["tool_calls"]): kill_tools = True error = "That tool is not allowed in this context"| Direction | Variable | Purpose |
|---|---|---|
| Input | messages | Conversation history |
| Input | coins | Tokens spent |
| Input | budget | Token budget |
| Output | error | Stop with error |
| Output | kill_tools | Cancel tool calls |
| Output | post_cd_instruction | Inject instruction |
| Output | subchat_result | Return subchat result |
A complete bot consists of these files:
mybot/ __init__.py mybot_bot.py # Runtime: tools, handlers, main loop mybot_prompts.py # System prompts for each expert mybot_install.py # Marketplace registration mybot-1024x1536.webp # Big marketplace picture mybot-256x256.webp # Avatar forms/ # Optional: custom HTML forms report.html| File | Change Requires |
|---|---|
_bot.py | Auto-restart |
_prompts.py | Reinstall |
_install.py | Reinstall |
| Images | Reinstall |
Bots are installed in two stages:
Stage 1: Publish to Marketplacemybot_install.py --ws=workspace_id │ ▼Creates in DB: - flexus_marketplace record - flexus_expert records │ ▼Returns: marketable_name, marketable_version (Bot is published but not running)
Stage 2: Hire (Create Persona)UI: Marketplace → "Hire" button ORCode: bot_install_from_marketplace(...) │ ▼Creates in DB: - flexus_persona record - flexus_persona_schedule records │ ▼Returns: persona_id (Bot can now run)Now that you understand the architecture: