Skip to main content

Deploying the Builder UIs

Neither builder is required, but both are no-code tools that put an otherwise code-only workflow in front of the people who own the work:

  • the LLM Prompt Builder lets prompt engineers test new prompts across LLMs, compare the results, version their experiments, and turn the best prompt into a model for further consumption in the platform (for example in SAS Intelligent Decisioning);
  • the RAG Builder lets a data or decision engineer configure a document pipeline — sources, chunking, embedding model, vector store — save it as a governed RAG setup, and generate the ingestion job and SAS Studio flow that run it.

The steps below are written for the Prompt Builder. The RAG Builder is deployed the same way — the same single-file build, the same Job Execution definition, the same Data-Driven Content object — with its own build target (npm run build:rag) and its own set of options; see RAG Ingestion and Retrieval for what those options mean.

Standalone build

Both builders are shipped as standalone applications in the LLM-Prompt-Builder directory of this repository. Neither has any dependency on the SAS Portal Framework for SAS Viya — each is a single self-contained HTML file that you embed directly in a SAS Visual Analytics report through SAS Job Execution.

Shortcut: import the transfer package (optional)​

Rather than building the app and wiring it up by hand (steps 1–2), you can import the SAS-Agentic-AI-Accelerator-Prompt-Builder.json transfer package. It bundles the whole UI ready to run — the Prompt Builder folder, the SAS Job Execution definition that serves the single-file app, and the Visual Analytics report that hosts the object. Import it and you can skip straight to step 3.

The package ships the report's Prompt Builder object pointing at a placeholder host, https://your-sas-viya-host — point it at your own environment before or after import.

Option A — mdb builders-import (recommended)​

With mdb installed and your .env filled in (Setup SAS Model Manager), one command imports both Builder packages, loads the release table they bind to, points their Data-Driven Content URLs and host defaults at your server, and configures the objects - from a file saved with mdb options-save when you pass one, else with the repository, projects and SCR endpoint it discovers:

mdb builders-import --dry-run                     # what would happen
mdb builders-import                               # first install
mdb builders-import --options builder-options.json   # upgrade: keep this site's options

Name package files to import only one (mdb builders-import SAS-Viya-Integrations/SAS-Agentic-AI-Accelerator-Prompt-Builder.json). Afterwards continue at step 4 (the Content Security Policy) and, for a first install, set the object options in step 5.

Option B — SAS Environment Manager​

Import the JSON from SAS Environment Manager → Content → Import. Then correct the host in step 5: open the report and update the Data-Driven Content object's base URL to your SAS Viya server.

Option C — SAS Viya CLI​

