> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent variables and secrets

> Keep an agent's names, prices, hours and API keys in one place and use them in workflows, conversation flows and coworker instructions.

Agent variables are named values that belong to one agent, kept in groups. Change a value once and every workflow, conversation flow and coworker of that agent uses the new one on its next step.

Add a group with **Add → Variable group** under an agent, and give it a name such as "Business" or "API\_keys".

## Add variables

Open the variable group, click **Add variable** and fill in the row.

| Field | Rule |
| - | - |
| **Name** | Letters, digits and `_`. Unique in the group. Used when you refer to it |
| **Type** | String, Number, Boolean, Date, URL, JSON, Secret or Connection. See [Connection variables](#connection-variables) |
| **List** | String and Number can hold a list of values |
| **Value** | Checked against the type when you save |
| **Description** | Optional. Shown on hover in pick lists and to whoever installs a copy |
| **Ask on install** | Optional. Asks whoever installs a copy to review the value |

You can rename a variable that is in use. Delete is refused while something uses it. See [Rename and delete](#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`:

```text theme={null}
We are open {{agent.Business.opening_hours}}.
```

The `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](https://docs.cogniagent.ai/nodes/actions/execute-code.md#read-and-set-agent-variables) 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.

The value is read when the step runs, so a change shows up in the next step that reads it. A field that holds only the variable keeps its type: a Number stays a number.

For a list, add the position: `{{agent.Business.holidays[0]}}`.

To read the name of the environment the agent runs in, write `{{agent.environment}}`. It is read-only. See [Environments](#environments).

> [!WARNING]
>
> `agent` is a reserved word. A workflow variable or a step can't be named `agent`, because it would hide the agent variables.

## Pick a variable with `{{`

Type `{{` in a workflow field or a conversation flow field. One list opens, in three groups, in this order:

1. **Step outputs**: what the steps before this one give back.
2. **This workflow's variables**: the variables of the workflow you are editing.
3. **Agent variables**: the variable groups of the agent. A secret shows a lock.

The list ends with the JavaScript helpers. A secret can be picked only in a field that goes to another service. See [Secrets](#secrets).

## 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}}`.

Use the keyboard to reach the card: put the cursor next to a chip and it opens with the same content. Tab to its links, and press Escape to close it.

Coworker instructions are plain text. They show the raw `{{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](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md) 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".`

The message shows under the field. When the field is not on screen, such as one in a closed tab or section, a message at the top of the panel names where it is, for example "In Headers.", with a **Show** button that opens it. It ends with "Your changes are still here: fix the reference, then save."

Fix the name, or create the variable, then save again. The same check covers a coworker's instructions, a recurring task's message and changes made by the Concierge or the builder tools.

Installs and imports never refuse. A shared copy, an Agent Library install, an import or a restore keeps the text as it is. Each unknown reference shows under **Needs attention** on the agent, with the item that holds it. It clears once the text is saved without it, or once the variable exists.

> [!NOTE]
>
> 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.

Sticky notes are never read by a run, so they are not checked.

## 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.

The move is refused up front, and the dialog says why, when it can't update every use with certainty. Nothing changes when it is refused:

* **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](https://docs.cogniagent.ai/nodes/actions/execute-code.md#read-and-set-agent-variables) describes, then move.
* **A step's expression binds its own local with that name**, for example `item` in `rows.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](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md) 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](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md) step, or from an [Execute Code](https://docs.cogniagent.ai/nodes/actions/execute-code.md#read-and-set-agent-variables) step with `set_agent_variable`.
* **From a coworker**, with the tools `list_agent_variables`, `get_agent_variable` and `set_agent_variable`. Setting a value asks you first. See [Data stores for coworkers](https://docs.cogniagent.ai/cowork/capabilities/data-stores.md).
* **From another agent**, when the group is shared with other agents at **Read & write**. See [Use a store another agent shares](https://docs.cogniagent.ai/features/data-stores.md#use-a-store-another-agent-shares).
* **From outside**, through the store's [Manage access](https://docs.cogniagent.ai/api/stores.md), when it allows writes.

**History** on the group's page lists every change: who made it, when, and the old and new value. A secret shows only who and when. The log keeps 90 days, and at least the latest 200 changes of each variable.

## 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 as `api.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](https://docs.cogniagent.ai/nodes/actions/http-request.md) 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.

```text theme={null}
Authorization: Bearer {{agent.API_keys.crm_token}}
```

A coworker uses a secret through its `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.

> [!WARNING]
>
> If a secret is exposed by mistake, replace it in the service that issued it, then use **Replace** here.

### Let a code step read a secret

An [Execute Code](https://docs.cogniagent.ai/nodes/actions/execute-code.md#use-a-secret) 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](https://docs.cogniagent.ai/features/environments.md) 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](https://docs.cogniagent.ai/features/environments.md) 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](https://docs.cogniagent.ai/features/environments.md#add-an-environment). 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](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md), 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.

Press **Start again** once they are set. A secret with no value must be set by a person.

### Share an environment's values

When you share the agent, you pick which environment's values the copy gets. See [Share from an environment](https://docs.cogniagent.ai/features/sharing-agents.md#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](https://docs.cogniagent.ai/features/environments.md#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](https://docs.cogniagent.ai/api/stores.md#environments) and the [MCP tools](https://docs.cogniagent.ai/mcp-server.md#manage-an-agents-data-stores) 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](#environments). Production can hold the real account and **Demo** a demo account, and the same steps use whichever one the agent runs in.

> [!NOTE]
>
> 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](#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](https://docs.cogniagent.ai/api/stores.md#connection-variables) a person made, or over [MCP](https://docs.cogniagent.ai/mcp-server.md#manage-an-agents-data-stores) 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.

An integration whose variable has no usable account shows it in red in the list.

The step then shows a chip with the variable's name and the account under it. Click **Use an account instead** to go back to an account of its own.

A step uses one source: the variable or an account of its own. The variable wins when both are set. A variable of another app, or one the agent doesn't have, is refused when you save the step.

You can't delete a Connection variable while something uses it. You can rename it, and everything that uses it follows.

### 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".

The list shows the variable under the integration, with the account it holds in the current environment. A line in red says what is wrong:

| Line | Meaning |
| - | - |
| No account in Demo | The variable is empty in this environment. |
| No longer available: the account | The account is switched off, signed out or gone. |
| This variable is for HubSpot, not Gmail. | The variable belongs to another app. |
| This variable does not exist any more | The variable was deleted. |

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](https://docs.cogniagent.ai/features/ways-in.md), such as Gmail, Slack or Telegram. This includes the channel settings drawer of a conversation flow and the channels of a coworker.

A trigger or a channel listens with the account the variable holds in the agent's current environment, never another account. In Demo it listens with the Demo account.

When you [switch the environment](https://docs.cogniagent.ai/features/environments.md#switch-the-environment), the agent is stopped first. When it starts again, its channels and triggers listen with the new environment's account. If you change the variable's account while the agent runs, the channels and triggers that use it move to the new account right away.

A variable that is empty in the current environment, or whose account is switched off or signed out, keeps that channel or trigger off. **Start** lists it, for example "The Gmail account for this channel is not set in Demo." Only an empty variable refuses Start. A switched-off or signed-out account is listed but does not refuse it. The Start dialog offers no **Leave empty** for a Connection variable: pick an account for it.

### 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](https://docs.cogniagent.ai/features/integrations.md#what-uses-an-account).

### 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](mailto: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**.

**Pick an account** opens the variable in the right environment. Channels and triggers that use it stay off, and **Start** lists them.

### 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.

| Case | Message |
| - | - |
| No account in this environment | The Connection variable Business › CRM account has no account in Demo. |
| The account is gone, switched off or signed out | The Connection variable Business › CRM account holds an account that is no longer available. Pick another account for it in Demo. |

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](#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](https://docs.cogniagent.ai/features/sharing-agents.md#what-a-copy-takes).

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

> [card] [Update Agent Variable step](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md)
>
> Change a variable from a workflow.

> [card] [HTTP Request](https://docs.cogniagent.ai/nodes/actions/http-request.md)
>
> Send a secret to an outside service.

> [card] [Agent data API](https://docs.cogniagent.ai/api/stores.md)
>
> Read and change variables from your own app.

> [card] [Data stores](https://docs.cogniagent.ai/features/data-stores.md)
>
> The other kinds of store.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.