Sync

Documentation Index

Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

CLI commands

meshagent room sync --help
meshagent room sync create --room myroom docs/briefing.mesh --schema ./briefing.schema.json
meshagent room sync show --room myroom docs/briefing.mesh
meshagent room sync inspect --room myroom docs/briefing.mesh

​

Why use the Sync API?

• Keep shared state in a live document instead of relying only on chat history.
• Let multiple participants collaborate on the same structured content at once.
• Define document schemas that help users and agents write valid data.

​

How it works

​

Permissions and grants

​

Defining Your Document Structure

• Documents the structure of your MeshDocument for anyone in your organization.
• Ensures agents and users don’t write invalid data to the document.
• Allows agents to automatically generate, manipulate, and validate structured documents.
• Automatically generates LLM-compatible schemas for structured outputs.
• Synchronizes documents across all platforms that MeshAgent supports.

​

Example Schema

from meshagent.api.schema import MeshSchema, ElementType, ChildProperty, ValueProperty

schema = MeshSchema(
    root_tag_name="html",
    elements=[
        ElementType(
            tag_name="html",
            properties=[
                # a ChildProperty describes the type of children that
                # an element allows. There can be at most one child
                # property for each element type, but the child property
                # can allow multiple types of child elements.
                ChildProperty(name="children", child_tag_names=["body"])
            ],
        ),
        ElementType(
            tag_name="body",
            properties=[
                # Our body can only contain paragraph elements
                ChildProperty(name="children", child_tag_names=["p"])
            ],
        ),
        ElementType(
            tag_name="p",
            properties=[
                # A ValueProperty property describes an attribute that
                # contains a single value
                ValueProperty(name="class", type="string"),
            ],
        ),
    ],
)

json_schema = schema.to_json()

​

Creating a MeshDocument

import asyncio
from meshagent.api import RoomClient


async def main():
    # Run with:
    # meshagent room connect --room=my-room --identity=participant-name -- python3 documents-writing.py
    path = "hello-world.document"

    async with RoomClient() as room:
        print(f"Connected to room: {room.room_name}")
        document = await room.sync.open(path=path, create=True)
        try:
            await document.synchronized
            document.root.append_child(
                tag_name="body", attributes={"text": "hello world!"}
            )
            await asyncio.sleep(1)
        finally:
            await room.sync.close(path=path)


asyncio.run(main())

​

API reference

​

create(path, json=None)

meshagent room sync create \
  --room myroom \
  my/path \
  --schema ./schema.json \
  --json '{"key":"value"}'

• Parameters:
  • path: Document path.
  • json: Optional initial JSON payload.
• Description: Create a new MeshDocument at the given path. The server infers the schema from the document extension.

​

describe(path)

doc_json = await room.sync.describe(path="my/path")

• Parameters:
  • path: Document path.
• Returns: The current document root as JSON.
• Description: Read the current state of a MeshDocument without opening a live sync session.
• Availability: Python exposes room.sync.describe today. Other SDKs can use open() or a lower-level request until they add a helper.

​

open(path, create=True)

doc = await room.sync.open(path="my/path", create=True)

• Parameters:
  • path: Document path.
  • create: When true, create the document if it does not already exist.
• Returns: A MeshDocument tied to that path.
• Description: Open a live synchronization session for the document. Local changes are sent automatically while the document remains open.

​

close(path)

await room.sync.close(path="my/path")

• Parameters:
  • path: Document path.
• Description: Close the local sync session for that document path. Once closed, local changes are no longer synchronized.

​

sync(path, data)

await room.sync.sync(path="my/path", data=b"some bytes")

• Parameters:
  • path: Document path.
  • data: Serialized sync bytes.
• Description: Send encoded sync data directly to the server. Use this when you already have the wire-format change payload.

​

Notes

• Synchronized Changes
  Once a document is opened, any local changes you make in the associated MeshDocument are automatically queued for sending, thanks to sendChangesToBackend. You rarely need to call sync() manually unless you want to send raw data yourself.
• Reference Counting
  The SyncClient internally tracks how many times a document is opened via the same path. Calling open multiple times for the same path returns the same underlying document. Only when all references are closed (via close()) will the client actually disconnect.
• Error Handling
  If a request fails, the RoomClient may throw an error (like RoomServerException). Wrap calls in try/catch (or use .catch(...)) to handle them gracefully.
• Concurrency and Performance
  • For high throughput, ensure that your RoomClient and server are configured for concurrent operations.
  • The SyncClient uses a StreamController internally to manage queued updates, sending them asynchronously to the server.

​

Related guides

• Room API Overview
• Storage API