meshagent.api
package forms the foundation. Other packages such as meshagent.tools
, meshagent.agents
, meshagent.openai
, and meshagent.livekit
build on this base.
MeshAgent’s Key Concepts page explains what Agents, Tools, and Rooms are. This guide shows how those ideas are implemented in the MeshAgent SDK.
meshagent.api
→ tools
and agents
→ integrations like openai
, livekit
, mcp
, computers
→ command line utilities via meshagent.cli
. This modular design lets developers build agents with custom tools, integrate OpenAI or LiveKit features, and run or deploy them via the CLI.
meshagent.api
is the foundation that all other packages build on. It includes foundational protocols, JWT authentication, room management, document sync, and more.
WebSocketClientProtocol
manages the underlying connection:
Protocol
layer that is transport-agnostic.
RoomClient
is the main entry point for interacting with a room. Once you pass in the protocol, the room becomes ready and you gain access to specialized sub-clients:
messaging
: send or broadcast text/files.storage
: open or write files in the room.sync
: collaborate on structured documents.agents
: manage agent instances.queues
, database
, livekit
, and more.SyncClient
and the document runtime allow multiple participants to edit structured documents (defined by a MeshSchema
) with real-time updates propagated via WebSocket messages.
WebhookServer
can run in your own service to receive signed events (HTTP webhooks) from MeshAgent—such as room lifecycle events (e.g., room started/ended)—allowing you to trigger custom logic.
AccountsClient
is a REST-based client for managing projects, API keys, and secrets. It is useful for administrative tasks.
ServiceHost
allows you to expose agents or tools as an HTTP service. The MeshAgent Server or CLI can invoke the service via webhook calls. The Servicehost
spins up the agent or tool, connects it to the specified room, and manages its lifecycle until the call completes or is dismissed. This is how examples like the ChatBot or VoiceBot can be run locally and also enables you to deploy an agent as a MeshAgent Service using the same applicable service path once your agent or tool is ready.
When a call to the agent or tool arrives through a webhook, the ServiceHost
spawns that agent or tool and connects it to the requested room via the RoomClient
and WebSocketClientProtocol
. The ServiceHost
starts an HTTP servier and registers each path so that multiple agents or toolkits can be hosted.
meshagent.agents
package provides higher-level agent classes that orchestrate tools and tasks. The primary agents you will build will use the TaskRunner
, Worker
, and ChatBot
agent types. These agents extend the base Agent
and SingleRoomAgent
classes which setup the fundamentals for working with Agents in MeshAgent Rooms.
Note that agents use LLMAdapters and ToolResponseAdapters to translate between language model calls and tool executions. They also use the ServiceHost to run.
Agent
base class handles static info such as the agent name, description, and requirements. This class is not used directly, but is the foundation for specialized agents.
SingleRoomAgent
extends the Agent
class, connects to a RoomClient
, and installs any declared schemas or toolkits when the agent starts up. All other MeshAgent Agent types extend the SingleRoomAgent
class with additional functionality.
TaskRunner
agent is useful when you want to invoke an agent with a well-defined JSON schemas for input and output. This is important for running agents-as-tools or running remote tasks. Often you will define a TaskRunner
and pass it to a ChatBot
or VoiceBot
as a tool for that agent to use.
Worker
is a queue-based SingleRoomAgent
that processes queued messages with an LLM and optional tools. This is particularly helpful for running asynchronous jobs. With the Worker
agent you can create a set of tasks that need to run in a Room and the Worker
will execute all of the tasks in the queue.
ChatBot
is a conversational agent derived from the SingleRoomAgent
. It wires an LLMAdapter, optoinal tools, and manages chat threads for each user. This means multiple users can be in the same room interacting with a chat agent, but each user will have private messages with the agent. Check out the Build and Deploy a Chat Agent example to learn how to create a simple Chat Agent without tools then add built-in MeshAgent tools and custom tools to the agent.
meshagent.livekit
package equips agents with real-time audio and voice capabilities via the LiveKit SDK.
VoiceBot
agent handles two-way voice conversations allowing users to interact with the agent verbally. Agents based on the VoiceBot
class can be given the same tools as ChatBot
based agents. This means you only need to write a tool once and the same tool can be used across both text and voice based agents. Check out the Build and Deploy a Voice Agent example to learn how to create a simple Voice Agent without tools then add built-in MeshAgent tools and custom tools to the agent.
meshagent.tools
package bundles reusable tool and toolkit abstractions plus a set of out of the box MeshAgent toolkits.
ToolContext
tracks the room, caller, and optional “on-behalf-of” participant. The BaseTool
defines metadata used by all tools such as name and description.
Tool
encapsulates a single operation with an input JSON schema. Each tool implements an execute
function where you define the logic for the tool. The Toolkit
groups tools together and can enforce rules or descriptions.
JsonResponse
, TextResponse
, and FileResponse
.
StorageToolkit
: Provides file operations (read, write, list, etc.)DocumentAuthoringToolkit
: Defines tools for manipulating Mesh documents (create document, add element, remove element, etc.)meshagent.mcp
package allows you to use any MCP server as a MeshAgent tool.
MCPTool
so it conforms to the MeshAgent Tool syntax. For more details on how to do this check out the MeshAgent MCP docs.
MCPToolkit
bundles multiple MCPTool
instances into a toolkit that agents can invoke just like built-in MeshAgent tools or custom tools.
meshagent.computers
package defines abstractions for controlling browsers and operating systems and providing these abilities to agents.
meshagent-computers
extends the ChatBot
with support for using browsers and computers. The computer agent will periodically send screenshots to participants on the thread using the MeshAgent messaging protocol, by sending a message of the type “computer_screen” and an attachment that contains a binary screenshot.
meshagent.openai
package provides adapters to integrate OpenAI models with MeshAgent tools and agents.
OpenAICompletionsAdapter
: wraps the OpenAI Chat Completions API. It turns Toolkit objects into OpenAI-style tool definitions and processes tool calls appropriately.OpenAIResponsesAdapter
: wraps the newer OpenAI Responses API. It collects tools, handles streaming events, and provides callbacks for advanced features like image generation or web search.OpenAICompletionsToolResponseAdapter
and OpenAIResponsesToolResponseAdapter
convert a tool’s structured response into plain text or JSOn that can beinserted into an OpenAI chat context.
meshagent.cli
package installs everything you need to streamline room and agent management from your terminal. The CLI assembles submodules for authentication, projects, API keys, participant tokens, messaging, storage, agents, webhooks, and more.
Check out the CLI Quickstart for more details.