# Variables

Variables serve as secure, reusable containers for values across your automation ecosystem. Instead of hardcoding API keys, configuration settings, or email addresses into every single step, you can define them once as **Variables** and reference them anywhere.

## Why Use Variables?

* **Centralized Control**: Update an API key or setting in one place, and it instantly updates across all your workflows and agents.
* **Security**: Use **Secret Variables** to encrypt sensitive data (like passwords and API tokens). These values are masked in logs and never exposed in the UI.
* **Portability**: Build workflows that act differently based on the environment or team without changing the workflow structure.

***

## Variable Scopes

Where you define a variable determines where it can be used. AgenticFlow offers four levels of scoping:

### 1. Project Variables (Global)

* **Access**: Available to **everything** in the project (all Workflows, Agents, and Workforces).
* **Best For**: Global API keys (OpenAI, Stripe), database credentials, or company-wide settings (e.g., `brand_color`).
* **Syntax**: `{{ var.project.variable_name }}`

### 2. Workflow Variables

* **Access**: Available only within the specific **Workflow** where they are defined.
* **Best For**: Workflow-specific defaults (e.g., `default_retry_count`, `admin_email_recipient`).
* **Syntax**: `{{ var.workflow.variable_name }}`

### 3. Agent Variables

* **Access**: Available only to a specific **Agent**.
* **Best For**: Personality settings, agent-specific memory limits, or distinct tool credentials for that agent.
* **Syntax**: `{{ var.agent.variable_name }}`

### 4. Workforce Variables

* **Access**: Available to all agents within a specific **Workforce** (Multi-Agent Team).
* **Best For**: Shared goals, team-specific resources, or coordination parameters.
* **Syntax**: `{{ var.mas.variable_name }}`

***

Có 2 loại variable bao gồm:

* System Variables
* Creating & Configuring Variables

## System Variables (Read-Only)

AgenticFlow automatically provides "System Variables" for every execution. These are read-only values that give you context about "who, what, and when" the automation is running.

**Syntax**: `{{ sys.variable_name }}`

| Variable              | Description                                 | Example Output              |
| --------------------- | ------------------------------------------- | --------------------------- |
| `sys.user_id`         | ID of the user who triggered the run        | `usr_8x92...`               |
| `sys.project_id`      | ID of the current project                   | `proj_ab12...`              |
| `sys.workflow_id`     | ID of the current workflow                  | `wf_abc123...`              |
| `sys.workflow_run_id` | Unique ID for this specific execution       | `run_xyz789...`             |
| `sys.triggered_by`    | How the run started (manual, schedule, API) | `manual`                    |
| `sys.timestamp`       | Current Unix timestamp (seconds)            | `1705680123`                |
| `sys.datetime`        | Current ISO datetime                        | `2024-01-19T10:30:00+00:00` |
| `sys.date`            | Current date (YYYY-MM-DD)                   | `2024-01-19`                |
| `sys.time`            | Current time (HH:MM:SS)                     | `10:30:00`                  |

***

## Creating & Configuring Variables

When adding a new variable in the Settings panel, you will configure:

### Data Types

* **String**: Text values (e.g., "Welcome to AgenticFlow").
* **Number**: Decimal numbers (e.g., `0.75`).
* **Integer**: Whole numbers (e.g., `42`).
* **Boolean**: True/False usage flags.

### Special Properties

* **Secret**: **Crucial for security**. Checks this box to encrypt the value. It will be hidden from the UI after creation and masked in all execution logs.
* **Read-only**: Prevents the variable from being modified during runtime.
* **Required**: The workflow will refuse to start if this variable is empty.

<figure><img src="/files/YsZdlXIzlAyo5EmwrUEk" alt=""><figcaption></figcaption></figure>

***

## How to Use Variables

You can use variables in almost any input field in the AgenticFlow builder by typing `#` to reference a variable. A dropdown list will appear—scroll to the bottom to find the variables you’ve created.<br>

{% embed url="<https://www.loom.com/share/bdfb1ff61b5e4e0cafd75db2066922fd>" %}

If `#` doesn’t work in a specific field, try using the double curly brace syntax: `{{ }}`.

### Syntax Cheat Sheet

| Type          | Syntax                             |
| ------------- | ---------------------------------- |
| **Project**   | `{{ var.project.your_var_name }}`  |
| **Workflow**  | `{{ var.workflow.your_var_name }}` |
| **Agent**     | `{{ var.agent.your_var_name }}`    |
| **Workforce** | `{{ var.mas.your_var_name }}`      |
| **System**    | `{{ sys.your_sys_var }}`           |

### Common Examples

**1. Using a Secure API Key in a Header** Instead of pasting your key directly, reference the secret project variable:

```json
{
  "Authorization": "Bearer {{ var.project.openai_api_key }}"
}
```

**2. Dynamic File Naming** Create unique filenames automatically using system date and run IDs:

```
invoice_{{ sys.date }}_{{ sys.workflow_run_id }}.pdf
```

*Result: `invoice_2024-01-19_run_xyz789.pdf`*

**3. Conditional Logic** Use a Boolean variable to control workflow paths:

```
{{ var.workflow.is_debug_mode }} == true
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agenticflow.ai/workflows/variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.