Secrets

Secrets let you securely store sensitive information like API keys, database credentials, and encryption keys. Unlike variables, secret values are encrypted and hidden from view, keeping your credentials safe while still allowing your agent to use them. A secret’s name is shared across your whole project; its value belongs to each environment.

Creating secrets

Open Secrets in your agent’s navigation and click New secret in the top right.

When creating a secret, you’ll provide a name, value, and visibility setting:

• Masked secrets are hidden by default but can be temporarily revealed by clicking on them.
• Restricted secrets cannot be revealed after creation. Use this for highly sensitive credentials.

The value you enter is stored in the environment you have open. Every other environment picks up the new secret’s name right away, but not its value, and shows a Missing value warning on that secret until you set a value there too.

You can also create secrets inline while building. Type { in any input field, switch to the Secrets tab in the dropdown, then click Create secret at the bottom.

Using secrets

Secrets work like variables but are accessed from a separate tab. In any input field within a tool, type { to open the dropdown, then switch to the Secrets tab and select the secret you need.

Which value your agent sends depends on the version that handles the conversation. Every environment holds two values for each secret:

Default value is the value this environment uses. Previews and test conversations run against the draft version, so they send the Draft value when one is set and the Default value when it isn’t. Your live agent only ever sends the Default value.

Secrets in each environment

The Secrets page always shows the environment you have open. Use the environment switcher at the top of the sidebar to move to another environment and see the values it holds.

Next to each secret’s name are its Default value, its Draft value, and Updated, which shows when that secret’s value was last edited in this environment. Publishing, merging, or cloning doesn’t change it: a value copied into a new version or environment keeps the time it was edited.

An environment that has no value for a secret shows a Missing value warning on that row. Because every environment holds its own values, a secret you set up in one environment needs a value in every other environment that uses it.

Managing secrets

Click the three dots next to a secret for Copy value, Edit, and Delete. For masked secrets, Copy value copies this environment’s default value to your clipboard. Restricted secrets cannot be copied or revealed.

Edit opens the same dialog you created the secret with, for the environment you have open. Enter a new Default value to replace this environment’s value; leave the field empty to keep the value it has. To stop using a Draft value, click Clear draft value under the field and save; the draft version goes back to using the default value.

Delete removes the secret and every environment’s values for it, and can’t be undone. Delete a secret only when nothing anywhere in the project still needs it.

When a value is missing

When a tool references a secret that the environment has no value for, your agent sends the placeholder text exactly as written: a header entered as Bearer {my_api_key} goes out as Bearer {my_api_key}. The service you’re calling rejects it, usually with a 401, the step takes its failure path, and the conversation continues. Nothing warns you at run time, so a missing value looks like an ordinary API failure until you check the secret’s row for the Missing value warning.

Publishing, reverting and discarding changes

Publishing, reverting, and discarding changes act on your agent’s content. Here is what each one does to an environment’s secret values.

Testing with a non-production credential

A Draft value lets an environment’s draft version call a sandbox service while its live version keeps calling the real one.

Merging to Main

By default, merging an environment into Main leaves Main’s secret values alone. When the source environment’s values differ from Main’s, the merge dialog tells you: “This environment has different secret values than Main, select how to proceed.” Turn on Override Main secrets to replace Main’s values with the source environment’s, both the Default value and the Draft value. A secret the source environment has no value for is removed from Main too, which leaves Main with no value for it.

The dialog never shows the values themselves, only that they differ. Before you confirm with Override Main secrets on, make sure the source environment’s Default value is the production credential, because it becomes the value Main’s live version uses. A sandbox key left in Draft value only reaches Main’s draft version; clear it first if you don’t want it there.

Duplicating and exporting projects

Duplicate project copies your secrets, with the Default value and Draft value they hold in Main, when the copy stays in your workspace. A copy made in another workspace, for example through Copy clone link, and an exported project carry secret names only. After importing, set the values in each environment that needs them.

Security

Secrets are encrypted using AES-256 GCM, which provides both confidentiality and integrity protection through a Message Authentication Code (MAC). Encryption keys are securely managed and secrets are stored and transmitted according to industry best practices.