Scope: this page is the technical architecture — how agents are defined, what tools they get, and how they collaborate inside the mesh. For the concepts-and-philosophy companion (what agentic AI is, traps, human-in-the-loop), see Agentic AI — concepts.

MeshWeaver integrates AI agents as first-class citizens. Agents can query data, navigate structures, execute tasks, and collaborate with one another — all through the same unified mesh references that every other component uses.

The Mesh Graph is the central knowledge hub — internal agents discover context from it dynamically, and external AI systems connect to it via bidirectional MCP.

Design Philosophy

Self-Guided Discovery

Traditional agent architectures front-load everything into a system prompt: schemas, business rules, examples, edge cases. As the domain grows, that prompt grows — fragile, expensive, and hard to maintain.

MeshWeaver agents take a different approach: they find documentation as they go. Rather than encoding all knowledge upfront, agents dynamically discover context from the mesh itself. The mesh is the system prompt.

Example: Email Processing Workflow

The following diagram shows how an agent handles an incoming email without any domain knowledge baked in at start-up:

1. An email arrives and triggers agent processing.
2. The agent detects the email's purpose (inquiry, claim, request).
3. Based on purpose, it loads instructions from the mesh — e.g. Insurance/Claims/Instructions.
4. Those instructions guide the agent to gather more context: line of business, responsible department.
5. The agent loads department-specific instructions and schemas.
6. Execution continues with full context until the task completes.

Because instructions live in the mesh, updating business rules requires no code change and no prompt rewrite — just edit the relevant node.

Agents as Data Elements

Agents are stored as ordinary nodes in the mesh, in a flat, well-known Agent namespace per partition:

Agent/                  <- platform defaults (shipped)
  Assistant
  Worker
rbuergi/Agent/          <- the user's own agents + overrides
  ClaimsProcessor
acme/Agent/             <- the space's agents
  Underwriter

Resolution is a tiered registry query, not a hierarchy walk. AgentPickerProjection.BuildRegistryQuery emits a single exact-membership alternation over the user's, the space's, and the current node type's partition namespaces plus the platform default, with the platform tier always present and listed last:

namespace:{user}/Agent|{space}/Agent|{typePartition}/Agent|Agent   nodeType:Agent

There is no scope:descendants and no graph search on this query, and no "entry agent" flag — an agent placed at Insurance/Claims/Agent/ClaimsProcessor is not discovered by it. What you get is:

• Per-user and per-space agents that override a platform agent of the same name — precedence is resolved from each result's own partition (most specific wins), never from the order of the query rows
• A platform tier that is always present as the fallback
• Default selection by node Order (the -1 convention puts an agent first)

Skills are the exception, deliberately. BuildSkillQueries emits separate queries and scopes the space's and the node type's partitions to the whole subtree (path:{partition} scope:descendants nodeType:Skill), because a space or plugin ships skills wherever its content is organised. A subtree scope and an exact-namespace membership cannot be folded into one clause, which is why skills cost one extra query per layer. The user's own skills stay flat at {user}/Skill.

Multi-Agent Collaboration

Agents rarely work alone. MeshWeaver orchestrates teams of specialised agents, each sized for its job:

Agent Roles

Custom agents are ordinary Agent nodes in the mesh. They inherit from a base agent and add domain-specific instructions, tools, and behaviours — no code required.

Custom Skills

Define skills to provide detailed, step-by-step instructions for specific operations. Skills live in the mesh alongside the data they operate on (a skill is "a thing that does something" — see ChatCommands):

Insurance/Claims/
  Skill/
    import.md      <- /import skill instructions
    validate.md    <- /validate skill instructions
    assign.md      <- /assign skill instructions

Example /import skill:

# Import Skill

This skill imports claims from external sources.

## Steps
1. Validate the source format (CSV, JSON, XML)
2. Map fields to Claims schema
3. Check for duplicates using claim reference number
4. Create new claim records
5. Trigger validation workflow

## Required Fields
- claimReference, policyNumber, lossDate, description

Skills are context-aware and discoverable within a partition subtree. When the active context or node type is in the Insurance partition, the skill layer for that partition is path:Insurance scope:descendants nodeType:Skill — so Insurance/Claims/Skill/import.md is found wherever it sits under Insurance, no wiring needed. It is not found from an unrelated partition; the subtree layers are keyed to the context and node-type partitions plus the user's own flat {user}/Skill and the platform Skill defaults.

MeshPlugin Tools

Agents interact with the mesh through MeshPlugin, which exposes a concise set of operations:

Read Operations

