Document the launch behavior for chats without a workspace

This commit is contained in:
Thorsten Sommer 2026-09-14 09:47:26 +02:00
parent 1fdf7a0c36
commit 1cb9e2fc20
Signed by untrusted user who does not match committer: tsommer
GPG Key ID: 371BBA77A02C0108
2 changed files with 30 additions and 4 deletions

View File

@ -82,7 +82,7 @@ Each assistant plugin lives in its own directory under the assistants plugin roo
## Structure
- `ASSISTANT` is the root table. Every assistant requires `Title` and `Description`.
- Form assistants additionally require `SystemPrompt`, `SubmitText`, `AllowProfiles`, and a nested `UI` definition.
- Direct chat launchers instead require `LaunchBehavior = "OPEN_WORKSPACE_CHAT_BY_NAME"` and `WorkspaceName`. 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.
- 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.
@ -108,8 +108,8 @@ ASSISTANT = {
}
```
## Direct Launch to Workspace Chat
Assistant plugins can optionally skip the normal assistant page and open a chat directly from the tile.
## Direct Launch into a Chat
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.
```lua
ASSISTANT = {
@ -130,8 +130,21 @@ ASSISTANT = {
}
```
A launcher without a workspace uses the other behavior and omits `WorkspaceName`. Every optional chat selection shown above works here as well:
```lua
ASSISTANT = {
["Title"] = "Quick Question",
["Description"] = "Open a disappearing chat with your research profile.",
["LaunchBehavior"] = "OPEN_TEMPORARY_CHAT",
["ProfileId"] = "22222222-2222-2222-2222-222222222222", -- optional
}
```
- `WorkspaceName` is resolved case-insensitively after trimming.
- If the workspace does not exist yet, AI Studio creates it automatically.
- 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.

View File

@ -444,7 +444,8 @@ ASSISTANT = {
},
}
-- direct chat launcher example; form-only fields and UI are not used in this mode:
-- direct chat launcher example opening the chat in a workspace; form-only fields and UI are not
-- used in this mode:
ASSISTANT = {
["Title"] = "<main title of chat launcher>",
["Description"] = "<description of the chat that will be opened>",
@ -464,3 +465,15 @@ ASSISTANT = {
"<optional tool ID>",
},
}
-- direct chat launcher example without a workspace: the tile opens a disappearing chat, which is
-- kept apart from the workspaces and cleaned up according to the workspace maintenance settings.
-- A WorkspaceName next to this launch behavior is an error instead of being ignored, so a leftover
-- name cannot silently change the kind of chat the tile opens. Every optional field of the example
-- above works here as well:
ASSISTANT = {
["Title"] = "<main title of chat launcher>",
["Description"] = "<description of the chat that will be opened>",
["LaunchBehavior"] = "OPEN_TEMPORARY_CHAT",
["ProfileId"] = "<optional profile GUID; use the empty GUID for no profile>",
}