ChatBot Overview

​

When to Use It

• You want to build an agent that is seamlessly connected to the room and responds conversationally to user messages.
• You’re building a text-based agent that uses an LLM to generate responses.
• You need to synchronize message history with room documents or threads.
• You want automatic integration with toolkits and schemas for dynamic LLM behavior.
• You plan to add tools, dynamic UI interactions, or other agent-to-room interactions during a chat.
• You prefer to focus on prompts, tools, and business logic for your agent instead of plumbing for storage, messaging, and scale.

​

Constructor Parameters

​

Lifecycle Overview

• await start(room: RoomClient): Connects to the room, installs requirements, and registers message handlers. Spawns per-thread tasks to handle participant messages, LLM responses, and tool invocations.
• await stop(): Cancels active chat threads and clears cached state before disconnecting.
• room property: Accesses the active RoomClient just like in SingleRoomAgent.

​

Conversation Flow

1. The ChatBot receives the message via room.messaging.on("message").
2. It identifies or spawns a chat thread corresponding to that conversation path.
3. A chat context (AgentChatContext) is initialized using the llm_adapter.
4. The message history is synchronized with the room’s "thread" document.
5. ChatBot resolves this turn’s toolkits: it collects ToolkitBuilders from get_thread_toolkit_builders(...), merges per-turn ToolkitConfigs (from MeshAgent Studio/CLI/App UI), calls make_tools(...) to create any dynamic toolkits, and combines the result with any static toolkits.
6. The LLM is invoked with the prepared chat context and the resolved toolkits; tool calls are routed back into those toolkits, tokens are streamed, and the results are appended to the thread document.

​

Key Behaviors and Hooks

• Thread management: Every conversation lives inside a MeshDocument thread. The ChatBot opens the thread as soon as a user sends a message and keeps it in sync with the document store.
• Context building: init_chat_context() asks the LLM adapter for a fresh context and appends any rules you provided. Override this if you need to preload the context with extra data.
• Static tool resolution: get_thread_toolkits() gathers toolkits declared in requires, and any always-on toolkits passed through toolkits.
• Dynamic tool providers: get_thread_toolkit_builders() lists the ToolkitBuilder factories the ChatBot is willing to spin up on demand (MCP, storage uploads, local shell, image generation, etc.). The chat UI calls this hook first to learn which tool toggles to display, and later sends back matching configs so the ChatBot can hydrate those toolkits with make_tools().
• Message-specific toolkits: When the user sends a message with a tools payload, make_tools() combines the selected configs with the provider list to hydrate just the toolkits needed for that turn before the LLM is invoked. (For example, in MeshAgent Studio, when the user selects which tools to add to an agent, these tools are added to the tools payload so the agent can use them.)
• Thread helpers: Use open_thread() and close_thread() to work with the underlying document, or load_thread_context() to replay the stored messages into an existing chat context (for example, when resuming a conversation).
• LLM customization: Override prepare_llm_context() if you need to mutate the context right before calling the LLM (for example to provide additional background context for the agent outside of the system prompt).
• Participant utilities: get_online_participants() returns the participants included in the thread so you can tailor responses or access their attributes.

​

Key Methods

​

Built-in Toolkits and Behaviors

• Reasoning Toolkit: Allows structured “chain-of-thought” reasoning within the chat context.
• Built-in Tool Support (OpenAI-style): May include web_search, local_shell, or image_gen, depending on the LLM adapter.
• UI Toolkit Integration: Supports sending messages, showing toasts, or interacting with user interfaces via the “ui” toolkit.

​

Beginner-Friendly Examples

import asyncio
from meshagent.otel import otel_config
from meshagent.api.services import ServiceHost
from meshagent.agents.chat import ChatBot
from meshagent.openai import OpenAIResponsesAdapter

# Enable OpenTelemetry logging and tracing for the agent
otel_config(service_name="chatbot")

# Create a service host
service = ServiceHost()  # optional to pass a port, MeshAgent automatically assigns an available one if none provideds

# Register an agent at a specific path
@service.path(path="/chat", identity="chatbot")
class SimpleChatbot(ChatBot):
    def __init__(self):
        super().__init__(
            name="chatbot",
            title="Simple Chatbot",
            description="A helpful chatbot for room participants",
            rules=[
                "Always respond to the user first then include a fun fact at the end of your response."
            ],
            llm_adapter=OpenAIResponsesAdapter(),
        )

# Start the service
asyncio.run(service.run())

meshagent service run "main.py" --room=gettingstarted

​

Next Steps

• Build a ChatBot: Step-by-step guide to configuring adapters, adding toolkits, and running your ChatBot in a MeshAgent room.
• Adapters: Understand how LLM adapters and tool response adapters plug into the chat loop.
• VoiceBot: Adds streaming audio input/output for speech interactions.
• Worker and TaskRunner: Perform background or task-based actions.
• MailWorker: Interact with an agent via email.

• Services & Containers: Understand different options for running, deploying, and managing agents with MeshAgent
• Secrets & Registries: Learn how to store credentials securely for deployment