Resources

Variables and secrets

Reusable tokens substituted into your prompt, tools and workflow functions 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 in the prompt, in tools and in workflow functions. Write the {{token}} and the runtime substitutes the real value at call time. The prompt takes plain variables only. In a tool, write the token in the URL, a header or the mock response. The runtime does not substitute variables in the request body, which holds what the agent sends.

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 three types, 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.
  • Dynamic. Filled in per call by your system or a test profile. You give it a default value, which is used when nothing is sent.

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

A variable's type 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 letters, numbers and underscores, 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. A dynamic variable has a Default value instead.

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:

  1. Your per-agent variable. A variable you set with that name wins, as does a value sent for a dynamic variable on this call.
  2. 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.
  3. A dynamic variable's default value, when nothing was sent for it.
  4. 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.

Caller identity

Seven {{caller.*}} tokens put what the platform knows about the caller in a tool's URL, headers or mock response. When a user signed in to Microsoft Teams calls or messages the agent, Teams has already confirmed who they are, and the first five carry that identity.

TokenValue
{{caller.email}}The user's email address
{{caller.upn}}Their Microsoft 365 sign-in name
{{caller.object_id}}Their Microsoft Entra object ID
{{caller.display_name}}Their display name
{{caller.verified}}teams when Teams confirmed the identity
{{caller.number}}The phone number the call came from
{{caller.callback_number}}The mobile a website visitor typed in before a browser call

The runtime fills them from the conversation that is running. No variable and nothing the agent sends can change them, so an endpoint can trust a header such as X-Verified-User: {{caller.email}} and refuse any other account. On a phone call, a web chat or a test, nothing confirmed the caller, and the five identity tokens are empty.

These are not variables, so you do not create them, and the publish check accepts them. A misspelt field, such as {{caller.emial}}, blocks publish.

Renaming safely

Renaming is atomic: the variable and every {{token}} reference to it are rewritten in one step. The editor confirms how many references it updated.

Rename on a draft. The draft's prompt, tools and workflow are rewritten, and the live version keeps the old name until you publish.

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.

On this page