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 the {{ }} syntax in various parts of the Agent configuration:

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.

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

3. Knowledge Retrieval

Filter knowledge base queries based on dynamic variables.