Variables and secrets

Reusable tokens substituted into your tools at call time, including secrets that stay encrypted in the vault and never reach the model.

A variable is a named value you write once and reuse anywhere a tool makes an HTTP request. Write the {{token}} in the URL, a header, a param or the body, and the runtime substitutes the real value at call time.

GET {{booking_url}}/slots?date={{$today_iso}}
Authorization: Bearer {{calendar_api_key}}

Why use variables

Reuse. Three tools calling the same booking system share one {{booking_url}}. Move to a new endpoint and you edit one value, not three tools.
Safety. An API key belongs in a secret variable, where it is encrypted and only the call-time runtime can read it. The key never sits in plain text inside a tool and never reaches the language model.

Plain and secret

Variables belong to a version: you edit them on a draft, the same way you edit your prompt and tools, and the change reaches live calls when you publish.

Every variable is one of two kinds, set when you create it.

Plain. Visible to anyone with workspace access. Use for non-sensitive values: a base URL, an account ID, a region code.
Secret. Stored encrypted, shown as bullets after you save, and never displayed again. Use for API keys, tokens, and anything that must not leak.

See Secret handling for where a secret lives and how it stays out of the model's reach.

A variable's kind is fixed after creation. To change it, delete the variable and create a new one.

Add, edit, and delete

The Variables section lives under your agent in the editor's left rail. Each variable has three fields:

Name. Lowercase snake_case, starting with a letter, up to 64 characters (e.g. booking_url). This is the name you put inside {{...}}.
Reference. A read-only, click-to-copy {{token}} you paste into a tool.
Value. The plain text or secret value.

Deleting a variable does not clean up the tools that reference it. Any tool still using {{the_deleted_name}} keeps the literal placeholder in its request, which sends a broken URL and fails the call. Update or remove those tools first.

How a token resolves

The runtime resolves each {{token}} in this order:

Your per-agent variable. A variable you set with that name wins.
A platform-managed value. A small set of shared names resolve from a runtime setting. These are managed for you and hidden from the Variables list.
Leave the token in place and warn. If nothing matches, the literal {{token}} stays in the request and the runtime logs a warning.

The request then fails fast (typically a 404) instead of silently calling the wrong endpoint. The publish check refuses to publish a version whose tools reference an unresolved {{token}}, so a missing variable should not reach a live call.

Renaming safely

Renaming is atomic: the variable and every {{token}} reference to it are rewritten in one step across the draft's prompt, tool URLs and headers. The editor confirms how many references it updated.

A published version is an immutable snapshot. If one still references the old name, the rename is rejected until you create a draft.

Good practice

Put every endpoint base URL and credential behind a variable.
Use plain for values safe to read, secrets for anything you would not paste into a public channel.
Name tokens descriptively ({{crm_base_url}}, {{calendar_api_key}}).
When you retire a variable, update or delete referencing tools in the same change.