Variables and Variable Sets

View as Markdown

Variables make Agents reusable. Instead of hard-coding a client, date range, report period, folder, or threshold into every step, define the value once and reference it where the Agent needs it.

Variable sets are saved groups of values. They make recurring runs and schedules easier to operate because the same Agent can run with different approved inputs.

When to Use Variables

Use variables for values that change between runs, such as:

reporting period
client or project name
target audience
review threshold
source folder or Site scope
output title
webhook payload value
sub-agent input

Avoid variables for instructions that should stay fixed. If a value expresses policy, source boundaries, evidence expectations, or quality requirements, put it in the Agent definition instead.

Define Good Variables

Good variables are specific, named clearly, and easy to validate.

Examples:

Better	Avoid
`reportingPeriod`	`date`
`clientName`	`name`
`minimumRiskScore`	`score`
`outputAudience`	`type`

Use descriptions to explain how the value is used. For required variables, make the expected format clear.

Use Variables in Steps

Variables can be referenced in prompts, output instructions, webhook payloads, sub-agent mappings, and generated file instructions.

Common patterns include:

Prepare a lender update for {{clientName}} covering {{reportingPeriod}}.

Only include findings with a risk score greater than {{minimumRiskScore}}.

Before running an Agent, confirm all required variables have values. Missing or ambiguous variables make Agent outputs harder to review and can cause trigger or schedule failures.

Variable Sets

Variable sets save reusable values for an Agent. They are especially useful when:

the same Agent runs for multiple clients
a scheduled Agent needs different values on different schedules
operators need approved presets instead of ad hoc values
repeated runs should use consistent labels, thresholds, or folders

Examples:

Monthly Finance Pack - East Region
Board Report - Q2
Client Escalation Summary - Enterprise Accounts

Keep variable set names operational. A person reviewing a schedule should understand what values the preset represents.

Variables and Schedules

Schedules can use variable sets so recurring runs stay consistent. When creating or editing a schedule:

Choose the Agent.
Select the schedule cadence.
Select the relevant Sites or source scope.
Select a variable set or provide the required values.
Decide whether to notify on completion.
Save and review the next run time.

Use separate schedules when different clients, Sites, or reporting periods require different variable values.

Variables and Triggers

Webhook, upload, and sub-agent triggers can map incoming payload values to Agent variables.

For example, a webhook payload might provide:

{
  "customer": {
    "name": "Northwind Partners"
  },
  "period": "2026-Q2",
  "priority": "high"
}

The trigger mapping can assign:

Payload key	Agent variable
`customer.name`	`clientName`
`period`	`reportingPeriod`
`priority`	`priorityLevel`

Use Trigger Mapping for detailed setup guidance.

Best Practices

Keep variable names stable once an Agent is in production.
Prefer clear names over short names.
Use variable sets for repeatable run patterns.
Keep sensitive values out of prompts unless the Agent truly needs them.
Do not use variables to weaken policy, source scope, or evidence requirements.
Test every variable set before attaching it to a production schedule.
Update schedules when variables are renamed or removed.