# Agent Variables

Variables are powerful placeholders that allow your Agents to access dynamic data, configuration settings, and secrets. Instead of hardcoding values, you references variables that are resolved at runtime.

## Why Use Variables?

* **Security**: Securely manage sensitive information like API keys using **Secret** variables.
* **Reusability**: Define a value once (like a brand tone or project ID) and reuse it across multiple agents.
* **Context**: Automatically access runtime information like the current user ID, time, or conversation details.

***

## Variable Scopes

For Agents, variables are organized into two primary scopes:

### 1. Project Variables (Global)

* **Access**: Available to **all agents** and workflows within the project.
* **Use Case**: Shared resources like database credentials, global API keys, or company-wide settings.
* **Syntax**: `{{ var.project.variable_name }}`

### 2. Agent Variables (Local)

* **Access**: Available **only to this specific agent**.
* **Use Case**: Agent-specific configuration, personality settings, or tools configurations unique to this agent.
* **Syntax**: `{{ var.agent.variable_name }}`

***

## System Variables (Automatic)

System variables are read-only values automatically populated by AgenticFlow every time an agent runs or replies. They provide essential context about the execution environment.

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

| Variable           | Description                                     | Example                     |
| ------------------ | ----------------------------------------------- | --------------------------- |
| `sys.user_id`      | ID of the user interacting with the agent       | `usr_8x92...`               |
| `sys.agent_id`     | ID of the current agent                         | `agent_abc123...`           |
| `sys.thread_id`    | ID of the current conversation thread           | `thread_xyz789...`          |
| `sys.agent_run_id` | Unique ID for the current execution             | `run_def456...`             |
| `sys.project_id`   | ID of the current project                       | `proj_ab12...`              |
| `sys.triggered_by` | Source of the interaction (user, API, schedule) | `user`                      |
| `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`                  |

***

## Configuring Variables

You can manage variables in the **Configuration** tab of your Agent editor.

### Data Types

* **String**: Text content.
* **Number**: Decimal values (e.g., `0.95`).
* **Integer**: Whole numbers (e.g., `42`).
* **Boolean**: True/False flags.

### Security & Constraints

* **Secret**: Encrypts the value and masks it in all logs/UI. **Essential for API keys.**
* **Read-only**: Ensures the variable cannot be modified during runtime.
* **Required**: Prevents the agent from running if the variable is empty.

***

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

<figure><img src="https://487764224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ3ppnJjAH1qBNXEYnDPA%2Fuploads%2FwpDoWbeBQKOhGv8XEJGk%2Fimage.png?alt=media&#x26;token=c51d50a6-9af0-4b66-8d60-f3d23299acad" alt=""><figcaption></figcaption></figure>

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

### 1. System Prompt

Personalize the agent's behavior based on context.

```
You are an assistant for Project {{ var.project.project_name }}.
Today is {{ sys.date }}.
Please address the user as {{ sys.user_id }}.
```

### 2. Tool Arguments

Pass secure credentials or dynamic values to tools without exposing them.

```json
{
  "api_key": "{{ var.project.openai_api_key }}",
  "user_context": "{{ var.agent.user_preference }}"
}
```

### 3. Knowledge Retrieval

Filter knowledge base queries based on dynamic variables.