Configure scoped AI chat

A chat surface reuses the existing TWL Tool AI chat page and constrains it to one installed workflow. Your app supplies the preset; it does not implement another chat backend or frontend.

{
  key: 'write',
  label: 'Write',
  type: 'chat',
  preset: {
    workflow: ref('workflowDefinitions', 'writePost'),
    space: ref('spaces', 'root'),
    outputDocumentFolder: ref('documentFolders', 'drafts'),
    allowedTools: ['workflow.launch'],
    initialMessage: 'What would you like to write about?',
    instructions: 'Turn the user request into one polished social post.',
    showModelSelector: false,
    showBrowserControls: false,
    showAttachments: true,
    contextSources: [
      {
        key: 'voice-and-styles',
        label: 'Voice & Styles',
        type: 'dataWorkspaceRows',
        table: ref('dataWorkspaceTables', 'styles'),
        workflowContextKey: 'selectedStyleContext',
        labelField: 'name',
        descriptionFields: ['description', 'tone', 'structure', 'example'],
        filter: { field: 'active', equals: true },
      },
    ],
    expectedOutput: 'document',
  },
}

Server-resolved scope

The browser sends the installed app key and surface key. The server resolves the workflow definition, Space, and output folder from the installed manifest. It also pins app attribution to the workflow run.

This prevents page code from swapping in an undeclared workflow ID or impersonating another installation.

Allowed tools

The current scoped surface accepts only workflow.launch. If you include it, the app must request workflows.execute. A chat surface also requires ai-chat.use.

When expectedOutput is present, its value is document. Bind outputDocumentFolder so generated work appears in the app's document surface and scheduler.

App-scoped history

The chat history control is automatically scoped to the installed app key and chat surface key. Users see previous conversations from that app surface only; general AI chats and conversations from other apps are excluded. No separate history implementation is required.

Context sources and mentions

Use preset.contextSources to replace the generic @ resource menu with rows from an app-owned Data Workspace table. The current source type is dataWorkspaceRows.

The app must request data-workspace.read in addition to the permissions required by the chat surface and workflow.

Field	Required	Purpose
key	yes	Stable source key within the chat preset
label	yes	Category shown in the @ menu
type	yes	Must be dataWorkspaceRows
table	yes	Reference to an installed dataWorkspaceTables resource
workflowContextKey	yes	Workflow context field that receives the selected row rules
labelField	yes	Row field used for the mention label
descriptionFields	no	Ordered fields included as context and picker details
filter	no	Simple equality filter, such as active rows only

When a user selects a row, chat sends a data_workspace_row reference. The server verifies that the row belongs to the declared installed table and current organization, reapplies the configured filter, and then pins the formatted row fields into the workflow launch context. Client-supplied table IDs or style text are not trusted.

For a writing workflow, bind the configured context key to the existing content-generation node's sourceContent parameter:

{
  identifier: 'content.generate-written-content@1',
  parameters: {
    prompt: '{{ context.prompt }}',
    sourceContent: '{{ context.selectedStyleContext }}',
  },
}

The selected rules then appear as SOURCE_CONTEXT in the generation prompt while document-based templates and voice profiles continue to use their existing parameters. The host also pins context.prompt to the current chat message, so a workflow cannot accidentally reuse an earlier request.

:::note Updating an installed app Adding or changing contextSources changes the installed app contract. Increment the app version, rebuild and certify the Tool, and upgrade existing installations. Until an older installation is upgraded, its scoped picker intentionally does not fall back to the user's global resource catalog. :::