Use the sas-viya command-line interface's transfer plugin. This assumes you have already installed the CLI, created a connection profile, logged in and installed the transfer plugin as described in Introduction — SAS Viya CLI Setup. In the commands below substitute https://viya.example.com with your own SAS Viya URL.

  1. Point the package at your host. Replace the placeholder in the JSON so the imported report loads the app from your server (the percent-encoded program path after the host is left untouched):

    # bash / Linux / macOS
    sed -i 's#https://your-sas-viya-host#https://viya.example.com#' SAS-Agentic-AI-Accelerator-Prompt-Builder.json
    # PowerShell / Windows
    (Get-Content SAS-Agentic-AI-Accelerator-Prompt-Builder.json) `
      -replace 'https://your-sas-viya-host','https://viya.example.com' |
      Set-Content SAS-Agentic-AI-Accelerator-Prompt-Builder.json

  2. Upload the package — the command prints the new package's id:

    sas-viya transfer packages upload --file SAS-Agentic-AI-Accelerator-Prompt-Builder.json

  3. Import it by that id:

    sas-viya transfer packages import --id <package-id>

    Or do both in one go, capturing the id (requires jq):

    pkg=$(sas-viya --output json transfer packages upload \
      --file SAS-Agentic-AI-Accelerator-Prompt-Builder.json | jq -r '.id')
    sas-viya --output text transfer packages import --id "$pkg"

    (On older transfer plugin versions the same commands are sas-viya transfer upload / sas-viya transfer import — they still work, marked deprecated.)

The host is a transfer substitution

The placeholder lives in the package's substitutions block (the VisualElement:ve9 value), which is exactly what SAS's import machinery is designed to remap. Editing the string before upload (step 1 above) is the simplest fix. Alternatively, remap it at import time with a mapping file: pass --mapping mapping.json to the upload and the CLI writes a JSON file whose substitutions block contains the VisualElement:ve9 entry with the placeholder URL — edit that value to your host, then pass the same file to the import:

sas-viya transfer packages upload --file SAS-Agentic-AI-Accelerator-Prompt-Builder.json --mapping mapping.json
# edit mapping.json: replace https://your-sas-viya-host in the VisualElement:ve9 value
sas-viya transfer packages import --id <package-id> --mapping mapping.json

(sas-viya transfer get-mapping --id <package-id> regenerates the file for an already-uploaded package.) If you do neither, the report still imports; you then correct the object's base URL in step 5.

After import, continue at step 3 — the Job Execution definition and report already exist under SAS Content > SAS Agentic AI Accelerator > Prompt Builder.

Preserving builder options across a report import​

Importing a report overwrites your configuration

Every option you set on a Prompt Builder or RAG Builder object — repository and project IDs, the SCR endpoint, the credential domain, the content root, the compute context, which vector stores the deployment offers — is stored inside the Visual Analytics report, not alongside it. A transfer package carries those values too, so importing a newer version of the report replaces your settings with whatever the package was built against.

This does not fail loudly. The report still opens and the app still runs; it simply points at somebody else's environment. Save your options before importing.

Two mdb commands cover this (see Model Definition Builder for installing the CLI and its [viya] extra):

# BEFORE importing a new report package
mdb options-save --file builder-options.json

# AFTER the import
mdb options-restore --file builder-options.json --dry-run   # check what would change
mdb options-restore --file builder-options.json             # write it back

options-save discovers the Model Manager repository and the LLM/Embedding projects exactly as mdb setup does, then overlays whatever your live Prompt Builder and RAG Builder reports already hold — so a deployment that has been tuned is captured as tuned, not as freshly bootstrapped. Keep the resulting file with your deployment records; it supersedes the older llm-prompt-builder.json / rag-builder.json seeds as the record of how this environment is configured.

options-restore writes back only the options named in the file. The newly imported report keeps its new layout, data items and objects, and regains your configuration. It also replaces the shipped placeholder host your-sas-viya-host - in the object's Data-Driven Content URL and in the viyaHost / SCREndpoint defaults - with SAS_VIYA_URL, so a report imported by hand needs no URL edit afterwards (mdb builders-import does both in one run).

Points worth knowing:

  • Reports are matched by name (Prompt Builder, RAG Builder). If you have renamed a report in your deployment, rename it in the file to match, or the restore skips it.
  • An option the report does not have is reported, not inserted. That usually means the option was renamed or removed in the newer version of the app — worth reading the message rather than ignoring it.
  • API keys are deliberately not saved. This file is meant to be kept with deployment paperwork and reviewed in a diff, which is no place for a provider key. The builders read their keys from the credential domain at run time — see Managing Credentials.
  • The file records which deployment it came from. Restoring it against a different SAS Viya URL still works — moving configuration between environments is a legitimate thing to do — but the command says so first, because doing it by accident is exactly the failure this guards against.
  • Concurrent edits fail loudly. The write is conditional on the report being unchanged since it was read, so a colleague editing the report in Visual Analytics at that moment causes an error rather than silently losing their work.

On a brand-new environment with no live report to capture from, run mdb options-save anyway: with nothing to overlay it writes the discovered values alone, which is the same content the old seed files carried.

1. Get the single-file app​

You have two options:

Option A — use the prebuilt file (recommended). Download the ready-to-use dist/index.html from the repository. No Node.js or build step is required — skip straight to step 2. Or copy the code from there to your clipboard and move to step 2.

Option B — build it yourself. With Node.js (^20.19 || >=22.12) installed:

git clone https://github.com/sassoftware/sas-agentic-ai-accelerator.git
cd sas-agentic-ai-accelerator/LLM-Prompt-Builder
npm install
npm run build

This produces the same single-file dist/index.html. See the project README for local development and customization details.

2. Create a SAS Job Execution definition​

The single-file app is served to Visual Analytics through SAS Job Execution:

  1. In SAS Data and AI Studio, click on New > Job definition to create a new Job Definition
  2. In the Job Definition (edit) tab go to the right hand side bar and click on the first icon (Associate a Form) and change it from Prompt designer to HTML form.
  3. Copy the full contents of dist/index.html and paste it into the Job Definition (edit) tab
  4. Save the job to the place you want it in SAS Content - note that people that should be using it need read access.
  5. On the right hand side bar click the second icon (Properties), expand the Details section and copy the value under Job URL - it should look something like this: https://your-viya-host/SASJobExecution/SASJobExecution/?_program=path-to-your-job-definition after the path value add the following: &_action=form, as this enables us to view the HTML form without having to provide any SAS code. Save that URL as we will need it in fifth step.
Why the build base64-encodes its scripts

SAS Job Execution serves HTML through a Go template engine that treats {{ … }} as directives. The build base64-encodes every inline <script> and decodes it at runtime so the minified bundle — which inevitably contains {{/}} — is not corrupted. This is automatic and requires no action.

3. Provide the API keys via the credential domain​

The Prompt Builder resolves provider API keys from a SAS Viya credential domain (default agentic-ai-keys) under the identity of the signed-in user — a user credential overrides a group credential, and models the user holds no key entry for are shown disabled with a note. Set the domain up once with the CLI-based scripts as described in Managing Credentials; no data source, table, or report assignment is involved.

Keys stay governed

Keys live encrypted in the Credentials service — never in the report definition, the URL, or a data table. Who holds a credential in the domain (directly or via group membership) is who can run paid model calls.

4. SAS Environment Manager configuration​

To let the app run inside SAS Visual Analytics, set the following Content Security Policy directives via SAS Environment Manager → Configuration → View Definitions.

SAS Visual Analytics — sas.commons.web.security → SAS Visual Analytics → content-security-policy:

default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src * blob: data:; frame-src * blob: data: mailto:; connect-src 'self' *.sas.com login.microsoftonline.com graph.microsoft.com *.arcgis.com *.arcgisonline.com; object-src 'none'

SAS Job Execution — sas.commons.web.security → SAS Job Execution → content-security-policy (replace <sas-viya-host> with your environment's URL). The 'unsafe-inline' and 'unsafe-eval' in script-src are what allow the base64-decoded single-file bundle to run:

default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://<sas-viya-host>; style-src 'self' 'unsafe-inline'; img-src * blob: data:; child-src 'self' blob: data: ; frame-ancestors 'self'; form-action 'self';

IFrame sandbox — verify the sas.visualanalytics definition's IFrame Sandbox Attribute Value contains at minimum allow-same-origin allow-scripts.

note

That sandbox does not include allow-popups, which is why the "Open in SAS Model Manager" link copies the URL instead of forcing a new tab on a normal click (use the browser's right-click → Open link in new tab). Add allow-popups to the IFrame Sandbox Attribute Value to let that link open a tab directly.

Restart the following kubernetes pods of your SAS Viya environment if saving the changes didn't trigger a restart automatically:

  • sas-job-execution
  • sas-job-execution-app
  • sas-logon-app
  • sas-visual-analytics
  • sas-visual-analytics-app

Example kubectl command:

kubectl get pods -n <your-namespace> -o name | grep -E 'pod/sas-job-execution|pod/sas-logon-app|pod/sas-visual-analytics' | xargs kubectl delete -n <your-namespace>

5. Add the object to a Visual Analytics report​

If you imported the SAS-Agentic-AI-Accelerator-Prompt-Builder.json package then open up the SAS Visual Analytics report under SAS Content > SAS Agentic AI Accelerator > Prompt Builder > Prompt Builder and then continue.

  1. In a Visual Analytics report, add a Data-Driven Content object and in the Options pane under Web Content enter the URL from the previous step or if you imported it update the base URL to your SAS Viya server.
  2. Assign the release table to the object: in the Data pane pick Public.ACCELERATOR_RELEASES (loaded by mdb setup or mdb load-releases; the library and name follow SAS_CAS_LIBRARY / SAS_RELEASES_TABLE) and add any of its columns to the object's role. A Data-Driven Content object does not render until it has a data assignment; the Builders themselves read nothing from it, and provider keys still come from the credential domain (step 3). The table carries the accelerator's changelog - one row per release and per change, with a component column - so the same report can show what changed for the Prompt Builder or the RAG Builder next to the object.
  3. Open the object's Properties panel and set the configuration values (see below).

Configuration (Properties panel)​

The core environment-specific values below are exactly those captured in your llm-prompt-builder.json — the file produced in the Setup SAS Model Manager chapter (regenerate it by re-running mdb setup if you have lost it). Copy each value from that file into the object's Properties panel. The last two fields are optional app settings that are not in that file:

Properties-panel fieldllm-prompt-builder.json keyURL parameterMeaning
SAS Viya host(not in the file)viyaHostSAS Viya base URL. Leave blank to default to the embedding origin.
Model Manager repository IDmodelRepositoryIDmodelRepositoryIDModel Manager repository in which new prompt projects are created.
LLM project IDllmProjectIDllmProjectIDModel Manager project holding the available LLM definitions (each with an options.json).
SCR endpointSCREndpointSCREndpointBase URL of the SCR endpoint hosting the LLM containers.
Deployment typedeploymentTypedeploymentTypek8s (default) or aca (Azure Container Apps / Instances). See Container Deployment.
Default judge model(optional — not in the file)judgeModelOptional. Name of an LLM in the LLM project used by default for the LLM-as-a-Judge comparison; prompt engineers can still override it in the app. Leave blank for no default.
Model card report URI(optional — not in the file)modelCardReportURIOptional. A SAS Visual Analytics report path (/reports/reports/<uuid>). When set, manifesting the best prompt embeds that report on its model card as the custom chart, hosted from the SAS Viya host above. Leave blank to omit.
Credential domain(optional — not in the file)credentialDomainCredential domain provider API keys resolve from (see step 3). Defaults to agentic-ai-keys; enter none when only key-less self-hosted models are used.
info

Until the three required values (repository ID, LLM project ID, SCR endpoint) are supplied the object shows a "Configuration required" message and does not call SAS Viya, so it never fails against placeholder IDs. Every field can also be appended to the object's URL by hand using its URL parameter name above (for example &judgeModel=...&modelCardReportURI=/reports/reports/<uuid>), which is a reliable fallback if your Visual Analytics version does not render the options panel.