Action Function

Action Function

Action Functions let you add custom buttons to the message toolbar so end users can trigger interactive workflows directly from a chat message. This supports use cases such as requiring user confirmation before running a task, generating visualizations from structured data, downloading artifacts (for example, an audio snippet of a conversation), and other guided interactions.

A scaffold for Action code is commonly available in community examples. Actions are designed to be modular, fast to execute, and easy to attach to the message UI.

What is an Action?

An Action is a UI button rendered under individual messages (the small buttons shown directly beneath a chat message). When clicked, it triggers an Action Function that can:

• Read the current message context and metadata
• Ask the user for additional input or confirmation
• Execute logic and return results to the UI
• Optionally emit UI events for richer experiences (forms, progress, visualization, downloads)

Actions are not models. They are user-initiated interactions that run on-demand.

Core component: the Action Function

Actions have a single main component: an asynchronous action(...) function. This function receives the request payload and optional runtime helpers that can be used to interact with the UI.

Common signature

from typing import Optional

async def action(
    self,
    body: dict,
    __user__=None,
    __event_emitter__=None,
    __event_call__=None,
) -> Optional[dict]:
    # Your logic here
    return None

Parameters

• body: dict
  • The action payload, including message context and any data the UI provides.
• __user__
  • User metadata (when available), useful for authorization, auditing, and personalization.
• __event_emitter__
  • A callback used to emit UI events (for example, progress updates, notifications, or rendering hints).
• __event_call__
  • A request/response style helper for interactive UI prompts (for example, asking the user for a value in a modal).

Note:

• Exact payload shape and supported events depend on your IntraLLM AI/IntraLLM AI runtime version and configuration.

Example: prompt the user for input

The example below shows how an Action can request a short user input using __event_call__. This is useful for “append note”, “rename”, “confirm”, or other guarded workflows.

from typing import Optional

class Action:
    async def action(
        self,
        body: dict,
        __user__=None,
        __event_emitter__=None,
        __event_call__=None,
    ) -> Optional[dict]:
        print(f"action:{__name__}")

        response = await __event_call__(
            {
                "type": "input",
                "data": {
                    "title": "Write a message",
                    "message": "Enter a message to append.",
                    "placeholder": "Enter your message",
                },
            }
        )

        print(response)

        # Example: return structured output for downstream handling or UI rendering
        return {
            "type": "result",
            "data": {
                "user_input": response,
            },
        }

Using Actions for permission and confirmation

Actions are well-suited for “ask before doing” flows. A typical pattern is:

• User clicks the button
• Action asks for confirmation (or additional parameters)
• Only then performs the operation

This reduces accidental execution and makes high-impact actions safer and more transparent.

Visualization and structured outputs

Actions can also be used to generate a visualization from structured data. The general pattern is:

• Parse or compute structured data (e.g., time series, categories, metrics)
• Return an object describing the result
• Optionally use event emission to render or present it in the UI

Implementation details vary by runtime; prefer using community scaffolds and existing visualization examples as references for supported event types and payload schemas.

Best practices

• Validate inputs from body and user responses from __event_call__ before executing any operation.
• Use user confirmation for destructive or irreversible operations.
• Avoid exposing sensitive data in logs; redact secrets before printing.
• Handle missing helpers gracefully (e.g., if __event_call__ is not available, provide a fallback).
• Keep Actions small and focused; use Pipes for model-like workflows and Filters for transformation hooks.

Notes

• Community scaffolds are the fastest way to start: they typically include supported event payload formats and UI behaviors for your runtime version.
• Verify compatibility with your current IntraLLM AI/IntraLLM AI release, as supported event types and signatures may change over time.