Nodes

Nodes are the building blocks of MindedJS flows - discrete processing units that handle different aspects of your agent's workflow.

Common Node Properties

All nodes require these fields:

• name (string, required): Unique identifier for the node

• type (NodeType, required): The node type (see table below)

• displayName (string, required): Human-readable label shown in the editor

Node Types Overview

Node Type (NodeType)	Purpose	Description
trigger	Entry Points	Start flows from various sources
promptNode	LLM Processing	Generate responses using language models
tool	Actions	Execute external functions and APIs
junction	Flow Control	Route and organize flow logic
jumpToNode	Flow Control	Jump to specific nodes or subflows
browserTask	Automation	AI-powered web page interactions

Trigger Nodes

Trigger nodes are entry points that start your flows and initialize them with memory and messages.

Trigger Nodes Properties

• type (NodeType, required): Always trigger

• triggerType (string, required): The type of trigger to use. See the table below for details.

triggerType	Description
webhook	Triggered by HTTP webhook calls
app	Triggered by external app events (e.g., Zendesk ticket created)
schedule	Triggered on a cron schedule

Webhook Trigger (webhook)

Triggered by HTTP requests to the agent's webhook endpoint.

Properties:

• autoTrigger (boolean, optional): Auto-execute when testing flows in the UI editor

• defaultPayload (string, optional): Default JSON payload for testing in the UI editor

- type: trigger
  triggerType: webhook
  name: payment-webhook
  displayName: Payment Webhook
  autoTrigger: true
  defaultPayload: '{"orderId": "123"}'

App Trigger (app)

Triggered by external application events.

- type: trigger
  triggerType: app
  name: zendesk-ticket-created
  displayName: Zendesk Ticket Created
  appTriggerId: zendesk-new-ticket

Schedule Trigger (schedule)

Triggered on a cron schedule.

Properties:

• cronExpression (string, required): Cron expression (e.g., 0 9 * * * for daily at 9 AM)

• timezone (string, optional): Timezone for the schedule (defaults to UTC)

- type: trigger
  triggerType: schedule
  name: daily-report
  displayName: Daily Report
  cronExpression: '0 9 * * *'

Trigger Implementation

Handle triggers in your agent code:

import { Agent, AgentEvents } from '@minded-ai/mindedjs';

const agent = new Agent({ /* agent options... */ });

agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
  if (triggerName === 'payment-webhook' && triggerBody.body?.orderId) {
    state.memory.orderId = triggerBody.body.orderId;
    return { isQualified: true };
  }
  
  // Return { isQualified: false } to prevent flow execution
  return { isQualified: false };
});

export default agent;

Prompt Nodes

Prompt nodes process input through LLM to generate intelligent responses or invoke tools. Prompt nodes are commonly used to notify and collect information.

Use Cases

• Notify the user about the result of a previous node.

• Collect information from the user.

• Invoke (scoped) tools.

Prompt Nodes Properties

• type: (NodeType, required) Always promptNode

• prompt (string, required): The prompt to be sent to the LLM. The prompt is an instruction for what AI message to generate or a (scoped) tool to invoke. This is not general instruction for what the agent should do (e.g. "wait for x").

• humanInTheLoop (boolean, optional): When true, pauses execution after this node for human input before continuing. Use this property only if you need to gather an input from the user. Usually combined with a promptCondition edge to allow for iterative processing over human input.

• canStayOnNode (boolean, optional): When true, allows the node to route back to itself for iterative processing. Usually combined with humanInTheLoop: true to allow for iteration over human input.

• llmConfig (boolean, optional): Used to customize the LLM used by the prompt node. Leave empty to use the default LLM configured.

• sendAiMessage (boolean, optional): Default: true. When true emits AgentEvents.AI_MESSAGE event to send the response to the user. When false, the AI response is processed internally without sending to the user. Set to false for internal calculations, reasoning, or decision-making logic that shouldn't be visible to users.

- type: promptNode
  name: generate-order-confirmation
  displayName: Generate Order Confirmation
  prompt: 'Generate Order Confirmation for {memory.customerName}'
  sendAiMessage: true

Handle AI message (sendAiMessage)

Prompt nodes usually result in an AI message being sent to the user. Use the AgentEvents.AI_MESSAGE event to route the message according to user requirement (e.g., send email, send a Slack message, update Jira ticket, etc.).

agent.on(AgentEvents.AI_MESSAGE, ({ message, state }) => {
  // Send message to Slack channel
  slackChat.postMessage({
    ...options,
    test: message
  });
});;

In development mode (playground), the message is automatically shown in the chat regardless of the message handler.

Context

• Prompt nodes automatically have access to previous nodes' output as context.

• You can inject dynamic values into prompts using placeholders that reference memory, environment variables, tool outputs, and system values.

