Variable Resolution

Mesh provides a powerful variable resolution system that allows you to reference data across nodes using template syntax. Variables use the `` syntax and can reference user input, node outputs, global variables, and more.

Overview

The VariableResolver processes template strings at runtime, replacing `` references with actual values from the execution context. This enables dynamic prompt construction and data flow between nodes.

Supported Variable Types

User Input Variables

Reference the initial input to your graph:

# Basic input reference
system_prompt="Analyze this topic: "

# Nested field access (requires structured input)
system_prompt="Write about  and "

# Alternative syntax (same as $input)
system_prompt="User asked: "

Important: Use syntax, not. The $input. prefix is required for field extraction.

Node Output Variables

Reference the output of other nodes in your graph:

# Reference entire node output
system_prompt="Previous result: "

# Access nested fields in node output
system_prompt="The content was: "

# Deep nesting supported
system_prompt="User name: "

Node IDs must match the id parameter used when creating the node.

Global Variables

Access global variables from the execution context:

# Reference global variable
system_prompt="Hello !"

# Nested global variables
system_prompt="Theme: "

Global variables are passed via ExecutionContext.variables.

Chat History

Access the full conversation history:

system_prompt="Given this history: , respond appropriately."

Formats chat history as:

user: Hello
assistant: Hi there!
user: How are you?

Iteration Variables

When using LoopNode, access the current iteration context:

# Current iteration value
system_prompt="Process item: "

# Nested field in iteration value
system_prompt="Name: , Age: "

# Iteration metadata
system_prompt="Processing item  of "

Automatic Input Parsing

Mesh can automatically parse natural language input into structured data when your system prompt references multiple input fields.

How It Works

When your system prompt contains multiple `` variables, Mesh automatically:

1. Detects the field names you’re referencing
2. Parses the natural language input using an LLM
3. Structures the data for variable resolution
4. Resolves your prompt with the extracted values

Example

System Prompt:

system_prompt="Write 3 posts about , and 2 about "

Natural Language Input:

"1. dogs, 2. cats"

What Happens:

1. Mesh detects topic1 and topic2 fields
2. Calls an LLM to parse: "1. dogs, 2. cats" → {"topic1": "dogs", "topic2": "cats"}
3. Resolves prompt: "Write 3 posts about dogs, and 2 about cats"

Performance

• Zero overhead when not needed (detection is pattern-based)
• Only triggers when 2+ `` variables are detected
• Uses gpt-4o-mini for fast, cost-efficient parsing
• Skips parsing if input is already structured (dict/JSON)

Syntax Requirements

For automatic parsing to work:

✅ Correct:

❌ Incorrect:

          # Missing $input prefix
           # Missing $ and prefix
    # Use dot notation, not underscore

Structured Input (No Parsing)

If you provide structured input directly, parsing is skipped:

# Input as JSON/dict
input_data = {
    "topic1": "dogs",
    "topic2": "cats"
}

# Variables resolve directly
system_prompt="Write about  and "
# Result: "Write about dogs and cats"

Variable Resolution API

In Python Code

from mesh.utils.variables import VariableResolver

# Create resolver with execution context
resolver = VariableResolver(context)

# Resolve a template string
template = "User asked: , agent said: "
resolved = await resolver.resolve(template)

# Resolve all strings in a dictionary
data = {
    "prompt": "Analyze ",
    "title": "Response to "
}
resolved_data = resolver.resolve_dict(data)

In Agent Nodes

Agent nodes automatically resolve system_prompt variables:

from mesh.nodes.agent import AgentNode

agent_node = AgentNode(
    id="writer",
    agent=vel_agent,
    system_prompt="Write about  in the style of "
)

In ReactFlow JSON

Variables work in Flowise/ReactFlow configurations:

{
  "nodes": [
    {
      "id": "agent_1",
      "type": "agentAgentflow",
      "data": {
        "inputs": {
          "agent": "writer",
          "systemPrompt": "Analyze  and compare to "
        }
      }
    }
  ]
}

