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. You can launch, configure, and deploy both conversational agents and background agents, 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.

​

Participant-Based Agents

Interactive agents you communicate with via voice or text. Best when you need a conversational interace 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. Manages a shared thread document, streams tool calls, and persists exchanges.
• VoiceBot: Conversational speech/voice agent. Integrates with LiveKit for audio in/out and supports the same tool interface as the ChatBot.

​

Background Agents

Background (ambient) agents triggered by tasks, queues, or other events to execute specific tasks. Best when you need to process data, wrap existing agents from other frameworks, handle background jobs, or respond to events. 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/output schemas and an ask() method. Perfect for wrapping existing agents.
• Worker: Queue driven background agent. Listens for messages and processes them sequentially. Ideal for background jobs or long-running tasks.
• MailBot: Specialized worker for email. Communicates via email, can process attachments, and invoke other custom tools before replying to a user.
• 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 AgentChatContext.
• SingleRoomAgent – Binds an agent to a Room connection and installs required toolkits.
• Specialized Base Agents – These extend the SingleRoomAgent and are either participant-oriented (ChatBot, VoiceBot) or run in the background (TaskRunner, Worker, Indexer, MailBot).

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.
• Build a Chat Agent: Learn how to use and customize a MeshAgent ChatBot.