Available Placeholders

• Memory: {state.memory.propertyName} or {memory.propertyName}

• Tool outputs: {tools.NodeName.propertyName}

• Environment variables: {env.VARIABLE_NAME}

• System values: {system.propertyName}

Memory Placeholders

Access values from the agent's memory state using {memory.propertyName}:

prompt: 'Send a confirmation email to {memory.customerName} that their order {memory.orderId} has been processed successfully'

Nested objects:

prompt: 'Generate a shipping label for delivery to {memory.customer.address.city}, {memory.customer.address.country} and notify the customer'

Array access:

prompt: 'Create a packing list including {memory.orderItems[0]} and {memory.orderItems[1]} with their quantities'

Complex objects:

When referencing entire objects or arrays, they will be serialized to JSON:

prompt: 'Validate the following order data and check for any inconsistencies: {memory.orderDetails}'
# If orderDetails is {id: "123", total: 99.99}, the prompt interpolated as:
# Validate the following order data and check for any inconsistencies: {"id":"123","total":99.99}

Tool/Node Output Placeholders

Access output from previous tool or operator nodes using {tools.NodeName.propertyName}:

# After a tool node named "lookup-customer" returns {email: "[email protected]", tier: "premium"}
prompt: 'Send a personalized welcome email to {tools.lookup-customer.email} with {tools.lookup-customer.tier} tier benefits'

With operator/browser task nodes:

# After an operator node named "scrape-price" with outputSchema field "price"
prompt: 'Compare the scraped price of {tools.scrape-price.price} with our database and alert if there is a significant difference'

Environment Variable Placeholders

Access environment variables using {env.VARIABLE_NAME}:

prompt: 'If the user needs help, direct them to contact support at {env.SUPPORT_EMAIL} or call {env.SUPPORT_PHONE}'

Common use cases:

# API endpoints
prompt: 'Fetch the latest order status from {env.API_BASE_URL}/orders and summarize it for the customer'

# Company information
prompt: 'Draft a professional response thanking the customer for choosing {env.COMPANY_NAME} and offer assistance'

System Placeholders

Access built-in system values using {system.propertyName}:

prompt: 'Log this customer inquiry with timestamp {system.currentTime} and respond with an acknowledgment'
# The timestamp will be: 2024-01-15T10:30:00.000Z

Placeholder Behavior

• String values: Inserted directly into the prompt

• Numbers and booleans: Converted to strings

• Objects and arrays: Serialized to JSON format

• Undefined values: If a placeholder references a non-existent property, it returns the original placeholder unchanged (e.g., {memory.nonexistent} stays as {memory.nonexistent})

• Null values: Rendered as "null"

Complete Example

nodes:
  - type: promptNode
    name: order-confirmation
    displayName: Order Confirmation
    prompt: |
      Order Confirmation for {memory.customerName}
      
      Order Details:
      - Order ID: {memory.orderId}
      - Items: {memory.orderItems}
      - Total: {memory.orderTotal}
      - Customer Tier: {tools.lookup-customer.tier}
      - Shipping to: {memory.shippingAddress.city}
      
      Support: {env.SUPPORT_EMAIL}
      Processed at: {system.currentTime}

Limitations

• Prompt nodes can not save information to memory directly. Rather the user & agent messages are stored in the messages array of the state object. Making user's input available to the next prompt nodes or tools in the form of input schema.

• Image recognition is only supported when a user attaches an image to the message. If you need to extract information from an image, use a tool with agent.llm to process the image. Return the result in the tool response so following prompt nodes can use it.

• By default, prompt nodes send a message to the user. Set sendAiMessage: false if you want internal processing without user-facing output.

Prompt examples

• "Draft a professional email to the merchant requesting verification of the dispute"

• "Ask the user for their contact information (name, email, phone)"

Common Prompt Patterns

Extract Information from User

Use humanInTheLoop: true and canStayOnNode: true with promptCondition edges for iterative information gathering:

nodes:
  - type: promptNode
    name: collect-customer-info
    displayName: Collect Customer Information
    prompt: 'Ask the user for their contact information (name, email, phone).'
    humanInTheLoop: true
    canStayOnNode: true

edges:
  - type: promptCondition
    source: collect-customer-info
    target: validate-info
    prompt: 'Has all required information been collected?'

Notify User

Use standard prompt nodes with stepForward edges for one-way notifications:

nodes:
  - type: promptNode
    name: send-confirmation
    displayName: Send Confirmation
    prompt: 'Send confirmation: Order {memory.orderId}, Total: {memory.orderTotal}'

edges:
  - type: stepForward
    source: process-order
    target: send-confirmation

Custom LLM Configuration

