Skip to content

Magic Variables

Overview

Magic variables are declared input fields that trigger behavior beyond normal context storage. The examples below are field fragments: a complete agent node also needs type, id, directive, completionCondition and connections. A magic input is not automatically a bare-name global.

execution_note

Updates the execution’s arbitrary note field for tracking purposes. It never supplies the task heading. Set or rename the task through execution task identity.

Usage

{
"inputSchema": {
"type": "object",
"properties": {
"execution_note": {
"type": "string",
"description": "Note to identify this execution"
}
}
}
}

Behavior

When agent provides execution_note:

  1. Value stored in context like normal
  2. Execution record’s note field updated in database
  3. Note visible in execution lists and session queries

With the shown properties declaration, the value remains node-local and is referenced as node-id.execution_note. To use a bare global, declare it in variableRegistry and write it through globalInputs instead.

Use Cases

Track what’s being worked on:

{
"directive": "Document what you're working on for tracking.",
"inputSchema": {
"properties": {
"execution_note": {
"type": "string",
"description": "Feature/task being developed"
}
},
"required": ["execution_note"]
}
}

Update note on task changes:

{
"directive": "Task requirements changed. Update the execution note.",
"inputSchema": {
"properties": {
"execution_note": { "type": "string" }
}
}
}

execution_note passes through inputSchema validation. Include in required array to enforce agents provide a note under this node’s contract; it does not require or establish a task name.

Querying Notes

Notes appear in session queries:

mcp__moira__execution({ action: "executions" });
// Returns executions with note field populated

System Variables

These variables are automatically available in context:

executionId

Current process execution ID.

{{executionId}}

workflowId

Current workflow identifier.

{{workflowId}}

runUrl

The run’s page in the web app, built from the server’s configured host and base path (<protocol>://<host>[/<base path>]/executions/<executionId>, with http for a localhost host and https otherwise). A notification already links it from its heading; use it to point at the run from any other text.

{{runUrl}}

userId

The user who owns this execution: {{userId}}. This does not authorize an operation for another user.

Usage Example

{
"directive": "Process ID: {{executionId}}\nWorkflow: {{workflowId}}\n\nDocument this for reference."
}

Expression Variables

Variables modified by expression nodes:

Counter Variables

Declared as globals in variableRegistry with a default:

{
"variableRegistry": {
"current_step_index": { "type": "number", "description": "Current step index", "default": 1 },
"current_iteration": { "type": "number", "description": "Current iteration", "default": 1 }
}
}

Modified by expression (expression nodes assign to globals by bare name):

{
"type": "expression",
"expressions": ["current_step_index = current_step_index + 1", "current_iteration = 1"]
}

Declare counter variables in variableRegistry with a default so they exist before expression nodes access them.

Template Processing

All magic and context variables work with templates:

Simple Access

{{variable_name}}

Nested Access

{{user.profile.name}}

Array Access

{{items[0]}}
{{items[0].field}}

Conditional Templates

{{#if intake.execution_note}}Note: {{intake.execution_note}}{{/if}}

Here intake is the node that declared and returned the local field.

See Also