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 tokens
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 two 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.
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.
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.
Caller identity
When a user signed in to Microsoft Teams calls or messages the agent, Teams has
already confirmed who they are. Five {{caller.*}} tokens put that identity in
a tool's URL, headers or mock response.
| Token | Value |
|---|---|
{{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 |
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 every token is
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.