Provide a custom LLM configuration to the prompt node using the llmConfig property with the following fields:

• name: (required) name of the LLM to use, must be one of ChatOpenAI, AzureChatOpenAI, MindedChatOpenAI.

• properties: (optional) LLM configuration properties

nodes:
  - type: promptNode
    name: send-confirmation
    displayName: Send Confirmation
    prompt: 'Send confirmation: Order {memory.orderId}, Total: {memory.orderTotal}'
    llmConfig:
      name: ChatOpenAI
      properties:
        model: gpt-5.2
        temperature: 0
        max_tokens: 500

Internal Processing (No User Message)

To process logic internally without sending a message to the user, set sendAiMessage: false:

- type: promptNode
  name: calculate-refund-amount
  displayName: Calculate Refund Amount
  prompt: 'Based on the order details: {memory.orderItems}, calculate the appropriate refund amount.'
  sendAiMessage: false

Use cases for sendAiMessage: false:

• Internal calculations and reasoning: Determining refund amounts, calculating discounts, analyzing data

• Decision-making logic: Evaluating conditions before taking actions

• Information extraction: Processing and structuring data for subsequent nodes

• Pre-processing: Preparing inputs for tools or other nodes

The AI response is added to conversation history and available to subsequent nodes, but not sent to the user.

Tool Nodes

Tool nodes execute functions to perform actions like API calls, database queries, or external integrations.

Tool Nodes Properties

• type (NodeType, required): Always tool

• toolName (string, required): The name of the registered tool function to execute. Must match a tool defined in your agent's tools configuration.

• prompt (string, optional): The prompt to be sent to the LLM to hint how tool parameters should be inferred.

• parameters (object, optional): The parameters to pass to the tool function. Tool parameters values are inferred by an LLM during runtime. You can override specific input parameters directly to ensure deterministic values. Parameters support placeholder syntax to inject dynamic values from memory, environment variables, other tool outputs, and system values. See Context for more details.

- type: tool
  name: lookup-customer-order
  displayName: Lookup Customer Order
  toolName: lookupOrder
  parameters:
    orderId: '{tools.lookup-customer.orderId}'

Tool Implementation

Tools are registered in your agent code. See Tools for implementation details.

Junction Nodes

Junction nodes provide flow control without processing, useful for organizing routing logic.

Basic Junction

- type: junction
  name: customer-routing-hub
  displayName: Customer Routing Hub

Routing Example

nodes:
  - type: junction
    name: route-customer-request
    displayName: Route Customer Request

edges:
  - source: route-customer-request
    target: vip-support
    type: logicalCondition
    condition: "state.memory.customerTier === 'premium'"
  - source: route-customer-request
    target: standard-support
    type: logicalCondition
    condition: "state.memory.customerTier === 'standard'"

Jump To Nodes

Jump To nodes provide direct navigation to specific nodes, enabling flow transitions and subflow execution.

Jump To Node Properties

• type (NodeType, required): Always jumpToNode

• targetNodeId (string, required) The name of the node to jump to. The target node is resolved across all loaded flows at runtime. If the target node doesn't exist, the flow will error.

Basic Jump To Node

nodes:
  - type: jumpToNode
    name: go-to-order-processing
    displayName: Go To Order Processing
    targetNodeId: process-customer-order

Cross-Flow Navigation

Jump To nodes enable navigation between flows. Target nodes can exist in different flow files, and state is preserved during jumps:

# flows/mainFlow.yaml
nodes:
  - type: jumpToNode
    name: go-to-refund-flow
    displayName: Go To Refund Flow
    targetNodeId: refund-processor  # resolves to node in any loaded flow

# flows/refundFlow.yaml
nodes:
  - type: tool
    name: refund-processor
    displayName: Refund Processor
    toolName: refundOrder

Browser Task Nodes

Browser task nodes allow your agent to interact with web pages using AI-powered automation.

Browser Task Properties

• type (NodeType, required): Always browserTask

• prompt (string, required): The prompt to be sent to the LLM to instruct the browser task.

Basic Browser Task

- type: browserTask
  name: search-products
  displayName: Search Products
  prompt: 'Go to amazon.com and search for wireless headphones under $100'

Custom Model

Specify which AI model to use (default: gpt-5.2):

- type: browserTask
  name: complex-task
  displayName: Complex Web Task
  prompt: 'Navigate to the support page and fill out the contact form'
  model: 'gpt-5.2'

Best Practices

• Use descriptive names: technical-support-specialist not agent-1

• Keep prompts focused: Define specific roles and context, avoid overly broad prompts

• Always include displayName: Required for prompt nodes, recommended for all nodes

Next Steps

• Edges - Connect nodes with intelligent routing

• Tools - Build powerful tool functions

• Memory Types - Design effective state management