> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/agent-builder/build/secrets-and-variables.md). # Secrets & Variables **Secrets & Variables** is the agent's keychain and configuration store. The page holds two parallel tables: **Secrets** (API keys, tokens, credentials — stored encrypted) and **Variables** (general-purpose values like base URLs, IDs, default parameters — stored in clear). Everywhere else in the builder that needs a value the agent will resolve at runtime — a skill's API endpoint, a credential in an instruction, an integration's auth header — references the value from this page through a `$secret.` or `$agent.` reference rather than pasting the value inline. Manage Agent → Secrets & Variables, with two tables Reach this page from **Manage Agent → Secrets & Variables** in the left navigation. ### Secrets The top table on the right pane holds the agent's secrets — values that need to be encrypted at rest and never appear in clear in logs or traces. > Store API keys and sensitive credentials. **Usage syntax:** `$secret.{variable_name}` — for example, `$secret.API_URL`, `$secret.STRIPE_SECRET_KEY`. Reference a secret by its `$secret.{name}` form anywhere the platform accepts dynamic values: skill configurations, trigger descriptions, instructions, integration settings. #### Columns

Column	What it holds
Name	The identifier you reference. Becomes `$secret.{name}`.
Type	The secret's type (text, key, token, etc.). Affects how the value is masked in the UI.
Value	The secret's value. Stored encrypted; displayed masked by default.
Secured	A per-row toggle controlling whether the value is stored in encrypted form. Leaving it on is the right default for anything sensitive.

Add a new row by clicking `+ Add Secret` at the bottom of the table. ### Variables The bottom table on the right pane holds the agent's variables — non-sensitive values that change between environments or use cases, but don't need encryption. > Store general purpose variables for execution context. **Usage syntax:** `$agent.{variable_name}` — for example, `$agent.BASE_URL`, `$agent.DEFAULT_REGION`. #### Columns

Column	What it holds
Name	The identifier you reference. Becomes `$agent.{name}`.
Description	A short note on what the variable is for. Useful when another team member opens the agent later.
Default Value	The variable's stored value.

Add a new row by clicking `+ Add Variable` at the bottom of the table. ### Obligation across the two tables | Field | Obligation | Notes | | ----------------------- | ---------- | ---------------------------------------------------------------- | | Secret Name | Mandatory | Required to save the row. | | Secret Type | Mandatory | Controls masking and rendering. | | Secret Value | Mandatory | The actual value being stored. | | Secret Secured (toggle) | Optional | Defaults on; turn off only for values that are genuinely public. | | Variable Name | Mandatory | Required to save the row. | | Variable Description | Optional | Recommended. | | Variable Default Value | Mandatory | Required to save the row. | > **Note — Skip-behavior not exercised** Empty-submit validation messages were not captured. The obligations above are inferred from the field labels and the column structure of the two tables. ### When to use a secret versus a variable Use a **secret** for anything that would be a problem if it leaked: API keys, OAuth client secrets, database passwords, internal endpoints not meant for public exposure. Use a **variable** for anything that's safe to expose but useful to centralize: base URLs that differ between staging and production, default region or locale codes, identifiers that other parts of the agent reference repeatedly. A useful rule: if you'd hesitate to paste the value into a public Slack channel, it belongs in Secrets. If you wouldn't hesitate, it belongs in Variables. ### How references resolve at runtime When the agent runs, the platform resolves `$secret.{name}` and `$agent.{name}` references to their stored values before passing the substituted content to skills or to the model. The reference syntax stays in the *stored* configuration; only the runtime sees the resolved value. This means: * A skill configuration that references `$secret.STRIPE_SECRET_KEY` shows the literal `$secret.STRIPE_SECRET_KEY` in the configuration form, not the actual key. * The same reference resolves to the real key when the skill executes. * Updating the secret's value updates every skill that references it, immediately, without re-editing each skill. This is the main reason secrets and variables belong on a single page rather than scattered through the skills that use them: one place to rotate a key when it changes. ### Why this matters This page is the boundary between *configuration* (what the agent's been told to do) and *credentials* (what the agent needs to actually do it). Keeping that boundary clean — every credential here, every reference elsewhere — gives you three things the alternative doesn't. First, secrets don't appear in Instructions, trigger descriptions, or skill configs that may be visible in traces or shared with other team members. Second, rotating a credential is a one-row edit rather than a scavenger hunt. Third, the same agent can be promoted across environments by changing the values here without touching anything else. Treat this page as the canonical source for anything the agent needs to authenticate or address an external system. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.uptiq.ai/agent-builder/build/secrets-and-variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.