Best Practices

1. Use Descriptive Field Names

# Good - clear intent



# Bad - unclear

2. Provide Fallbacks

When a variable is missing, it’s replaced with an empty string. For critical fields, validate inputs:

# Check for required fields in your node logic
if not input.get("topic"):
    raise ValueError("Missing required field: topic")

3. Structure Your Data

For complex data, use structured input instead of relying on parsing:

# Structured input (preferred for APIs)
{
    "query": "search term",
    "filters": {"category": "tech", "date": "2025"},
    "limit": 10
}

# Natural language (good for chat UIs)
"Find tech articles from 2025, limit 10 results"

4. Test Parsing

When using automatic parsing, test with various input formats:

# Different ways users might express the same thing:
"1. dogs, 2. cats"
"First: dogs, Second: cats"
"dogs and cats"
"Write about dogs, then cats"

Troubleshooting

Variable Not Resolved

Symptom: `` appears in output

Causes:

• Variable name typo
• Node hasn’t executed yet (wrong execution order)
• Field doesn’t exist in the data structure

Solution:

# Check node execution order
graph.validate()  # Ensures nodes are reachable

# Verify field exists
print(context.get_node_output("node_id"))

# Check variable syntax
  # ✅ Correct
         # ❌ Missing $ and prefix

Parsing Not Triggered

Symptom: Natural language input not being parsed

Causes:

• Only one `` variable (parsing requires 2+)
• Input is already structured (dict)
• Wrong syntax (e.g., instead of)

Solution:

# Requires at least 2 fields for auto-parsing
 and   # ✅ Triggers parsing
 only                    # ❌ No parsing

Parsing Extracts Wrong Data

Symptom: Parsed fields don’t match user input

Causes:

• Ambiguous natural language input
• Field names don’t match the content

Solution:

# Use clear field names that match expected content
system_prompt="Topic: , Tone: "

# Good input: "topic is AI, tone is professional"
# Bad input: "write about AI in a good way"  # "tone" field unclear

Examples

Multi-Step Pipeline

from mesh.nodes.agent import AgentNode
from mesh.core.graph import ExecutionGraph

# Step 1: Extract entities
extractor = AgentNode(
    id="extractor",
    agent=extractor_agent,
    system_prompt="Extract entities from: "
)

# Step 2: Process each entity (references previous node)
processor = AgentNode(
    id="processor",
    agent=processor_agent,
    system_prompt="Process entities: "
)

# Step 3: Summarize (references multiple nodes)
summarizer = AgentNode(
    id="summarizer",
    agent=summarizer_agent,
    system_prompt="Original: , Extracted: , Processed: "
)

graph = ExecutionGraph.from_nodes_and_edges(
    nodes={"extractor": extractor, "processor": processor, "summarizer": summarizer},
    edges=[
        Edge("START", "extractor"),
        Edge("extractor", "processor"),
        Edge("processor", "summarizer"),
        Edge("summarizer", "END")
    ]
)

Personalized Agent

# Set global variables
context.variables = {
    "user_name": "Alice",
    "expertise_level": "beginner",
    "preferred_style": "casual"
}

# Agent uses variables in prompt
agent_node = AgentNode(
    id="assistant",
    agent=agent,
    system_prompt="""
    You are helping , who is a .
    Use a  tone.
    User question: 
    """
)

Natural Language Multi-Input

# System prompt with multiple fields
agent_node = AgentNode(
    id="content_writer",
    agent=writer_agent,
    system_prompt="""
    Write  social media posts about .
    Target audience: .
    Tone: .
    """
)

# User provides natural language input
input_text = "Write 5 posts about AI for developers in a technical tone"

# Mesh automatically parses to:
# {
#   "num_posts": "5",
#   "topic": "AI",
#   "audience": "developers",
#   "tone": "technical"
# }

Related Documentation

• Nodes - Understanding node types and configuration
• Execution - How graphs execute and manage state
• Events - Event system for monitoring execution
• Vel Integration - Using Vel agents with Mesh