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 Python SDK is a family of split distributions that share the meshagent.* import namespace. In code you import modules like meshagent.api or meshagent.agents, but on PyPI you install distributions such as meshagent-api and meshagent-agents.

The top-level meshagent package is intentionally thin. It mainly provides the shared version plus extras such as meshagent[all], meshagent[cli], and meshagent[agents], which install the underlying split distributions for you. If you want a smaller environment, install only the distributions you need directly.

In the rest of this page, dotted names such as meshagent.api refer to Python import namespaces, while hyphenated names such as meshagent-api refer to the installable distributions that provide them.

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

Use meshagent[all] when you want a batteries-included install, or mix and match the individual distributions below:

Installable distribution	Import namespace	What it provides
meshagent	meshagent	Thin umbrella package with shared version metadata and extras such as [all], [cli], and [agents]
meshagent-api	meshagent.api	Core room and REST clients, JWT auth, protocols, storage, sync, services, and webhooks
meshagent-agents	meshagent.agents	Agent building blocks, process runtime support types, channels, VoiceBot support, and compatibility classes
meshagent-livekit	meshagent.livekit	LiveKit integration and voice-focused agent support
meshagent-tools	meshagent.tools	Tool and toolkit abstractions plus built-in toolkits
meshagent-mcp	meshagent.mcp	MCP-backed toolkits and tool wrappers
meshagent-computers	meshagent.computers	Browser and computer control abstractions for agents
meshagent-openai	meshagent.openai	OpenAI adapters for agents and tools
meshagent-anthropic	meshagent.anthropic	Anthropic adapters for agents and tools
meshagent-cli	meshagent.cli	The meshagent CLI and related command modules

Together these distributions form a layered ecosystem: meshagent-api provides the foundation, meshagent-tools and meshagent-agents build on top of it, integrations such as meshagent-openai, meshagent-livekit, meshagent-mcp, and meshagent-computers extend those workflows, and meshagent-cli packages the operational command line experience.

MeshAgent API

The meshagent-api distribution provides the meshagent.api namespace. It is the foundation that the other Python distributions build on, including the core protocols, JWT authentication, room management, document sync, and REST/admin clients.

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.

Python

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:

Python

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.

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.

Meshagent

Separate from rooms, Meshagent 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.

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.

Python

from meshagent.api.services import ServiceHost
from meshagent.tools import FunctionTool

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

@service.path("/ping")
class PingTool(FunctionTool):
    ...
print(f"running on port {service.port}")
asyncio.run(service.run())

MeshAgent Agents

The meshagent-agents distribution provides the meshagent.agents namespace. It adds agent building blocks for room-connected agents and exposes the lower-level pieces used by the process runtime. These types extend the base Agent and SingleRoomAgent classes which set up the fundamentals for working with agents in MeshAgent rooms.

For new user-facing docs, the main runtime path is meshagent process. The Python process composition story exists at a lower level, but the main process workflow is intentionally documented CLI-first today.

Note that agents use LLMAdapters and ToolResponseAdapters to translate between language model calls and tool executions.

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.

Process-related exports

The package also exports the core channel and thread-adapter types used by the process runtime, including:

• ChatChannel
• MailChannel
• QueueChannel
• ToolkitChannel
• AgentProcessThreadAdapter

Lower-level runtime types such as the supervisor and per-thread process live deeper in the package and are more advanced SDK surfaces.

These are the Python-side pieces that correspond to what the CLI assembles for meshagent process.

Other exported agent types

The package also includes:

• VoiceBot for real-time voice workflows
• older compatibility classes such as ChatBot, Worker, and TaskRunner

The compatibility classes remain part of the SDK surface for existing codebases, but they are not the recommended starting point for new agent docs or examples.

MeshAgent LiveKit

The meshagent-livekit distribution provides the meshagent.livekit namespace and 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. Check out the VoiceBot documentation to learn how to create a speech-enabled agent.

MeshAgent Tools

The meshagent-tools distribution provides the meshagent.tools namespace and 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: JsonChunk, TextChunk, and FileChunk.

Python

from meshagent.tools import FunctionTool, Toolkit, ToolContext
from meshagent.api.messaging import TextChunk

class MyNewTool(FunctionTool):
    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 TextChunk(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 distribution provides the meshagent.mcp namespace and 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.

Python

import mcp
from meshagent.mcp import MCPToolkit

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

MeshAgent Computers

The meshagent-computers distribution provides the meshagent.computers namespace and defines abstractions for controlling browsers and operating systems and providing these abilities to agents.

Key exports include browser and operator abstractions such as BrowserbaseBrowser and Operator, along with compatibility classes for older computer-use agent patterns.

For new user-facing docs, computer-use should be thought of as an advanced capability you can attach to a MeshAgent agent workflow, not as a separate primary runtime path. The current public docs focus first on meshagent process and other mainstream room-connected agent workflows, then use the computer package for lower-level custom integrations when needed.

MeshAgent OpenAI

The meshagent-openai distribution provides the meshagent.openai namespace and 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.

Python

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 Anthropic

The meshagent-anthropic distribution provides the meshagent.anthropic namespace and adapters to integrate Anthropic models with MeshAgent tools and agents.

Messages Adapter

• AnthropicMessagesAdapter: wraps Anthropic’s Messages API. It converts Toolkit objects into Anthropic tool definitions, executes tool calls, and returns the final assistant response.

Python

from meshagent.anthropic import AnthropicMessagesAdapter

adapter = AnthropicMessagesAdapter(model="claude-3-5-sonnet-latest")

Tool Response Adapter

The AnthropicMessagesToolResponseAdapter converts a tool’s structured response into Anthropic tool_result blocks so the model can consume tool outputs in the same turn.

MeshAgent CLI

The meshagent-cli distribution provides the meshagent.cli namespace and installs everything you need to streamline room and agent management from your terminal. It also installs the meshagent command-line entry point. 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.