Understand workflow variables

Workflow variables let actions share data during an agentic workflow run.

For example, a workflow might collect an employee's details, use an Agent to confirm what they need, create a request with a tool, and then use that request ID in a later message. Each action can use data produced earlier in the run.

Where workflow data comes from

Workflow data generally comes from four sources:

Workflow inputs

Workflow inputs are created by the Start action. What they contain depends on how Start is configured.

They can include:

• Answers the employee gives when the workflow starts
• Profile information from the signed-in person
• Data from the event that started the workflow

For example, a workflow might start with an employee ID and request type.

$.inputs.employeeId
$.inputs.requestType

The inputs available to you depend on how the Start action is configured.

Action outputs

Many actions produce data that later actions can use. Typical sources include Agent, Run Tool, Transform, and Wait when it is waiting for an event.

For example:

$.TimeOffAssistantAgent.startDate
$.CreateRequest.requestId

The path comes from the action that produced the output.

• An Agent name is converted to PascalCase and gets an Agent suffix unless the name already contains "agent." An Agent named Time Off Assistant produces $.TimeOffAssistantAgent.
• A Run Tool path is based on the selected tool name. A tool named Create Request produces $.CreateRequest.

If two actions would produce the same identifier, each gets a number suffix.

An output is available only after its action has run and only when a valid path connects the producing action to the action you're configuring.

If a value is missing from @, check that the action producing it is connected and runs before the action you're editing.

State variables

Use Set State when you need to keep a value and reuse it later.

For example:

$requestNumber
$managerId

State variables keep their $name form. They aren't written as $.requestNumber.

• Use Set State when you want to retain a value for later in the workflow.
• Use Transform when you need to reshape or calculate a value and continue with the result. The result is stored under the Transform's output name.

List items

When you use Process List, the workflow runs the same child actions for each item in a list.

Inside those child actions, the current item is:

$.item
$.item.email

These paths are available only while that Process List is running.

Find a variable with @

When a field accepts workflow data, press @ to open the picker. Choose the value instead of typing its path.

What @ inserts depends on the field:

• In a workflow expression field, it inserts the path, such as $.inputs.employeeId.
• In Agent instructions, it inserts a path token, such as {{$.inputs.employeeId}}.

Start with @ whenever you need to pass an existing value to another action.

When a later action can use a value

A value must exist before a later action can use it.

A typical sequence is:

1. Start provides workflow inputs.
2. An Agent or Run Tool produces outputs.
3. Set State or Transform saves a value you want to reuse.
4. A later action selects that value with @.

You can't use an action's output before that action has run.

When a variable isn't enough

Selecting a variable gives you the value as it exists in the workflow.

Use an expression when you need to do more with that value, such as:

• Combine text
• Calculate a value
• Compare values
• Check whether a value exists
• Filter data
• Reshape data

For example, to combine a first and last name:

$.inputs.firstName & ' ' & $.inputs.lastName

Text values in expressions must be enclosed in quotes. In this example, ' ' adds a space between the two names.