Skip to main content
MeshDocuments enable your agents to share and synchronize information in real time across platforms. They resemble a web page’s structure but offer much greater flexibility. For example, if you want to generate website content with your agents, you can start with a simple HTML-compatible document format: 
<html>
    <body>
        <p class="content"></p>
    </body>
</html>
A MeshDocument, like an HTML document, is composed of elements that can have child elements and attributes. However, MeshDocuments introduce additional features and capabilities that go beyond standard HTML or XML.

​
Defining Your Document Structure

To define the structure of a MeshDocument, you start by creating a schema using the MeshSchema class. A schema:
  • 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.
Similar to how a web page is structured, a MeshSchema begins with a root element that includes an allowed tag name and optional attributes. Afterward, you can define additional tags, their attributes, and the types of child nodes they can contain.

​
Example Schema

Suppose you have a basic web page structure and want to define a schema for it. In Python: 
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"),
            ],
        ),
    ],
)

​
Creating a MeshDocument

Many LLMs (such as OpenAI) and agent frameworks (such as MeshAgent) support JSON Schemas for defining inputs and outputs. Generating an OpenAI-compatible JSON schema from your MeshSchema requires only one line of code: 
json_schema = schema.to_json()
To create a MeshDocument based on your schema and enable synchronization across different clients, use the MeshAgent runtime: 
import os
import asyncio
from meshagent.api import (
    RoomClient,
    WebSocketClientProtocol,
    ParticipantToken,
    ApiScope,
    ParticipantGrant,
)
from meshagent.api.helpers import meshagent_base_url, websocket_room_url


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():
    # Define a unique room name
    room_name = "my-room"

    async with RoomClient(
        protocol=WebSocketClientProtocol(
            url=websocket_room_url(room_name=room_name, base_url=meshagent_base_url()),
            token=ParticipantToken(
                name="participant",
                project_id=env("MESHAGENT_PROJECT_ID"),
                api_key_id=env("MESHAGENT_KEY_ID"),
                grants=[
                    ParticipantGrant(name="room", scope=room_name),
                    ParticipantGrant(name="role", scope="agent"),
                    ParticipantGrant(name="api", scope=ApiScope.agent_default()),
                ],
            ).to_jwt(token=env("MESHAGENT_SECRET")),
        )
    ) as room:
        print(f"Connected to room: {room.room_name}")
        # open our document
        document = await room.sync.open(path="hello-world.document")

        # wait for the document to sync from the server
        await document.synchronized

        # our root element is automatically added to the document, let's construct the sample document by inserting
        # a body with a paragraph element
        document.root.append_child(tag_name="body", attributes={"text": "hello world!"})

        # wait before closing so the sync can finish
        await asyncio.sleep(3)


asyncio.run(main())