Skip to main content
MeshAgent Rooms provide real-time collaborative workspaces for agents and participants. Each room dynamically manages participant lists, tracks presence, and enables information sharing. Rooms are automatically provisioned when participants join, ensuring effortless integration and minimizing synchronization complexity. Rooms also serve as gateways to several additional APIs accessible through the room object:
  • Agents API AgentsClient: Manages agent interactions.
  • Containers API ContainersClient: Interact with containers on demand in a room.
  • Database API DatabaseClient: Provides a simple relational-like API for data storage and retrieval through tables.
  • Messaging API MessagingClient: Enables real-time chat messaging among participants.
  • Queues API QueuesClient: Facilitates reliable data/message exchange with other agents or participants.
  • Secrets API SecretsClient: Create and manage oauth tokens and user secrets.
  • Storage API StorageClient: Manages file storage and retrieval.
  • Sync API SyncClient: Offers document synchronization capabilities, listing remote participants, allowing participants to collaborate on shared documents.
For information on how to create and manage rooms and their permissions in a project check out the REST API documentation.

​
Let’s connect to a room

First, be sure to have followed the Getting Started with MeshAgent Docs. Next, in your terminal authenticate to MeshAgent and export the environment variables needed to connect to your MeshAgent project. You can do this using the MeshAgent CLI. 
meshagent auth login
meshagent project activate -i
# create an api key if necessary. The key value will be displayed only once.
meshagent api-key create --activate my-key
export MESHAGENT_API_KEY=[my-api-key-value]
Now run the code to connect to a MeshAgent room. 
import os
import asyncio
from meshagent.api import (
    RoomClient,
    WebSocketClientProtocol,
    ParticipantToken,
    ApiScope,
    ParticipantGrant,
)


def env(name: str) -> str:
    val = os.getenv(name)
    if not isinstance(val, str) or not val:
        raise RuntimeError(f"Missing required environment variable: {name}.")
    return val


async def main():
    room_name = "my-room"
    api_key = env("MESHAGENT_API_KEY")
    async with RoomClient(
        protocol=WebSocketClientProtocol(
            url=f"wss://api.meshagent.com/rooms/{room_name}",
            token=ParticipantToken(
                name="participant",
                grants=[
                    ParticipantGrant(name="room", scope=room_name),
                    ParticipantGrant(name="role", scope="agent"),
                    ParticipantGrant(name="api", scope=ApiScope.agent_default()),
                ],
            ).to_jwt(api_key=api_key),
        )
    ) as room:
        print(f"Connected to room: {room.room_name}")


asyncio.run(main())

​
Room Class Overview

Rooms expose the same capabilities in every SDK, but the exact API mirrors the host language. Use the section below that matches your client library.

​
Python

from meshagent.api import RoomClient
  • Connect with async with RoomClient(protocol=...) as room:; the async context manager starts and stops the connection for you.
  • Issue requests with await room.send_request(...); session metadata is available via room.session_id, room.room_url, and room.room_name.
  • Register event handlers with room.on("room.status", handler); use room.emit(...) to publish custom events.
  • Access sub-clients through snake_case attributes such as room.agents, room.database, room.messaging, room.sync, room.containers, room.queues, room.secrets, room.storage, room.developer, and room.livekit.

​
TypeScript / JavaScript

RoomClient in @meshagent/...
  • Instantiate the client with { protocol } and call await room.start({ onDone, onError }) to wait for room_ready.
  • Clean up with room.dispose() when you are finished.
  • Send RPCs with await room.sendRequest(type, payload, data?); readiness is exposed via await room.ready.
  • Emit events with room.emit(event) and consume them using for await (const evt of room.listen()).
  • Sub-clients are camelCase properties: room.agents, room.database, room.messaging, room.sync, room.containers, room.queues, and room.storage.

​
Dart / Flutter

RoomClient in package:meshagent/room_server_client.dart
  • Call await room.start(onDone: ..., onError: ...) after constructing the client; room.ready completes when the server sends room_ready.
  • Dispose resources with room.dispose(); use await room.exec(...) for container execution helpers.
  • Send requests with await room.sendRequest(type, payload, data: ...).
  • Observe room activity with room.events.listen(handler) or by keeping the StreamSubscription returned from room.listen(...).
  • Access sub-clients via camelCase getters: room.agents, room.database, room.messaging, room.sync, room.containers, room.queues, room.secrets, room.storage, room.developer, and room.livekit.

​
.NET

Meshagent.RoomClient
  • Construct var room = new RoomClient(protocol); and call await room.ConnectAsync(); to wait for readiness.
  • Dispose with await room.DisposeAsync(); or await using var room = new RoomClient(protocol);.
  • Send RPCs using await room.SendRequest(type, payload, data);; session metadata is available via room.SessionId, room.RoomUrl, and room.RoomName.
  • Register handlers with room.On("room.status", handler) and raise custom events through room.Emit(name, data).
  • Sub-clients are exposed as PascalCase properties: room.Agents, room.Database, room.Messaging, room.Sync, room.Containers, room.Queues, room.Storage, room.Developer, and room.Livekit.