Invoke components

Form Builder Component Invocation & Dynamic UI Generation

Overview

The invoke_component mechanism is the standard way for MelodyArc skills to render interactive form-based UI components. It allows skill authors to declaratively define pages, fields, instructions, dynamic options, data-token mappings, and UI panels without writing custom code.

This mechanism ensures that all UI-generating steps behave consistently and follow a predictable lifecycle when able.

Purpose of the Invoke Component

The invoke_component exists to:

• Render form-builder components inside the operator user interface.
• Dynamically populate templates using fill_text.
• Expand _this placeholders based on the active entity.
• Generate option lists automatically when a field declares options: "@partition".
• Populate a data-token that captures the user’s submitted values.
• Pause the workflow by sending a message to the user when appropriate.
• Return a fully populated form_builder component object to the UI engine.

This provides a declarative and standardized approach for collecting structured user input.

When to Use invoke_component

Use this component when:

• A skill step requires user input.
• Fields or pages must be dynamically generated or filled from entity/token data.
• You want a standardized, easily maintainable form experience.
• Avoid invoke_component when:
  • You only need to send a chat message (use an entity controller).
  • No user input is required.
  • Complex branching needs to occur before UI display.

Attribute Reference

The following keys are supported in the invokes attributes:

invoke_pages required

Defines the form pages. Form pages are the JSON array defined in the form builder documentation .

All text inside a page is processed with fill_text and entity substitution.

invoke_data_token required

Maps the identifiers of form fields into a token structure. This is the data token object defined in the form builder documentation .

Each mapping will appear in the final returned data_token.

add_keys optional

Allows injecting extra keys into the return object. This is a JSON object.

All _this references are auto-replaced.

Best Practices

• Keep pages concise; avoid overloading users with many fields on a single page.
• Use dynamic options instead of hardcoding enumerations.
• Provide clear instructions and user-friendly labels.
• Map only necessary fields via invoke_data_token.
• Do not deeply nest objects inside invoke_pages or add_keys.

Summary

The invoke_component standard provides a unified pattern for building interactive, declarative, dynamic forms inside MelodyArc. It handles:

• UI panel configuration

  • Universal form-builder rendering

    This ensures consistent behavior across all interactive steps and empowers authors to build rich interfaces without writing custom code.

Example

{
  "_id": "6931f1f694dee1d0b5fec6f9",
  "organization_id": "org_692e045887d13ed4774c0682",
  "name": "example_component",
  "partition": "example",
  "description": "",
  "tags": [],
  "inputs": {
    "task.operator": {
      "evaluate": "=sandbox"
    },
    "state": {
      "evaluate": "=initialized"
    }
  },
  "attributes": {
    "friendly_name": null,
    "description": null,
    "invoke_pages": [
      {
        "header": "User Feedback",
        "instructions": "Please answer the following question.",
        "fields": [
          {
            "id": "is_happy",
            "title": "Are you happy?",
            "component": "radio_group",
            "instructions": "Select 'Yes' if you're feeling happy, otherwise select 'No'.",
            "required": true,
            "default_value": "yes",
            "options": [
              {
                "value": "yes",
                "label": "Yes"
              },
              {
                "value": "no",
                "label": "No"
              }
            ]
          }
        ]
      }
    ],
    "invoke_data_token": {
      "is_happy": "is_happy"
    }
  },
  "code": "invoke_component",
  "allow_taskless": false,
  "is_quicklink": false,
  "allow_dynamic_code": false,
  "allow_dynamic_key": false,
  "version": "latest",
  "updated": {
    "request_id": "req-39x",
    "at": "2025-12-04T22:53:59.849Z",
    "by": "VV0Wu2BMe6sw2tPycObJFZKgOGdfekSEyAOZDL4Mq5w",
    "ip": "3.18.78.136",
    "user_agent": "node",
    "email": "[email protected]",
    "name": "VV0Wu2BMe6sw2tPycObJFZKgOGdfekSEyAOZDL4Mq5w"
  },
  "id": "6931f1f694dee1d0b5fec6f9",
  "search_resource_type": "invoke",
  "metadata": {
    "name": "test_component",
    "friendlyName": "",
    "partition": "test",
    "description": ""
  }
  }

Maintained by: MelodyArc Platform Engineering
Reference Implementation: invoke_component.js
Version: 1.0