Python Package Overview

MeshAgent provides a collection of tools and SDKs for building agents that collaborate in real time. At a high level MeshAgent provides:

• A room‑based infrastructure for agents and participants to communicate.
• A set of clients (messaging, storage, document sync, etc.) to simplify common tasks.
• Integrations for popular services (OpenAI, LiveKit, etc.).
• A command‑line interface (CLI) to manage projects and agents.

The 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 Packages at a Glance

In this guide you will understand the relationships and core components for each of the MeshAgent packages:

• meshagent.api: the base layer providing JWT auth, websocket protocols, rooms, messaging, storage, document sync, and webhooks
• meshagent.agents: adds agent classes (e.g., TaskRunner, ChatBot) that orchestrate toolkits and planning logic on top of the core API
• meshagent.livekit: plugs in LiveKit for voice communication and streaming, providing specialized agents like VoiceBot
• meshagent.tools: builds on meshagent.api to create reusable tools and toolkits (collections of tools) that operate over a ToolContext that integrates with the room
• meshagent.mcp: exposes MCP-hosted tools using the same toolkit interface so agents can call them
• meshagent.computers: offers abstractions to control browsers or OS environments (useful for automation tools or remote control)
• meshagent.openai: supplies adapters so those agents and tools can leverage OpenAI models and convert tool calls/responses appropriately
• meshagent.cli: wraps everything in a user-facing command line interface for managing projects, tokens, agents, messaging, etc

Together these packages form a layered ecosystem: 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

The meshagent.api is the foundation that all other packages build on. It includes foundational protocols, JWT authentication, room management, document sync, and more.

​

JWT Authentication

MeshAgent uses JSON Web Tokens (JWTs) to authenticate participants. A token encodes who you are (participant name) and what you’re allowed to access (project ID, room name, role). The token is signed, so the server can verify it without storing any state.

from meshagent.api import ParticipantToken
token = ParticipantToken(
    name="alice",
    project_id="your-project-id",
    api_key_id="your-api-key-id",
)
token.add_room_grant(room_name="my-room", role="user")
jwt = token.to_jwt(secret="your-api-secret")

​

WebSocket Protocol

A WebSocket keeps a two-way connection open between your Python code and the Meshagent server. This allows instant messaging, file transfers, and document updates. WebSocketClientProtocol manages the underlying connection:

from meshagent.api import WebSocketClientProtocol
protocol = WebSocketClientProtocol(url=room_url, token=jwt)
async with protocol:
    # communication occurs over this protocol

Messages are encoded and decoded using a Protocol layer that is transport-agnostic.

​

RoomClient

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.

from meshagent.api import RoomClient
async with RoomClient(protocol=protocol) as room:
    await room.messaging.send("hello everyone!")
    async with room.storage.open(path="example.txt", overwrite=True) as f:
        await f.write(b"content")

​

Document Runtime and Schemas

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

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

Separate from rooms, AccountsClient is a REST-based client for managing projects, API keys, and secrets. It is useful for administrative tasks.

​

ServiceHost

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.

from meshagent.api.services import ServiceHost

service = ServiceHost(
    port=int(os.getenv("MESHAGENT_PORT","7777"))
)

@service.path("/chat")
class SimpleChatbot(ChatBot):
    ...
print(f"running on port {service.port}")
asyncio.run(service.run())

​

MeshAgent Agents

The 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

The 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

The SingleRoomAgentextends 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

The 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

The 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

The 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

The meshagent.livekit package equips agents with real-time audio and voice capabilities via the LiveKit SDK.

​

VoiceBot

The 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

The meshagent.tools package bundles reusable tool and toolkit abstractions plus a set of out of the box MeshAgent toolkits.

​

ToolContext and BaseTool

The 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 and Toolkit

A 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.

​

Response Types

Response types specify the output that a tool should return. This helps the tool and agent know how to handle the response appropriately. Response types include: JsonResponse, TextResponse, and FileResponse.

from meshagent.tools import Tool, Toolkit, ToolContext
from meshagent.api.messaging import TextResponse

class MyNewTool(Tool):
    def __init__(self):
        super().__init__(
            name="my_new_tool",
            title="A sample tool", 
            description="The tool skeleton",
            input_schema={
                "type":"object",
                "additionalProperties": False,
                "required": [...],
                "properties": {...}
            }
        )
    async def execute(self, ctx:ToolContext, sample_parameter:str):
        # tool logic
        return TextResponse(text="Tool logic complete")
    
class MyNewToolkit(Toolkit):
    def __init__(self):
        super().__init__(
            name="my_new_toolkit", 
            title="An example toolkit", 
            description="The toolkit skeleton", 
            tools=[MyNewTool])

​

Built-in Toolkits

Some of the built-in MeshAgent toolkits include:

• StorageToolkit: Provides file operations (read, write, list, etc.)
• DocumentAuthoringToolkit: Defines tools for manipulating Mesh documents (create document, add element, remove element, etc.)

​

MeshAgent MCP

The meshagent.mcp package allows you to use any MCP server as a MeshAgent tool.

​

MCPTool

Wrap an MCP tool with MCPTool so it conforms to the MeshAgent Tool syntax. For more details on how to do this check out the MeshAgent MCP docs.

​

MCPToolkit

The MCPToolkit bundles multiple MCPTool instances into a toolkit that agents can invoke just like built-in MeshAgent tools or custom tools.

import mcp
from meshagent.mcp import MCPToolkit

session = mcp.ClientSession(...)
toolkit = MCPToolkit(
    name="mcp-tools",
    session=session,
    tools=[...]
)

​

MeshAgent Computers

The meshagent.computers package defines abstractions for controlling browsers and operating systems and providing these abilities to agents.

​

ComputerAgent

The ComputerAgent in 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.

from meshagent.api import RequiredToolkit
from meshagent.openai import OpenAIResponsesAdapter
from meshagent.computers import ComputerAgent, BrowserbaseBrowser, Operator
from meshagent.api.services import ServiceHost

service = ServiceHost()

@service.path("/computeragent")
class BrowserbaseAgent(ComputerAgent):
    def __init__(self):
        super().__init__(
            name="meshagent.browser",
            title="browser agent",
            description="a task runner that can use a browser",
            requires=[RequiredToolkit(name="ui", tools=[])],
            llm_adapter=OpenAIResponsesAdapter(
                model="computer-use-preview",
                response_options={"reasoning": {"generate_summary": "concise"}, "truncation": "auto"},
            ),
            labels=["tasks", "computers"],
            computer_cls=BrowserbaseBrowser,
            operator_cls=Operator
        )

asyncio.run(service.run())

​

MeshAgent OpenAI

The meshagent.openai package provides adapters to integrate OpenAI models with MeshAgent tools and agents.

​

Completions Adapter and Responses Adapter

MeshAgent supports both the OpenAI Chat Completions API and Responses API. It is recommended to use the Responses adapter given the newer OpenAI models and functionality use the Responses adapter.

• 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.

from meshagent.openai import OpenAIResponsesAdapter
from openai import AsyncOpenAI

# Use an OpenAI client inside a MeshAgent LLMAdapter
adapter = OpenAIResponsesAdapter(client=AsyncOpenAI(api_key="sk-..."))

​

Tool Response Adapter

The OpenAICompletionsToolResponseAdapter and OpenAIResponsesToolResponseAdapterconvert a tool’s structured response into plain text or JSOn that can beinserted into an OpenAI chat context.

​

MeshAgent CLI

The 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.