---
title: Variables and Variable Sets
description: >-
  Define Agent variables, reuse variable sets, map trigger payloads, and keep
  scheduled or repeatable Agent runs consistent.
ogTitle: Agent Variables and Variable Sets
ogDescription: >-
  Learn how Clear Ideas Agent variables and variable sets support repeatable
  runs, schedules, webhooks, upload triggers, and sub-agent calls.
ogImage: /assets/images/og/agents-variables-and-variable-sets.webp
navigation:
  icon: fasl fa-brackets-curly
---

# Variables and Variable Sets

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:

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

```text
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:

1. Choose the Agent.
2. Select the schedule cadence.
3. Select the relevant Sites or source scope.
4. Select a variable set or provide the required values.
5. Decide whether to notify on completion.
6. 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:

```json
{
  "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](/agents/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.

## Related Documentation

- [Agent Editor and Step Types](/agents/agent-editor-and-step-types)
- [Trigger Mapping](/agents/trigger-mapping)
- [Schedules](/agents/schedules)
- [Triggers and Webhooks](/agents/triggers-and-webhooks)
- [Agent Runs](/agents/runs)