Introduction to Agents

Building an agent with an LLM is easy. Deploying it, scaling it, and integrating it into real applications is hard. MeshAgent bridges that gap with built-in agents you can run or extend, the ability to wrap agents from any major framework, and a Room-based runtime that handles connectivity, tools, observability, and scale out of the box.

​

How to build agents with MeshAgent

MeshAgent supports two complementary ways to build and deploy agents, depending on how much customization you need. 1. Build and deploy agents with the MeshAgent CLI (recommended starting point) The MeshAgent CLI is the fastest way to get production-ready agents running in real rooms, often without writing any agent code yourself. For most new text and background workflows, the recommended starting point is meshagent process, which lets one agent handle multiple entry points such as chat, mail, queues, and toolkit calls. MeshAgent also includes specialized agent commands and SDK classes for focused use cases, including:

• ChatBots and VoiceBots (interactive, multi-turn)
• MailBots (email-based workflows)
• TaskRunners and Workers (background + queue/task-driven)

The CLI-based agents support customization by allowing you to configure:

• Custom system prompts/rules
• Tool access (use built-ins for web search, storage, image generation, MCP connectors)
• Editable rule files that room members can modify

For many teams, the CLI is the fastest path to production because it bundles the most common agent patterns and allows you to test and deploy quickly. 2. Extend agents using the MeshAgent SDKs (when you need custom behavior) When you need deeper control, you can build agents and tools directly with the MeshAgent SDKs. The SDKs give you the same underlying capabilities as the CLI but allows you to:

• Define your own agent classes with specialized logic
• Create custom tools that integrate with your systems
• Wrap existing agents from other frameworks and use them in MeshAgent
• Implement advanced workflows with custom lifecycle hooks, routing logic, or other orchestration

Both CLI and SDK-based agents can be deployed either as project-wide services (available in all rooms) or room-scoped services, and shared with end users through Powerboards or your own application.

​

Why Use MeshAgent When You Already Have Another Framework?

MeshAgent expands on traditional agent frameworks by focusing on inter-framework interoperability, rich human-in-the-loop workflows, and seamless multi-device reach. Other frameworks focus on an agent interactions, reasoning loops, memory, and planning. MeshAgent focuses on everything around that core by providing the runtime infrastructure that makes agents usable in the real-world:

• Room-based connectivity: Agents, tools, and user interfaces join the same room over a lightweight WebSocket mesh. This lets Python, Dart, JavaScript, or .NET components talk to one another as peers instead of forcing every call through a single back-end service.
• Shared tool abstraction across client and server: Any capability—opening a local file, showing a toast on a mobile device, invoking an internal REST API—becomes a MeshAgent tool. Tools can live in the user’s device, on your cloud server, or both, yet they’re invoked through the same call pattern from the agent’s perspective.
• First-class observability and cost tracking: Every agent interaction and tool call automatically records who invoked it, latency, result size, and cost metadata, feeding dashboards and billing pipelines without extra code.
• Plug-and-play UI components: MeshAgent Studio and the React / Flutter UI kits render agent interactions, streaming responses, and tool call progress out of the box, letting you drop high-quality UX into your own app.

Use MeshAgent alone, or pair it with your preferred agent framework, either way, MeshAgent handles everything you need for production scale.

​

How it Works: A Practical Scenario

Suppose your agent is written in Python and hosted on a server, while your customer-facing app is a Flutter mobile client. By connecting both to the same MeshAgent room:

• The Flutter app registers UI-centric tools—ask_user, ask_user_file, show_toast.
• The Python agent calls those tools exactly like any other function, even though they execute on the user’s phone.
• Observability events stream back automatically, so you can audit how often dialogs appeared, how long file picks took, and what it cost.
• No additional RPC plumbing, versioning, or security tunnel is required; the room’s mesh protocol handles transport, authentication, and fallback across networks.

​

Built-in MeshAgent Agents

MeshAgent ships built-in agent classes that handle Room connectivity, context, and tool orchestration. You can run them as-is, extend them with your own rules and tools, or layer them with agents built with other agent libraries like LangChain, Semantic Kernel, CrewAI, and PydanticAI.

​

Recommended Starting Point: meshagent process

