Message Schemas

Structured Message Schemas in Partite Mesh

Partite Mesh uses a disciplined, trimmed subset of JSON Schema to describe every typed message exchanged between Agents, Intents, Call Links, Transfer Links and external callers. Clear structure + rich field descriptions dramatically improve instruction following, constrain token usage, and enable advanced features like grounding & artifact referencing without brittle text scraping.

This page explains:

Design goals & why a subset
Core restrictions
Grounding extensions (x-partite-grounding-config)
Artifact references (format: "x-partite-ref")
Runtime grounding & citation flow
Authoring best practices & common pitfalls
End‑to‑end examples

1. Design Goals

Message schemas serve as precise contracts between cooperating agents. Each schema:

Narrows scope → smaller prompts, better focus, less hallucination.
Provides explicit field semantics via required descriptions → models fill fields more accurately.
Forms the backbone for grounding (fact verification) and artifact exposure.

Rather than chase full JSON Schema expressiveness (which often confuses LLMs), Partite.ai Mesh intentionally limits complexity for higher reliability.

2. Core Restrictions (Subset of JSON Schema)

Restriction	Rationale
Root must be an `object`	Consistent structural framing for prompt assembly & grounding
Every field MUST have a `description`	Boosts model accuracy; avoids ambiguous output intent
No `oneOf`, `anyOf`, `$ref`, complex combinators	Keeps schema cognitively simple for the model; maximum compatibility across model providers

If you feel tempted to add conditional polymorphism, prefer splitting responsibilities into multiple Agents / Output Message Types or adding a discriminant string field.

3. Grounding Extension: `x-partite-grounding-config`

Add this object to any field to require citations and optional value verification. All properties optional unless noted.

Property	Type	Default	Purpose
`enabled`	boolean	`true` (if object present)	Turns grounding on for the field
`minimumCitationCount`	integer	`0`	Require multiple independent sources (e.g. cross‑checking)
`validateText`	boolean	`false`	Enforce exact match of field value against source text/data
`preserveCitations`	boolean	`false`	Keep inline citation tags in final returned message

When grounding is enabled, the runtime injects citation instructions so the model knows to cite sources for the field. Sources can be tool results or artifact data.

Grounding Example

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "Concise explanation of the incident"
    },
    "incidentId": {
      "type": "string",
      "description": "Identifier of the incident (must match cited source exactly)",
      "x-partite-grounding-config": {
        "enabled": true,
        "validateText": true
      }
    },
    "rootCause": {
      "type": "string",
      "description": "Likely root cause supported by at least two evidence sources",
      "x-partite-grounding-config": {
        "minimumCitationCount": 2
      }
    }
  },
  "required": ["summary", "incidentId"]
}

Choosing Fields to Ground

Any field that must be constructed from factual information provided by tools or artifacts should have grounding applied. This will prevent hallucinations by ensuring that all output is rooted in verifiable facts.

4. Artifact References (`format: "x-partite-ref"`)

To pass artifacts (image, document, large dataset) to agents artifact references are used. To specify that a field in a schema is an artifact referene, define a property of type: object with format: "x-partite-ref". At runtime, the artifact will be presented to the LLM using an appropriate representation. In the case of images or documents, the data will be exposed to the LLM directly. In the case of a remote artifact provided by a tool, the artifact’s metadata and applicable tool operations are exposed to the model, enabling interaction (summarize, filter, extract) without bloating context.

Artifact Reference Example

{
  "type": "object",
  "properties": {
    "logBundle": {
      "type": "object",
      "format": "x-partite-ref",
      "description": "Reference to collected application logs artifact"
    },
    "metricsSnapshot": {
      "type": "object",
      "format": "x-partite-ref",
      "description": "Reference to performance metrics artifact"
    },
    "analysis": {
      "type": "string",
      "description": "Interpretation of logs and metrics (include grounded numeric values)"
    }
  },
  "required": ["analysis"]
}

Why Use Artifact References?

Preserve token budget
Enable tool‑mediated inspection (e.g., query subset of dataset)
Provide multi‑modal context (e.g., images) cleanly

5. Runtime Grounding & Citation Flow

When a grounded field is returned:

Agent embeds citation tags referencing sources (tool results, artifacts).
Mesh validates each citation: existence + property presence.
Optional text validation (validateText) checks verbatim match.
If any required field fails: the LLM is prompted to correct the output.
Citations stripped or preserved according to preserveCitations.

This enforces factual linkage without forcing raw source content into the prompt, reducing hallucination risk.

6. Authoring Best Practices

Practice	Benefit
Keep schemas minimal initially	Focus model; add fields only after observing repeated implicit data
Provide concrete, outcome‑oriented descriptions	Improves fill accuracy & reduces rambling
Split large optional areas with minimal overlap into separate Output Message Types	Cleaner evolution & versioning
Use multiple Agents instead of polymorphic schemas	Enhances parallelization & model right‑sizing

Common Pitfalls

Pitfall	Mitigation
Attempting `oneOf` style variability	Create distinct message types or separate agents
Missing descriptions	Add concise, specific intent for every field
Grounding everything	Limit to critical facts to avoid noise
Inlining large blobs	Convert to artifacts + reference

7. End-to-End Examples

A. Simple Input Schema (Intent Invocation)

{
  "type": "object",
  "properties": {
    "issueText": { "type": "string", "description": "Raw end user problem report" },
    "environment": { "type": "string", "description": "Runtime environment or OS if known" }
  },
  "required": ["issueText"]
}

B. Output Message with Mixed Grounding

{
  "type": "object",
  "properties": {
    "summary": { "type": "string", "description": "Short narrative summary of the issue" },
    "probableCause": { "type": "string", "description": "Likely single root cause with supporting facts", "x-partite-grounding-config": { "minimumCitationCount": 2 } },
    "nextStep": { "type": "string", "description": "Recommended immediate remediation action" },
    "incidentId": { "type": "string", "description": "Incident identifier (must match source)", "x-partite-grounding-config": { "validateText": true } }
  },
  "required": ["summary", "incidentId"]
}

C. Artifact-Aware Output

{
  "type": "object",
  "properties": {
    "logRef": { "type": "object", "format": "x-partite-ref", "description": "Reference to aggregated log artifact" },
    "screenshot": { "type": "object", "format": "x-partite-ref", "description": "User-provided screenshot artifact" },
    "finding": { "type": "string", "description": "Key finding derived from artifacts" },
    "confidence": { "type": "string", "description": "Qualitative confidence rating (high/medium/low)" }
  },
  "required": ["finding"]
}

10. Summary

Partite Mesh message schemas are lean contracts that keep prompts precise, enable modular agent orchestration, and power grounding + artifact integration. Embrace simplicity early, evolve deliberately, and use grounding selectively to enforce trust in critical outputs.

If you need deeper configuration examples or run into edge cases, open a discussion or issue - feedback drives refinement.

Getting Started MCP Extensions