This folder keeps the Lua manifest (`plugin.lua`) that defines a custom assistant. Treat it as the single source of truth for how AI Studio renders your assistant UI and builds the submitted prompt.
- [Example: Use Logging in lua functions](#example-use-logging-in-lua-functions)
- [General Tips](#general-tips)
- [Useful Resources](#useful-resources)
## How to Use This Documentation
Use this README in layers. The early sections are a quick reference for the overall assistant manifest shape and the available component types, while the later `... reference` sections are the full detail for each component and advanced behavior.
When you build a plugin, start with the directory layout and the `Structure` section, then jump to the component references you actually use. The resource links at the end are the primary sources for Lua and MudBlazor behavior, and the `General Tips` section collects the practical rules and gotchas that matter most while authoring `plugin.lua`.
If you want to see a complete assistant plugin, start with `examples/translation/plugin.lua` in this folder. It mirrors the built-in translation assistant in a reduced form.
This example shows:
-`WEB_CONTENT_READER`
-`FILE_CONTENT_READER`
- a plain `TEXT_AREA`
- a `DROPDOWN` for the target language
-`PROVIDER_SELECTION`
-`ASSISTANT.BuildPrompt(input)` for prompt assembly
Treat the example as the recommended minimum viable pattern for assistant plugins, not as a feature-by-feature clone of `AssistantTranslation.razor`.
Each assistant plugin lives in its own directory under the assistants plugin root. In practice, you usually keep the manifest in `plugin.lua`, optional icon rendering in `icon.lua`, and any bundled media in `assets/`.
- Direct chat launchers instead require a `LaunchBehavior`: either `"OPEN_WORKSPACE_CHAT_BY_NAME"` together with a `WorkspaceName`, or `"OPEN_TEMPORARY_CHAT"` for a chat that belongs to no workspace. AI Studio stops reading the form-only fields as soon as a launch behavior is active, so older launchers that still carry them keep working.
-`ToolIds` is optional for both kinds and names the tools the assistant runs with, such as `{"web_search"}`. When present, it must list at least one unique, non-empty tool ID; omit the field instead of writing an empty list. For a form assistant, naming tools takes the choice away from users: the tool selection disappears, and the assistant always runs with exactly these tools. For a launcher, the tools are merely preselected and users may change them once the chat is open. Naming a tool is a wish, not a permission: a tool switched off in the settings stays off, one whose settings are incomplete cannot run, and every tool still has to meet the confidence requirements of the provider in use. A tool ID unknown to the installation is skipped.
-`DEPLOYED_USING_CONFIG_SERVER` identifies who manages the assistant plugin. Set it to `false` for locally managed plugins. A missing field is also treated as local for compatibility with existing plugins. Enterprise-distributed plugins must set it to `true` and cannot be revised with AI in AI Studio.
-`AI_STUDIO_ASSISTANT_BUILDER = {Generated = true, SchemaVersion = 1}` is reserved for plugins generated by the AI Studio Assistant Builder. It enables Builder-specific actions such as safe deletion and must not be added to manually authored or enterprise-distributed assistants. Newly generated Builder assistants always set `DEPLOYED_USING_CONFIG_SERVER = false` explicitly.
Assistant plugins can optionally skip the normal assistant page and open a chat directly from the tile. The chat either lives in a workspace or in none at all; everything else about the two behaviors is the same.
- Use `OPEN_TEMPORARY_CHAT` when the chat needs no home of its own, for instance, a quick start that only preselects a profile and a few data sources. AI Studio then opens the same disappearing chat the chat page offers: it is kept apart from the workspaces and cleaned up according to the workspace maintenance settings of the installation.
-`OPEN_TEMPORARY_CHAT` must not carry a `WorkspaceName`. A name next to it stops the plugin from loading rather than being ignored, so a leftover or mistyped name cannot silently turn a workspace launcher into a disappearing one.
- Omitted optional IDs use the chat defaults active when the tile is opened. An explicit empty GUID selects no profile or no chat template; an empty provider or data-source GUID is invalid.
-`ProviderId` overrides both the chat-specific and app-wide default provider. It must name a provider that is permitted for chats at the required confidence level.
- Explicit data sources are enabled and manually preselected, automatic source selection is disabled, and the normal automatic-validation setting is retained. Every referenced source must currently be available and permitted for the effective provider.
- Invalid or unavailable references stop the launch with an error before a workspace or chat is created.
- A selected chat template supplies the chat system prompt, profile allowance, predefined user prompt, attachments, and cloned example conversation. A launcher `SystemPrompt`, if retained in an older plugin, is ignored, so there is never a second competing system prompt.
- When the selected chat template does not allow profiles, the template wins: the launcher `ProfileId` is dropped and the chat starts without a profile. This matches the disabled profile selection such a template produces in the chat.
- The predefined user prompt and the attachments of the selected chat template are placed into the chat input, unless the user already has an unsent draft there.
### Editing a launcher in AI Studio
Users can change a launcher without touching Lua and without asking a model: the tile on the assistants page and the plugins page both offer a settings dialog for the name, the title, the description, and every chat selection above. Changing a launcher is picking from drop-downs, so there is nothing to prompt about, and locally managed launchers therefore get this dialog instead of the AI revision.
Saving rewrites the whole `plugin.lua` in a canonical shape. Comments, formatting, and anything beyond the metadata and the `ASSISTANT` table would be lost that way, so AI Studio offers the dialog only for launchers that are:
- locally managed, meaning not internal and not deployed by a configuration server,
- made of a single `plugin.lua` without companion Lua files, and
- free of `ICON_SVG` and any `require(...)`.
Launchers with an own icon or extra Lua code keep the plugin code editor and the AI revision, so nothing an author wrote gets dropped. `AI_STUDIO_ASSISTANT_BUILDER` is carried over unchanged: the dialog never adds it to a manually authored plugin.
#### Supported types (matching the Blazor UI components):
-`TEXT_AREA`: user input field based on `MudTextField`; requires `Name`, `Label`, and may include `HelperText`, `HelperTextOnFocus`, `Adornment`, `AdornmentIcon`, `AdornmentText`, `AdornmentColor`, `Counter`, `MaxLength`, `IsImmediate`, `UserPrompt`, `PrefillText`, `IsSingleLine`, `ReadOnly`, `Class`, `Style`.
-`DROPDOWN`: selects between variants; `Props` must include `Name`, `Label`, `Default`, `Items`, and optionally `ValueType` plus `UserPrompt`.
-`BUTTON`: invokes a Lua callback; `Props` must include `Name`, `Text`, `Action`, and may include `IsIconButton`, `Variant`, `Color`, `IsFullWidth`, `Size`, `StartIcon`, `EndIcon`, `IconColor`, `IconSize`, `Class`, `Style`. Use this for stateless actions, including icon-only action buttons.
-`BUTTON_GROUP`: groups multiple `BUTTON` children in a `MudButtonGroup`;`Props` must include `Name`, `Children` must contain only `BUTTON` components and `Props` may include `Variant`, `Color`, `Size`, `OverrideStyles`, `Vertical`, `DropShadow`, `Class`, `Style`.
-`LAYOUT_GRID`: renders a `MudGrid`; `Children` must contain only `LAYOUT_ITEM` components and `Props` may include `Justify`, `Spacing`, `Class`, `Style`.
-`LAYOUT_ITEM`: renders a `MudItem`; use it inside `LAYOUT_GRID` and configure breakpoints with `Xs`, `Sm`, `Md`, `Lg`, `Xl`, `Xxl`, plus optional `Class`, `Style`.
-`LAYOUT_PAPER`: renders a `MudPaper`; may include `Elevation`, `Height`, `MaxHeight`, `MinHeight`, `Width`, `MaxWidth`, `MinWidth`, `IsOutlined`, `IsSquare`, `Class`, `Style`.
-`LAYOUT_STACK`: renders a `MudStack`; may include `IsRow`, `IsReverse`, `Breakpoint`, `Align`, `Justify`, `Stretch`, `Wrap`, `Spacing`, `Class`, `Style`.
-`LAYOUT_ACCORDION`: renders a `MudExpansionPanels`; may include `AllowMultiSelection`, `IsDense`, `HasOutline`, `IsSquare`, `Elevation`, `HasSectionPaddings`, `Class`, `Style`.
-`LAYOUT_ACCORDION_SECTION`: renders a `MudExpansionPanel`; requires `Name`, `HeaderText`, and may include `IsDisabled`, `IsExpanded`, `IsDense`, `HasInnerPadding`, `HideIcon`, `HeaderIcon`, `HeaderColor`, `HeaderTypo`, `HeaderAlign`, `MaxHeight`, `ExpandIcon`, `Class`, `Style`.
-`SWITCH`: boolean option; requires `Name`, `Label`, `Value`, and may include `OnChanged`, `Disabled`, `UserPrompt`, `LabelOn`, `LabelOff`, `LabelPlacement`, `Icon`, `IconColor`, `CheckedColor`, `UncheckedColor`, `Class`, `Style`.
-`COLOR_PICKER`: color input based on `MudColorPicker`; requires `Name`, `Label`, and may include `Placeholder`, `ShowAlpha`, `ShowToolbar`, `ShowModeSwitch`, `PickerVariant`, `UserPrompt`, `Class`, `Style`.
-`DATE_PICKER`: date input based on `MudDatePicker`; requires `Name`, `Label`, and may include `Value`, `Color`, `Placeholder`, `HelperText`, `DateFormat`, `PickerVariant`, `UserPrompt`, `Class`, `Style`.
-`DATE_RANGE_PICKER`: date range input based on `MudDateRangePicker`; requires `Name`, `Label`, and may include `Value`, `Color`, `PlaceholderStart`, `PlaceholderEnd`, `HelperText`, `DateFormat`, `PickerVariant`, `UserPrompt`, `Class`, `Style`.
-`TIME_PICKER`: time input based on `MudTimePicker`; requires `Name`, `Label`, and may include `Value`, `Color`, `Placeholder`, `HelperText`, `TimeFormat`, `AmPm`, `PickerVariant`, `UserPrompt`, `Class`, `Style`.
-`PROVIDER_SELECTION` / `PROFILE_SELECTION`: hooks into the shared provider/profile selectors.
-`WEB_CONTENT_READER`: renders `ReadWebContent`; include `Name`, `UserPrompt`, `Preselect`, `PreselectContentCleanerAgent`.
-`FILE_CONTENT_READER`: renders `ReadFileContent`; use it when exactly one expected file should be read and inserted into the prompt; include `Name`, and optionally `UserPrompt`, `ShowAttachedDocumentState`, `Class`, `Style`. `ShowAttachedDocumentState` defaults to `true`; set it to `false` only when the loaded-document indicator should be hidden.
-`FILE_ATTACHMENTS`: renders `AttachDocuments`; use it when the assistant should accept multiple documents/images or an unpredictable number of files as context; include `Name`, and may include `Heading`, `UserPrompt`, `CatchAllDocuments`, `UseSmallForm`, `Class`, `Style`. Keep `UseSmallForm = false` by default unless compact layout is explicitly required.
- **Drop zones and `CatchAllDocuments`**: `FILE_CONTENT_READER` and `FILE_ATTACHMENTS` both accept dropped files. `CatchAllDocuments` makes one of them the default target of the whole assistant, so that a file dropped anywhere in it still arrives there. That only makes sense while the assistant has exactly **one** drop zone. With several, set `CatchAllDocuments = false`: it defaults to `true` when the prop is absent, and users then have to aim at the zone they mean instead of watching their file land in a neighbouring one. AI Studio enforces the rule at runtime, so a `true` value is ignored anyway as soon as a second drop zone exists.
-`IMAGE`: embeds a static illustration; `Props` must include `Src` plus optionally `Alt` and `Caption`. `Src` can be an HTTP/HTTPS URL, a `data:` URI, or a plugin-relative path (`plugin://assets/your-image.png`). The runtime will convert plugin-relative paths into `data:` URLs (base64).
-`HEADING`, `TEXT`, `LIST`: descriptive helpers.
Images referenced via the `plugin://` scheme must exist in the plugin directory (e.g., `assets/example.png`). Drop the file there and point `Src` at it. The component will read the file at runtime, encode it as Base64, and render it inside the assistant UI.
More information on rendered components can be found [here](https://www.mudblazor.com/docs/overview).
## Component References
### `TEXT_AREA` reference
- Use `Type = "TEXT_AREA"` to render a MudBlazor text input or textarea.
- Required props:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Label`: visible field label.
- Optional props:
-`HelperText`: helper text rendered below the input.
-`HelperTextOnFocus`: defaults to `false`; show helper text only while the field is focused.
-`Adornment`: one of `Start`, `End`, `None`; invalid or omitted values fall back to `Start`.
-`AdornmentIcon`: MudBlazor icon identifier string for the adornment.
-`AdornmentText`: plain adornment text. Do not set this together with `AdornmentIcon`.
-`AdornmentColor`: one of the MudBlazor `Color` enum names such as `Primary`, `Secondary`, `Warning`; invalid or omitted values fall back to `Default`.
-`Counter`: nullable integer. Omit it to hide the counter entirely. Set `0` to show only the current character count. Set `1` or higher to show `current/max`.
-`MaxLength`: maximum number of characters allowed; defaults to `524288`.
-`IsImmediate`: defaults to `false`; updates the bound value on each input event instead of on blur/change.
-`UserPrompt`: prompt context text for this field.
-`PrefillText`: initial input value.
-`IsSingleLine`: defaults to `false`; render as a one-line input instead of a textarea.
-`ReadOnly`: defaults to `false`; disables editing.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
["UserPrompt"]="Use this budget information in your answer.",
["PrefillText"]="",
["IsSingleLine"]=true
}
}
```
---
### `DROPDOWN` reference
- Use `Type = "DROPDOWN"` to render a MudBlazor select field.
- Required props:
-`Name`: unique state key used in prompt assembly, button actions, and `BuildPrompt(input)`.
-`Label`: visible field label.
-`Default`: dropdown item table with the shape `{ ["Value"] = "<internal value>", ["Display"] = "<visible label>" }`.
-`Items`: array of dropdown item tables with the same shape as `Default`.
- Optional props:
-`UserPrompt`: prompt context text for this field.
-`ValueType`: one of `string`, `int`, `double`, `bool`; currently the dropdown values exposed to prompt building and button actions are handled as the configured item `Value`s, with typical usage being `string`.
-`IsMultiselect`: defaults to `false`; when `true`, the component allows selecting multiple items.
-`HasSelectAll`: defaults to `false`; enables MudBlazor's select-all behavior for multiselect dropdowns.
-`SelectAllText`: custom label for the select-all action in multiselect mode.
-`HelperText`: helper text rendered below the dropdown.
-`OpenIcon`: MudBlazor icon identifier used while the dropdown is closed.
-`CloseIcon`: MudBlazor icon identifier used while the dropdown is open.
-`IconColor`: one of the MudBlazor `Color` enum names such as `Primary`, `Secondary`, `Warning`; invalid or omitted values fall back to `Default`.
-`IconPositon`: one of `Start` or `End`; controls where the icon adornment is rendered.
-`Variant`: one of the MudBlazor `Variant` enum names such as `Text`, `Filled`, `Outlined`; invalid or omitted values fall back to `Outlined`.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
- Dropdown item shape:
-`Value`: the internal raw value stored in component state and passed to prompt building.
-`Display`: the visible label shown to the user in the menu and selection text.
- Behavior notes:
- For single-select dropdowns, `input.<Name>.Value` is a single raw value such as `germany`.
- For multiselect dropdowns, `input.<Name>.Value` is an array-like Lua table of raw values.
- Use `Type = "BUTTON"` to render a clickable action button.
-`BUTTON` is the only action-button component in the assistant plugin API. Keep plugin authoring simple by treating it as one concept with two visual modes:
- default button mode: text button, optionally with start/end icons
- icon-button mode: set `IsIconButton = true` to render the action as an icon-only button
- Do not model persistent on/off state with `BUTTON`. For boolean toggles, use `SWITCH`. The plugin API intentionally does not expose a separate `TOGGLE_BUTTON` component.
- Required props:
-`Name`: unique identifier used to track execution state and logging.
-`Text`: button label used for standard buttons. Keep providing it for icon buttons too so the manifest stays self-describing.
-`Action`: Lua function called on button click.
- Optional props:
-`IsIconButton`: defaults to `false`; when `true`, renders the action as a `MudIconButton` using `StartIcon` as the icon glyph.
-`Variant`: one of the MudBlazor `Variant` enum names such as `Filled`, `Outlined`, `Text`; omitted values fall back to `Filled`.
-`Color`: one of the MudBlazor `Color` enum names such as `Default`, `Primary`, `Secondary`, `Info`; omitted values fall back to `Default`.
-`IsFullWidth`: defaults to `false`; when `true`, the button expands to the available width.
-`Size`: one of the MudBlazor `Size` enum names such as `Small`, `Medium`, `Large`; omitted values fall back to `Medium`.
-`StartIcon`: MudBlazor icon identifier string rendered before the button text, or used as the icon itself when `IsIconButton = true`.
-`EndIcon`: MudBlazor icon identifier string rendered after the button text.
-`IconColor`: one of the MudBlazor `Color` enum names for text-button icons; omitted values fall back to `Inherit`.
-`IconSize`: one of the MudBlazor `Size` enum names; omitted values fall back to `Medium`.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
#### `Action(input)` interface
- The function receives the same `input` structure as `ASSISTANT.BuildPrompt(input)`.
- Return `nil` for no state update.
- Each named component is available as `input.<Name>` and exposes:
-`Type`: component type such as `TEXT_AREA` or `SWITCH`
-`Value`: current component value
-`Props`: readable component props
- To update component state, return a table with a `state` table.
-`state` keys must reference existing component `Name` values.
- Use `Type = "BUTTON_GROUP"` to render multiple `BUTTON` children as a single MudBlazor button group.
- Required structure:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Children`: array of `BUTTON` component tables. Other child component types are ignored.
- Optional props:
-`Variant`: one of the MudBlazor `Variant` enum names such as `Filled`, `Outlined`, `Text`; omitted values fall back to `Filled`.
-`Color`: one of the MudBlazor `Color` enum names such as `Default`, `Primary`, `Secondary`, `Info`; omitted values fall back to `Default`.
-`Size`: one of the MudBlazor `Size` enum names such as `Small`, `Medium`, `Large`; omitted values fall back to `Medium`.
-`OverrideStyles`: defaults to `false`; enables MudBlazor button-group style overrides.
-`Vertical`: defaults to `false`; when `true`, buttons are rendered vertically instead of horizontally.
-`DropShadow`: defaults to `true`; controls the group shadow.
-`Class`, `Style`: forwarded to the rendered `MudButtonGroup` for layout/styling.
- Child buttons use the existing `BUTTON` props and behavior, including Lua `Action(input)`. That includes `IsIconButton = true` when you want an icon-only action inside the group.
- Use `Type = "SWITCH"` to render a boolean toggle.
- Required props:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Value`: initial boolean state (`true` or `false`).
- Optional props:
-`Label`: If set, renders the switch inside an outlines Box, otherwise renders it raw. Visible label for the switch field.
-`OnChanged`: Lua callback invoked after the switch value changes. It receives the same `input` table as `BUTTON.Action(input)` and may return `{ state = { ... } }` to update component state. The new switch value is already reflected in `input.<Name>.Value`.
-`Disabled`: defaults to `false`; disables user interaction while still allowing the value to be included in prompt assembly.
-`UserPrompt`: prompt context text for this field.
-`LabelOn`: text shown when the switch value is `true`.
-`LabelOff`: text shown when the switch value is `false`.
-`LabelPlacement`: one of `Bottom`, `End`, `Left`, `Right`, `Start`, `Top`; omitted values follow the renderer default.
-`Icon`: MudBlazor icon identifier string displayed inside the switch thumb.
-`IconColor`: one of the MudBlazor `Color` enum names such as `Primary`, `Secondary`, `Warning`; omitted values default to `Inherit`.
-`CheckedColor`: color used when the switch state is `true`; omitted values default to `Inherit`.
-`UncheckedColor`: color used when the switch state is `false`; omitted values default to `Inherit`.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
["UserPrompt"]="Decide whether the final answer should include a short summary.",
["LabelOn"]="Summary enabled",
["LabelOff"]="Summary disabled",
["LabelPlacement"]="End",
["Icon"]="Icons.Material.Filled.Summarize",
["IconColor"]="Primary",
["CheckedColor"]="Success",
["UncheckedColor"]="Default",
["Class"]="mb-6",
}
}
```
---
### `COLOR_PICKER` reference
- Use `Type = "COLOR_PICKER"` to render a MudBlazor color picker.
- Required props:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Label`: visible field label.
- Optional props:
-`Placeholder`: default color hex string (e.g. `#FF10FF`) or initial hint text.
-`ShowAlpha`: defaults to `true`; enables alpha channel editing.
-`ShowToolbar`: defaults to `true`; shows picker/grid/palette toolbar.
-`ShowModeSwitch`: defaults to `true`; allows switching between HEX/RGB(A)/HSL modes.
-`PickerVariant`: one of `DIALOG`, `INLINE`, `STATIC`; invalid or omitted values fall back to `STATIC`.
-`UserPrompt`: prompt context text for the selected color.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
#### Example Colorpicker component
```lua
{
["Type"]="COLOR_PICKER",
["Props"]={
["Name"]="accentColor",
["Label"]="Accent color",
["Placeholder"]="#FFAA00",
["ShowAlpha"]=false,
["ShowToolbar"]=true,
["ShowModeSwitch"]=true,
["PickerVariant"]="STATIC",
["UserPrompt"]="Use this as the accent color for the generated design."
}
}
```
---
### `DATE_PICKER` reference
- Use `Type = "DATE_PICKER"` to render a MudBlazor date picker.
- Required props:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Label`: visible field label.
- Optional props:
-`Value`: initial date string. Use the same format as `DateFormat`; default recommendation is `yyyy-MM-dd`.
-`Placeholder`: hint text shown before a date is selected.
-`Color`: one of the MudBlazor `Color` enum names such as `Primary`, `Secondary`, `Warning`; omitted values default to `Primary`.
-`HelperText`: helper text rendered below the picker.
-`DateFormat`: output and parsing format; defaults to `yyyy-MM-dd`.
-`PickerVariant`: one of `Dialog`, `Inline`, `Static`; invalid or omitted values fall back to `Dialog`.
-`UserPrompt`: prompt context text for the selected date.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
#### Example DatePicker component
```lua
{
["Type"]="DATE_PICKER",
["Props"]={
["Name"]="deadline",
["Label"]="Deadline",
["Value"]="2026-03-31",
["Placeholder"]="YYYY-MM-DD",
["Color"]="Warning",
["HelperText"]="Pick the target completion date.",
["DateFormat"]="yyyy-MM-dd",
["PickerVariant"]="Dialog",
["UserPrompt"]="Use this as the relevant deadline."
}
}
```
---
### `DATE_RANGE_PICKER` reference
- Use `Type = "DATE_RANGE_PICKER"` to render a MudBlazor date range picker.
- Required props:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Label`: visible field label.
- Optional props:
-`Value`: initial range string using `<start> - <end>`, for example `2026-03-01 - 2026-03-31`.
-`Color`: one of the MudBlazor `Color` enum names such as `Primary`, `Secondary`, `Warning`; omitted values default to `Primary`.
-`PlaceholderStart`: hint text for the start date input.
-`PlaceholderEnd`: hint text for the end date input.
-`HelperText`: helper text rendered below the picker.
-`DateFormat`: output and parsing format for both dates; defaults to `yyyy-MM-dd`.
-`PickerVariant`: one of `Dialog`, `Inline`, `Static`; invalid or omitted values fall back to `Dialog`.
-`UserPrompt`: prompt context text for the selected date range.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
#### Example DateRangePicker component
```lua
{
["Type"]="DATE_RANGE_PICKER",
["Props"]={
["Name"]="travelWindow",
["Label"]="Travel window",
["Value"]="2026-06-01 - 2026-06-07",
["Color"]="Secondary",
["PlaceholderStart"]="Start date",
["PlaceholderEnd"]="End date",
["HelperText"]="Select the full period.",
["DateFormat"]="yyyy-MM-dd",
["PickerVariant"]="Dialog",
["UserPrompt"]="Use this as the allowed date range."
}
}
```
---
### `TIME_PICKER` reference
- Use `Type = "TIME_PICKER"` to render a MudBlazor time picker.
- Required props:
-`Name`: unique state key used in prompt assembly and `BuildPrompt(input)`.
-`Label`: visible field label.
- Optional props:
-`Value`: initial time string. Use the same format as `TimeFormat`; default recommendations are `HH:mm` or `hh:mm tt`.
-`Placeholder`: hint text shown before a time is selected.
-`Color`: one of the MudBlazor `Color` enum names such as `Primary`, `Secondary`, `Warning`; omitted values default to `Primary`.
-`HelperText`: helper text rendered below the picker.
-`TimeFormat`: output and parsing format; defaults to `HH:mm`, or `hh:mm tt` when `AmPm = true`.
-`AmPm`: defaults to `false`; toggles 12-hour mode.
-`PickerVariant`: one of `Dialog`, `Inline`, `Static`; invalid or omitted values fall back to `Dialog`.
-`UserPrompt`: prompt context text for the selected time.
-`Class`, `Style`: forwarded to the rendered component for layout/styling.
#### Example TimePicker component
```lua
{
["Type"]="TIME_PICKER",
["Props"]={
["Name"]="meetingTime",
["Label"]="Meeting time",
["Value"]="14:30",
["Placeholder"]="HH:mm",
["Color"]="Error",
["HelperText"]="Pick the preferred meeting time.",
["TimeFormat"]="HH:mm",
["AmPm"]=false,
["PickerVariant"]="Dialog",
["UserPrompt"]="Use this as the preferred time."
}
}
```
## Prompt Assembly - UserPrompt Property
Each component exposes a `UserPrompt` string. When the assistant runs, `AssistantDynamic` recursively iterates over the component tree and, for each component that has a prompt, emits:
For switches the “value” is the boolean `true/false`; for `WEB_CONTENT_READER` and `FILE_CONTENT_READER` it is the fetched or selected content; for `FILE_ATTACHMENTS` it is the selected file paths and the files are also attached to the chat request; for color pickers it is the selected color text (for example `#FFAA00` or `rgba(...)`, depending on the picker mode); for date and time pickers it is the formatted date, date range, or time string. Always provide a meaningful `UserPrompt` so the final concatenated prompt remains coherent from the LLM’s perspective.
If you want full control over prompt composition, define `ASSISTANT.BuildPrompt` as a Lua function. When present, AI Studio calls it and uses its return value as the final user prompt. The default prompt assembly is skipped.
---
### Interface
-`ASSISTANT.BuildPrompt(LuaTable input) => string` must return a **string**, the complete User Prompt.
- If the function is missing, returns `nil`, or returns a non-string, AI Studio falls back to the default prompt assembly.
- Errors in the function are caught and logged, then fall back to the default prompt assembly.
---
### `input` table shape
The function receives a single `input` Lua table with:
-`input.<Name>`: one entry per named component
-`Type` (string, e.g. `TEXT_AREA`, `DROPDOWN`, `SWITCH`, `COLOR_PICKER`, `DATE_PICKER`, `DATE_RANGE_PICKER`, `TIME_PICKER`)
-`Value` (current component value)
-`Props` (readable component props)
-`input.profile`: selected profile data
-`Name`, `NeedToKnow`, `Actions`, `Num`
- When no profile is selected, values match the built-in "Use no profile" entry
-- <Name> is the value you set in the components name property
```
---
### Using component metadata inside BuildPrompt
`input.<Name>.Type` and `input.<Name>.Props` are useful when you want to build prompts from a few specific fields without depending on the default `UserPrompt` assembly.
Profiles are optional user context (e.g., "NeedToKnow" and "Actions"). You can inject this directly into the user prompt if you want the LLM to always see it.
#### Example: Add user profile context to the prompt
-`Timestamp()` returns a UTC timestamp in ISO-8601 format (`O` / round-trip), e.g. `2026-03-02T21:15:30.1234567Z`.
#### Example: Use the datetime functions in lua
```lua
localdt=DateTime("yyyy-MM-dd HH:mm:ss")
LogInfo(dt.formatted)
LogInfo(Timestamp())
LogInfo(dt.day.."."..dt.month.."."..dt.year)
```
## General Tips
1. Give every component a _**unique**_`Name`— it’s used to track state and treated like an Id.
2. Keep in mind that components and their properties are _**case-sensitive**_ (e.g. if you write `["Type"] = "heading"` instead of `["Type"] = "HEADING"` the component will not be registered). Always copy-paste the component from the `plugin.lua` manifest to avoid this.
3. When you expect default content (e.g., a textarea with instructions), keep `UserPrompt` but also set `PrefillText` so the user starts with a hint.
4. If you need extra explanatory text (before or after the interactive controls), use `TEXT` or `HEADING` components.
5. Keep `Preselect`/`PreselectContentCleanerAgent` flags in `WEB_CONTENT_READER` to simplify the initial UI for the user.
