Configure app variables and secrets app-variables

Use variables and secrets to configure your app without hardcoding values in its action handlers. For example, set the URL of the product catalog API your app calls, using a test service in Stage and the live service in Production, without changing the handler code.

Variables hold non-sensitive settings. Secrets are intended for sensitive values such as API keys and access tokens.

Journey: Add a variable or secret → read it in your handler → deploy → test.

Before you begin before-you-begin

You need:

To check the version, run this in your handler repository:

npm ls @adobe/llm-apps-runtime

If the version is earlier than 1.1.0, upgrade it, then commit and push package.json and package-lock.json:

npm install @adobe/llm-apps-runtime@latest

Manage variables manage-variables

Each environment, Stage or Production, has its own variables, so check Workspace before you add, update, or delete one. Changes take effect the next time you deploy the app to that environment.

Add a variable add-variable-to-app

This guide uses a variable named GREETING_PREFIX with the value Good day as a non-sensitive example, overriding the handler’s default greeting of Hello. Adding a variable does not change an action automatically: the handler must read it.

Step 1: Add a variable in the UI add-a-variable

The variable appears in the table with its Name, Type, Value, and Last updated date. Use the copy control beside the value if you need to copy it.

Step 2: Read the variable in your handler use-a-variable

In your handler repository, open actions/<action-name>/index.js. Make sure the handler accepts a second argument, extra, and read the variable with getVariable:

const { getVariable } = require('@adobe/llm-apps-runtime');

module.exports = async ({ name = 'there' } = {}, extra) => {
  const prefix = getVariable(extra, 'GREETING_PREFIX') || 'Hello';

  return {
    content: [{ type: 'text', text: `${prefix}, ${name}!` }]
  };
};

With the value Good day, a call with name set to Ada returns Good day, Ada! instead of the default Hello, Ada!. If you later change the value to Howdy, the greeting changes after you redeploy, without another handler edit.

The name in your code must match the name in the UI exactly. If the variable is not set, getVariable returns undefined. Decide whether your action can use a suitable default, as in the example, or should return a clear error because it requires the setting.

When your handler changes are ready, commit and push them to your app’s handler repository. The next deployment uses the latest pushed code. To learn more about editing handlers, see Customize a generated handler.

Step 3: Deploy and test deploy-and-verify

To configure the other environment, select it in Workspace, repeat the setup with the appropriate value, then deploy and verify there.

Update a variable update-or-delete

Updating changes only the value. Variables cannot be renamed; to use a different name, delete the existing variable and add a new one, then update your handler to read the new name.

Delete a variable delete-a-variable

Rules and limits good-to-know

Troubleshooting verify-configuration

What’s next whats-next