Creating a New Bot

This guide walks you through the real, code-centric process of building a custom bot in Flexus. We will create a simple “Greeting Bot” that uses a custom tool.

The process involves three main stages:

1. Defining the Bot’s Brain: Creating the Expert and its system prompt.
2. Giving the Bot an Identity: Creating the Persona and configuring it.
3. Writing the Bot’s Logic: Developing the code for the tools the bot will use.

Step 1: Define the Expert

The Expert holds the core logic of your bot. It consists of a system prompt and a set of allowed tools.

1. Create a System Prompt This is the most crucial step. The prompt tells the AI how to behave. For our Greeting Bot, the prompt will instruct it to use a specific tool to greet a user.

   System Prompt Example:

   You are a friendly Greeting Bot. Your one and only job is to greet the user specified in the 'name' parameter. To do this, you MUST call the `greeting_tool` with the provided name. Do not ask questions or do anything else.

2. Create the Expert in Flexus You’ll need to create an Expert record in the Flexus system. This is typically done via a setup script or an internal admin UI. The key fields are:

   • fexp_name: “Greeting Expert”
   • fexp_system_prompt: (The prompt from the previous step)
   • fexp_allow_tools: ["greeting_tool"] (A list of tools this expert can use)

Step 2: Create the Persona

The Persona is the public-facing identity of your bot. It links to the Expert you just created.

1. Create the Persona in Flexus Like the Expert, this is done via a script or admin UI.

   • persona_name: “Greeter”
   • persona_marketable_name: “greeter_bot_v1”
   • Link it to your “Greeting Expert”.

2. Configure the Persona Setup The persona_setup JSON field allows you to pass configuration to your bot. For this simple bot, we don’t need any, but you could use it to specify a default greeting style, for example.

Step 3: Write the Tool’s Code (Python)

This is where you write the actual logic for the greeting_tool that your Expert is allowed to call. Flexus uses CloudTools to execute this code.

Here is a simple Python script for our tool. It will be run by the Flexus platform.

from flexus_client_kit.ckit_cloudtool import run_cloudtool_service, FCloudtoolCall, CloudTool
import asyncio
import json

# Define the tool's function
async def handle_greeting_call(call: FCloudtoolCall, args: dict) -> tuple[str, str]:
    """
    This function is executed when the 'greeting_tool' is called.
    """
    try:
        # The arguments are passed as a JSON string in the FCloudtoolCall
        tool_args = json.loads(call.fcall_arguments)
        name = tool_args.get("name", "World")

        # The result must be a JSON string
        content = json.dumps({"message": f"Hello, {name}! Welcome to Flexus."})
        provenance = json.dumps({"system": "greeting_tool", "version": "1.0"})

        return content, provenance
    except Exception as e:
        return json.dumps({"error": str(e)}), json.dumps({"system": "greeting_tool"})

# Define the tool's schema for the Flexus platform
greeting_tool_schema = CloudTool(
    name="greeting_tool",
    description="Generates a personalized greeting.",
    parameters={
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "The name of the person to greet."
            }
        },
        "required": ["name"]
    }
)

async def main():
    # This function registers the tool and keeps it running
    await run_cloudtool_service(
        service_name="greeting_tool_service",
        tools=[greeting_tool_schema],
        the_python_function=handle_greeting_call,
        # ... other necessary config like fgroup_id, fuser_id ...
    )

if __name__ == "__main__":
    asyncio.run(main())

This script uses the flexus_client_kit to register a CloudTool named greeting_tool. When the tool is called by a bot, the handle_greeting_call function is executed.

Step 4: Activate and Test

With all the pieces in place, you can now activate your bot.

1. Start the Tool: Run your greeting_tool.py script in an environment where the Flexus platform can reach it.
2. Trigger the Bot: The simplest way to test is to start a new chat thread with the “Greeter” Persona.
3. Provide Input: Send a message like:

   { "name": "Alice" }

4. Verify the Output: The bot should follow its instructions, call the greeting_tool, and return the message: Hello, Alice! Welcome to Flexus.

You have now created a bot from scratch, defining its AI behavior and implementing its capabilities in code.