Add variables
Open the variable group, click Add variable and fill in the row.
You can rename a variable that is in use. Delete is refused while something uses it. See Rename and delete.
Group names follow the same rule as variable names.
environment is reserved and can’t be a group name.
Use a variable
Write{{agent.<group>.<name>}}. For a group named Business and a variable opening_hours:
agent. in front means the value belongs to the agent and is the same everywhere in it. A name without it, such as {{customer_email}}, is local to one workflow.
It works in:
- Workflow fields, in every step. An Execute Code step reads it as
agent["Business"]["opening_hours"]instead. - Conversation flow instructions, messages and starting values.
- Coworker instructions, and the opening text of a session that a workflow, a schedule or a person starts in the app.
{{agent.Business.holidays[0]}}.
To read the name of the environment the agent runs in, write {{agent.environment}}. It is read-only. See Environments.
Pick a variable with {{
Type {{ in a workflow field or a conversation flow field. One list opens, in three groups, in this order:
- Step outputs: what the steps before this one give back.
- This workflow’s variables: the variables of the workflow you are editing.
- Agent variables: the variable groups of the agent. A secret shows a lock.
How a reference looks in a field
In a workflow field or a conversation flow field,{{agent.Business.opening_hours}} shows as a small chip: Business › opening hours. An underscore in the name shows as a space in the chip only.
- Hover a chip. A card opens with the value, the type and an Edit link. Edit opens the variable group in a new tab, so unsaved edits in the field stay.
- A secret shows as
••••••••. The card never shows the value. - A name that doesn’t exist shows as a red chip. Its card says No such variable and offers Create it, which opens the group in a new tab. After you create the variable, the chip turns normal when you come back to the window. Every chip is checked again when you come back to the window.
- Backspace removes the whole chip in one press.
- Copy keeps the raw text,
{{agent.Business.opening_hours}}.
{{agent.…}} reference, with no chip.
Rename and delete
On the variable group’s page, rename a variable and every place that uses it is updated: workflows, conversation flows (published versions too), recurring task messages and coworker instructions. An Update Agent Variable step keeps pointing at it. The dialog says how many places it updates, for example Updates 3 places. When every use is in items you can’t open, it says Updates places you cannot open. Delete is refused while something uses the variable. The dialog shows Used by: each workflow, conversation flow or coworker, with a link and where in it the variable sits. Change those to stop using it, then delete it. When nothing uses it, the variable and its value are deleted.A name that doesn’t exist
A reference to a variable the agent doesn’t have is refused when you save. The message sits under the field you saved, in plain words:{{agent.Business.hours}}: there is no variable "hours" in the group Business.{{agent.Busines.hours}}: this agent has no variable group "Busines".
A name that doesn’t exist reads as empty in a conversation flow and a coworker. In a workflow it is left as it is, like an unknown variable.
Move a workflow variable to the agent
A variable of one workflow often belongs to the whole agent. In a workflow that sits in an agent, open its variables drawer. A variable that no step changes, or a secret one, shows a small hint under it: Move to agent variables? Press Move, or the close button to hide the hint for that variable. The hint stays hidden for that workflow in this browser. The dialog asks you to pick a Variable group, or A new group with a New group name. It shows what moves:- The agent variable gets the same type and value.
- Every
{{name}}in that workflow becomes{{agent.<group>.name}}, and so does the name in the expression of a condition step. The dialog counts the places. - Plain text is left as it is: prompts, names and descriptions. A word there never blocks the move.
- The workflow variable is removed.
- A secret moves as a secret and is never shown again. The dialog asks for its allowed hosts, under Where this secret may be sent.
- Values given when a run starts (the Start form or the API) no longer apply to it. The agent variable’s value is used.
- A code step reads it. “A code step reads it. Change that code to read agent[“group”][“name”] with the group you move it to, then move.” Edit the code as Execute Code describes, then move.
- A step’s expression binds its own local with that name, for example
iteminrows.map(item => item.name). The dialog says: “The expression in step › field uses its own “item”. Rename it there, then move.” - A mention inside
{{ }}that the move can’t read as code, such as one in a string or a comment. The dialog says: ""item” is also used in step › field in a way the move cannot update.” - A secret in a field that doesn’t go to a tool. “A secret can be used only in fields that go to a tool: HTTP headers, query or body.”
- A step changes it. “The step name changes it. Agent variables change only through Update Agent Variable, so it stays a workflow variable.” Use Update Agent Variable for agent variables.
- Anything else, such as a file, a list of a type that can’t be a list, or a key that can’t name an agent variable (letters, digits and
_only). The dialog says what is wrong.
Change a variable
- By hand, on the variable group’s page.
- From a workflow, with the Update Agent Variable step, or from an Execute Code step with
set_agent_variable. - From a coworker, with the tools
list_agent_variables,get_agent_variableandset_agent_variable. Setting a value asks you first. See Data stores for coworkers. - From another agent, when the group is shared with other agents at Read & write. See Use a store another agent shares.
- From outside, through the store’s Manage access, when it allows writes.
Secrets
A Secret is for API keys, tokens and passwords. You enter it once, and it is never shown again.- The page shows
••••••••, who set it and when, and a Replace button. There is no reveal and no copy. - No screen, API, export or copy returns the value. Reads show it masked.
- Only people set a secret’s value, on the group’s page. A workflow, a coworker or an outside caller can’t.
- It stays with its agent. When the group is shared with other agents, their items can’t use its secrets: the pickers show them greyed, and a step that names one is refused.
- It is stored encrypted, and removed from run history, test sessions, error messages and logs.
- It is at least 8 characters long.
Allowed hosts and where a secret goes
Every secret lists the Allowed hosts it may be sent to, such asapi.example.com or *.example.com. A secret goes only to those hosts, and only over https.
A secret can be used only in fields that go to another service: the headers, query, body or form of an HTTP Request step, and the same fields of a custom request in a conversation flow.
You can’t put one in an AI instruction, a message, coworker instructions, a variable or a file. Saving such a reference is refused with a message that says why.
http_request tool, which always asks first. “Always allow” can’t turn that off. The approval names the secret, where it goes and the hosts it is allowed on.
Let a code step read a secret
An Execute Code step can use a secret only when you allow it. Open the variable group and turn on Code steps can read this secret under the secret. It is off by default, and only a person turns it on. It belongs to the variable and is the same in every environment. A code step gets the value itself and can send it anywhere. Its output, logs and errors hide the exact value. A changed form of it, such as an encoded one, is not hidden, and files the code writes are not checked.- The code must name the secret directly, as
agent["Billing"]["api_key"]. No other secret reaches the step. - With the switch off, the step fails before the code runs:
The secret "Billing › api_key" is not readable by code steps. Turn on "Code steps can read this secret" on the variable. - A value from a secret can’t be stored in a workflow variable or in an agent variable that is not a secret.
- A secret shorter than 8 characters can’t be used in a code step.
Environments
Each environment of an agent holds its own value for each variable. Production is the one every agent has. You can add others, such as Demo with sample values. The variables themselves, their names and types, are the same in every environment. The agent runs in one environment at a time, and its variables read that one. An environment also holds its own files and rows, and its own channels, endpoints, triggers and schedules. See Environments for all it holds, how to add one and how to switch. An agent that never adds an environment stays in Production and shows nothing new. Once it has more than one, a reference chip’s hover card shows the value in the current environment and names it.Values in an environment
Open a variable group. A selector at the top lists the environments and opens on Production. The values you see and edit are those of the environment you pick, not necessarily the current one. The page says which one it is showing, and which one the agent runs in. Compare shows every environment side by side, one column each, with the empty cells marked. A cell opens its value to edit. A secret shows only Set or Empty. A value that is empty in an environment stays empty. It never falls back to Production’s value. This keeps a Demo agent from using real values by accident. Empty means no value at all. An empty string"" and an empty list [] are values.
A secret is set for each environment, in the app, and its allowed hosts stay the same. A new environment’s secrets and accounts start empty, unless you tick Copy secrets and accounts too when you add it. That copy happens inside the server, and no screen ever shows them.
A new variable gets its value in the environment you add it in. In the others it starts empty. Deleting or renaming a variable applies to every environment.
Start needs values
Start is refused while a variable that a running part of the agent reads has no value in the current environment. Parts that run are published workflows and conversation flows, a coworker’s instructions and its enabled schedules, and enabled channels. Drafts, stopped items and disabled schedules never block Start. A step that only writes a variable, with Update Agent Variable, never blocks it either. The dialog says how many variables have no value in the environment and lists each one with where it is used. Each row offers:- Set a value, which opens the variable group on that environment at the variable.
- Leave empty, for text and lists only. It saves
""or[]in that environment. Use it when nothing is the right value.
Share an environment’s values
When you share the agent, you pick which environment’s values the copy gets. See Share from an environment.Another agent’s group
A variable group another agent shares with yours is always read in that agent’s Production, whatever environment either agent runs in. A change through it lands in Production too, and only while your agent runs in Production: in any other environment your agent can read the group but not change it. Your agent’s Start counts the values it reads that are empty in that agent’s Production; the other agent’s Start never counts your reads. See Stores other agents share.Read the environment
Write{{agent.environment}} to use the current environment’s name in a workflow, a conversation flow or a coworker’s instructions, for example to label a test message. It is Production in Production.
From outside, the Agent data API and the MCP tools read and write the current environment, and say which one they used.
Connection variables
A Connection variable holds an account of one app, such as a HubSpot or Gmail account. A step, a trigger or a channel takes its account from the variable instead of holding the account itself. Change the account in the variable and everything that uses it follows. You pick the app when you add the variable, and it is fixed after that. The variable has one account per environment. Production can hold the real account and Demo a demo account, and the same steps use whichever one the agent runs in.Connection variables work in workflow steps, conversation flows, coworkers, triggers and channels.
Add one
Open the variable group, click Add variable, set Type to Connection and pick the app. Then pick the account for each environment. You can also create one from a step’s account picker. See Use it in a step. A Connection variable is not a list and has no text value. Sharing an agent sends its definition (name, app and description), never an account.Only shared accounts
A Connection variable can hold only an account that is shared with the workspace, or with the agent’s project. Everyone who can edit the agent may use whatever account a step takes from it, so a private account would hand it to people who were never given it. To use a private account, share it with the workspace first. The account picker lists your private accounts of that app, muted, with “Private. Share it with the workspace to use it here.” and a Share button for the ones you own. An agent in a project can use accounts of that project and workspace accounts. An account of another project is refused. A Connection variable is used only by its own agent’s items. When its group is shared with other agents, they can’t use it: it shows greyed in their pickers, and a step that names it is refused.Pick an account
Under each environment, the variable shows an account picker with the accounts of its app. Connect a new account is there too. Under the picker, Used by 3 steps tells you what the account powers. It says “Not used by any step yet” when nothing uses it. Only a person sets a Connection variable: in the app, with an endpoint key a person made, or over MCP as a person. A step or a coworker that tries gets “A Connection variable is set by a person.” It can’t clear one or delete one either. You can pick only an account you may use. An empty value means no account.Use it in a step
Open the account picker of a step and look for From variable. It lists the agent’s Connection variables of that app, each with the account it holds in the current environment. Pick one, or Create a Connection variable. From variable is in the account pickers of:- Action in App steps.
- AI, Code and Human steps, in the account of each integration.
Use it in a conversation flow or a coworker
These take their account from a Connection variable too:- Conversation flow: an actor’s integrations, and the flow’s own integrations. Open the integration’s account picker and pick From variable.
- Coworker: an integration’s drawer has an Account section. Pick an account or From variable. A coworker integration needs one of the two. The drawer won’t save without it and says “Pick an account or a Connection variable”.
A live conversation or a coworker session never uses another account in its place. When the variable has no usable account, the app’s tool is left out and the gap is reported. The conversation or the session goes on without that app. A coworker says so, for example “The CRM account for this agent is not set in Demo, so HubSpot is not available now.”
A coworker’s “talk to people” channels can use a Connection variable too. If it has no usable account when a session starts, that channel is not offered and the coworker gets one note about it. Bring in channels keeps the variable.
Renames and moves keep the flows and coworkers in step. A coworker session that is already running follows them too, so it never loses a variable or picks up another one by name.
Use it in a trigger or a channel
A trigger and a channel take their account the same way. The account picker has From variable, and the chip shows “the account in Demo”, the account the variable holds in the current environment. Use an account instead goes back to an account of its own.- Triggers: an App Trigger step, or any built-in trigger that listens through an account.
- Channels: the agent’s Channels, such as Gmail, Slack or Telegram. This includes the channel settings drawer of a conversation flow and the channels of a coworker.
When an account goes away
If its owner makes the account private, or someone deletes it, the variable loses it. The value is removed in every environment that held it. Needs attention shows “Its account is no longer shared, so it was removed. Pick a shared account.” Pick another account to clear it. The same happens when the account is moved to another project. A channel or trigger that used the variable stops listening until you pick another account.Deleting an account
When someone deletes an account, every Connection variable that holds it is emptied, in every environment. Each one shows under Needs attention: “Business › CRM account: its account was deleted, so it is empty in Production and Demo. Pick another account.” The line names the environments where it is now empty. Pick an account opens the variable, on the agent’s current environment first. A person’s accounts are cleared the same way when that person is deleted. Channels and triggers that used it stop listening, and Start is refused while a variable that something uses is empty. The delete dialog lists these variables first, under Used by. See Used by.Switching an account off
An account that is switched off or signed out stays in the variable, but a run can’t use it. The chip and the From variable list show it in red. Switch it back on and everything works again, with nothing to re-pick. Needs attention shows one line for each variable that holds it, with Open Connections and Pick an account. The line depends on the account:- Switched off: “Business › CRM account: its account “sales@example.com” is switched off in Production. Switch it on in Connections, or pick another account.”
- Signed out: ”… is signed out in Production. Reconnect it in Connections, or pick another account.”
- Not set up yet: ”… is not set up yet in Production. Set it up in Connections, or pick another account.”
- Gone: ”… its account is no longer available in Production. Pick another account.” This line has no Open Connections.
What a run does
A step that takes its account from a variable looks it up in the current environment when it runs. If it can’t, the step fails with a message and does nothing else.
A run never uses another account of the app in place of the variable’s. This keeps a Demo agent from using the real account by accident. The usual checks still apply to the account the variable holds.
Switch the environment
Switching the environment changes which account every step uses. The variable keeps one account per environment, and an environment that has none stays empty. It never takes Production’s account. Compare on the variable group shows the account names side by side, with the empty ones marked. Start is refused while a Connection variable has no account in the current environment and a running part reads it: a workflow step, a published conversation flow, the agent’s coworker, a trigger or a channel. An account that is switched off or signed out is listed in the Start dialog and in Needs attention, but does not refuse Start, because it may come back. See Start needs values.Move a variable group
You can’t move a variable group to another agent while a Connection variable in it is used. Like deleting, the message lists what uses it under Used by. Change those to stop using it, then move the group.Sharing and installing
A shared copy carries each variable with its value. Secrets arrive empty, marked as needing a value, with their allowed hosts. The share screen shows what will go, and warns about a variable that looks like a credential, also in a list or a JSON value. Use Make it a Secret there to move its value into a secret. See Sharing agents. A shared copy keeps Code steps can read this secret off. When the shared agent’s code steps read a secret, Finish installation shows the switch next to the secret’s value, with “The shared agent’s code steps read this secret. Turn it on to let them.” The choice is yours.Next steps
Update Agent Variable step
Change a variable from a workflow.
HTTP Request
Send a secret to an outside service.
Agent data API
Read and change variables from your own app.
Data stores
The other kinds of store.