For most new text and background workflows, start with meshagent process. meshagent process creates one unified agent that can be reached through one or more channels:

• chat
• email
• queues
• toolkit-style invocations

This is the clearest path when one workflow may need several entry points over time. Instead of splitting the same logic across separate chat, mail, queue, and callable agents, you can keep one agent identity and attach the channels you need. This is also the direction MeshAgent is moving for many non-voice agent patterns. Today, VoiceBot is still separate because meshagent process does not currently expose a voice channel. See Multi-channel Agents Overview and Using Multi-channel Agents for the recommended workflow.

​

Specialized Agent Types

MeshAgent also includes focused agent types that remain useful when you want a dedicated single-purpose runtime or are working with an existing codebase that already uses them.

​

Participant-Based Agents

Interactive agents you communicate with via voice or text. Best when you need a conversational interface and interactive, iterative problem-solving with the end-user. These agents:

• Appear in the Room’s participants list (just like human team members)
• Maintain persistent conversation threads and support back-and-forth dialogue
• Best for ongoing interactions where context matters

Available Participant Based Agents:

• ChatBot: Conversational text agent. Best when you want a dedicated chat-focused runtime.
• VoiceBot: Conversational speech and voice agent. Integrates with LiveKit for audio in and out.

​

Background Agents

Background agents triggered by tasks, queues, or other events to execute specific tasks. Best when you need a dedicated single-surface background runtime or a specific SDK base class. These agents:

• Run without appearing in conversation threads
• Respond to invocations or queue messages
• Execute and complete without user dialogue
• Best for automated workflows and batch processing

Available Background Agents:

• TaskRunner: Schema-driven background agent. Define input and output schemas and an ask() method.
• Worker: Queue-driven background agent. Listens for messages and processes them sequentially.
• MailBot: Specialized worker for email workflows.
• Indexer: Watches incoming content, embeds it into the room’s vector store, and integrates with RagToolkit for Retrieval Augmented Generation (RAG) workflows.

​

Under the Hood: Agent Class Model

MeshAgent agents are built on a layered class hierarchy. This design makes it easy to create agents that share consistent behavior, while still allowing you to extend or specialize them for your use case. All MeshAgent agents share a layered class hierarchy:

• Agent – Base identity, metadata, and AgentSessionContext.
• SingleRoomAgent – Binds an agent to a Room connection and installs required toolkits.
• Specialized Base Agents – These extend SingleRoomAgent and are either participant-oriented (ChatBot, VoiceBot) or run in the background (TaskRunner, Worker, Indexer, MailBot).

meshagent process is slightly different at the docs level: it is not one separate SDK base class. It is a CLI runtime that assembles channels and per-thread processes on top of the same lower-level agent building blocks. This design ensures consistent context handling, toolkit discovery, and Room integration across all agent types.

​

Extending Built-in Agents

• Add your own rules (system prompts) to steer behavior
• Register custom tools or toolkits for new capabilities
• Override methods like ask() to implement additional agent-specific logic.

Built-in MeshAgent Agents support Studio testing, UI integration, observability, and cost tracking out of the box. When ready for deployment you can deploy the agent as a project or room specific service based on your permissions and use case needs.

​

Running and Deploying Agents

MeshAgent allows you to run agents locally on your machine during development then deploy agents as either a project-wide or room-scoped service. Once deployed, MeshAgent ensures that your services are always running in the appropriate room(s) when needed.

​

Managing Agents via the Room Agents API

There are three first-class ways to coordinate work between agents: messages, queues, and tools. Messages give you one-way messaging, queues give you async one-way messaging, and tools provide request/response-style RPC. For messages and queues, use the Messaging API and Queues API. The Room Agents API lets you list and invoke available tools from code. This includes TaskRunners, which expose a tool that uses an LLM to accomplish a task. For more details check out the Room Agents documentation.

​

Next Steps

• SingleRoomAgent: Understand the different types of agents in MeshAgent and the core classes for each.
• Multi-channel Agents Overview: Learn when to use the recommended multi-channel agent path.
• Using Multi-channel Agents: Start with the practical meshagent process workflow.
• Build a Chat Agent: Learn how to use and customize a dedicated ChatBot runtime.