Variables and secrets
Reusable tokens that get substituted into your tools at call time — including secrets that never leave the vault.
Variables are named tokens you reference inside tools
using {{token}} syntax. At call time the runtime substitutes the token's value
into the tool's URL, headers, params, or body. They keep your tool definitions
clean and let you change a value in one place instead of editing every tool that
uses it.
Where tokens go
You write a token like {{booking_url}} or {{api_key}} anywhere in a webhook
tool's request — the URL, a header, a param, or the body — and the runtime
swaps in the variable's value when the agent makes the call. The token is
config; the tool definition that references it is content.
Two kinds
Each variable is one of two kinds:
- Plain — a visible value. Use it for non-sensitive config: a base URL, an account ID, a region. You can see and edit the value in the UI.
- Secret — an encrypted value. Use it for API keys, tokens, and anything that must not leak. Secrets are stored encrypted in Supabase Vault, and only the runtime ever reads them.
Secrets are write-only
The encrypted value of a secret never comes back to the browser. That means:
- After you save a secret, the UI shows that it exists but never re-displays its value.
- To change a secret you paste a fresh value (which rotates it). Leaving the field empty on an edit means "do not rotate" — the existing value stays.
- The Builder Chat never receives secret values either. When a change needs one, it asks you to type it into a passive dialog so the value goes straight to the vault, not through the model.
Renaming
Renaming a variable updates every tool reference to it at once, so a {{token}}
you renamed does not silently break. Variables are scoped to the agent, not to a
version — they are configuration, so changing one does not require a new draft of
your prompt or tools.
Good practice
- Put every endpoint base URL and credential behind a variable instead of hard-coding it into a tool.
- Use plain variables for things that are safe to read; use secrets for anything you would not paste into a public channel.
- Name tokens for what they are (
{{crm_base_url}},{{calendar_api_key}}) so a teammate reading a tool can tell what gets substituted.