# 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="/files/odOetL3fLzxm9aEGDV2J" 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.


---

# 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/ai-agents/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.