Get — Retrieve a node or its children by path:

Get("@Insurance/Claims/CLM-2024-001")     -> Returns claim JSON
Get("@Insurance/Claims/*")                -> Returns all claims (children)

Get with Unified Path prefixes — Access schemas and data models without knowing the underlying storage:

Get("@Cornerstone/schema/")             -> JSON Schema for content type
Get("@Cornerstone/schema/Pricing")      -> Schema for a specific named type
Get("@Cornerstone/model/")              -> Full data model with all types

Search — Query with GitHub-style syntax:

Search("nodeType:Claim status:Open")        -> All open claims
Search("name:*property*")                   -> Name contains 'property'
Search("lob:Commercial", "@Insurance")      -> Commercial LOB under Insurance

Write Operations

Create — Create new nodes:

Create('{"id": "CLM-2024-002", "namespace": "Insurance/Claims",
  "name": "Property Damage Claim", "nodeType": "Claim",
  "content": {"status": "Open"}}')

Update — Modify existing nodes. The canonical workflow is Get → modify → Update:

// 1. Get existing: result = Get("@Insurance/Claims/CLM-2024-001")
// 2. Modify the JSON
// 3. Pass as array:
Update('[{"id": "CLM-2024-001", "namespace": "Insurance/Claims",
  "name": "Updated Claim", "nodeType": "Claim",
  "content": {"status": "Closed"}}]')

Delete — Remove nodes by path:

Delete('["Insurance/Claims/CLM-2024-002"]')

Navigation

NavigateTo — Display a node's view in the UI:

NavigateTo("@Insurance/Claims/CLM-2024-001")  -> Shows claim detail view

Path Shorthand & Unified Path

The @ prefix is a convenient shorthand. Unified Path prefixes let agents address specific resource types without knowing the underlying structure:

Including External MCP Servers

MeshWeaver supports the Model Context Protocol (MCP) so agents can reach out to any compatible external tool provider:

Available integrations:

Tools from external MCP servers appear automatically in agent context — no additional wiring required.

Exposing MeshWeaver as an MCP Server

The relationship is bidirectional. MeshWeaver also acts as an MCP server, so external AI systems can include MeshWeaver as a tool provider:

Common use cases:

• GitHub Copilot / Claude Code: Read task descriptions and prompts from MeshWeaver, then execute using external agents
• Microsoft Copilot: Query live business data while composing Word documents or emails
• Snowflake Agents: Access organisational context and workflows
• Custom integrations: Any MCP-compatible AI system

MCP Server Tools

The MCP server exposes the same core operations as the internal MeshPlugin, so external AI systems get full mesh access. (The live surface is larger than this table — it also carries patch, move, copy, upload, autocomplete, execute_script, render_area, compile / get_diagnostics, the lsp_* pre-flight tools, and the version/recycle tools. Enumerate the server's own tool list rather than treating this as exhaustive.)

External vs. internal NavigateTo: When called from an external system, NavigateTo returns a URL rather than rendering inline, because external consumers operate outside the MeshWeaver UI.

🚨 The URL shape is {baseUrl}/{meshpath} — nothing else. The mesh path is appended directly, with no /node/ segment and no URL-escaping of the path separators: https://app.example.com/Insurance/Claims, never https://app.example.com/node/Insurance%2FClaims. A leading @ is stripped; an empty path returns the base URL alone.

Example — Claude Code using MeshWeaver MCP:

Get("@Cornerstone/Claims/*")              -> List all claims
Get("@Cornerstone/schema/")               -> Get content type schema
Search("nodeType:Claim status:Open")      -> Find open claims
Create('{"id": "CLM-NEW", ...}')          -> Create a claim

Alternative AI APIs

Some platforms provide dedicated APIs alongside MCP for direct AI access:

These APIs are used when a hub needs to invoke AI from an external system directly:

-- Snowflake Cortex via SQL
SELECT
  claim_id,
  SNOWFLAKE.CORTEX.SUMMARIZE(description) as summary,
  SNOWFLAKE.CORTEX.SENTIMENT(customer_feedback) as sentiment
FROM claims
WHERE status = 'Open'

Agent Context Discovery

At runtime, an agent builds its context from the mesh — no pre-loaded knowledge required:

1. Task Descriptions — Markdown nodes that explain what needs to be done
2. Data Schemas — NodeType definitions with field metadata and validation rules
3. Custom Skills — /skill instruction nodes for specific operations
4. Domain Knowledge — Documentation distributed throughout the hierarchy

This keeps agents thin at start-up and rich in context by the time they act.

Summary of Benefits