# Custom Variables

Create reusable variables to personalize your AI agent prompts across interviews.

## What are Custom Variables?

Custom variables let you define placeholders like `{{company_background}}` or `{{research_focus}}` that can be filled in differently for each interview. This allows you to:

* **Reuse prompts** across different research projects
* **Customize interviews** without editing the agent prompt each time
* **Ensure consistency** with required fields that must be filled in
* **Provide defaults** for optional information

## System Variables vs Custom Variables

### System Variables (Built-in)

InsightAgent provides these variables automatically:

| Variable                        | Description               |
| ------------------------------- | ------------------------- |
| `{{expert_name}}`               | Expert's full name        |
| `{{client_name}}`               | Your organization name    |
| `{{questions_list}}`            | Interview questions       |
| `{{call_subject}}`              | Interview topic           |
| `{{compliance_disclaimer}}`     | Legal disclaimer          |
| `{{expert_current_role}}`       | Expert's current position |
| `{{expert_employment_history}}` | Expert's work history     |

### Custom Variables (Your Own)

Create your own variables for project-specific information:

| Example Variable         | Use Case                  |
| ------------------------ | ------------------------- |
| `{{company_background}}` | Target company context    |
| `{{research_focus}}`     | Specific research area    |
| `{{competitor_list}}`    | Competitors to explore    |
| `{{industry_context}}`   | Industry-specific details |

## Creating Variables

### Navigate to Settings

1. Go to **Settings** in the sidebar
2. Click **Variables**
3. Click **Add Variable**

### Define the Variable

| Field             | Description                                                      | Required |
| ----------------- | ---------------------------------------------------------------- | -------- |
| **Name**          | Variable key used in prompts (e.g., `company_background`)        | Yes      |
| **Display Name**  | Human-readable label shown in forms (e.g., "Company Background") | Yes      |
| **Description**   | Help text explaining what to enter                               | No       |
| **Required**      | Whether a value must be provided for each interview              | No       |
| **Default Value** | Fallback value if not specified                                  | No       |

### Variable Name Rules

Variable names must:

* Start with a letter (a-z, A-Z)
* Contain only letters, numbers, and underscores
* Be unique within your account

**Valid examples:** `company_name`, `targetMarket`, `research_focus_2024`

**Invalid examples:** `123name`, `has-hyphen`, `has spaces`

## Using Variables in Prompts

Reference variables in your agent prompts using double curly braces:

```
You are researching {{company_background}} for {{client_name}}.

Focus on understanding:
- Their position in {{industry_context}}
- Competition with {{competitor_list}}
- Specific areas: {{research_focus}}

QUESTIONS:
{{questions_list}}
```

## Required vs Optional Variables

### Required Variables

Mark a variable as **required** when every interview using that agent needs a value:

* Interviews cannot be created without providing a value
* The form shows a red asterisk (\*) next to required fields
* Save button is disabled until all required fields are filled

**Use for:** Critical context the AI needs to conduct the interview properly.

### Optional Variables

Leave a variable as **optional** when it's helpful but not essential:

* Interviews can be created without a value
* If no value is provided, the default value (if set) is used
* If no default exists, the variable is replaced with empty text

**Use for:** Additional context that enhances but isn't critical to the interview.

## Default Values

Set a default value for optional variables to ensure the prompt always has meaningful content:

```
Variable: industry_context
Default: "the technology industry"

Prompt: "...their position in {{industry_context}}..."

Result when no value provided: "...their position in the technology industry..."
Result when value is "healthcare": "...their position in healthcare..."
```

## Interview Workflow

### Creating an Interview

When creating an interview with an agent that uses custom variables:

1. Select the agent for your interview
2. A **Custom Variables** section appears with fields for each variable
3. Required fields are marked with a red asterisk (\*)
4. Default values are pre-filled (you can change them)
5. Fill in the values and save

### Editing an Interview

You can update variable values before the interview is conducted:

1. Open the interview detail page
2. Find the **Custom Variables** section
3. Click **Edit** to modify values
4. Click **Save** to apply changes

### Changing Agents

When changing an interview's agent to one with different variables:

1. Click **Change Agent** on the interview
2. A preview modal shows the new agent's variables
3. Fill in any required values
4. Confirm to apply the change

## Deleting Variables

Variables that are used by agent prompts cannot be deleted. To delete a variable:

1. Remove the `{{variable_name}}` reference from all agent prompts
2. Return to **Settings → Variables**
3. The **Delete** option becomes available

## Best Practices

### Naming Conventions

Use descriptive, consistent names:

```
// Good - clear and consistent
company_background
research_focus
target_industry

// Avoid - unclear or inconsistent
cb
researchFocus
INDUSTRY
```

### Required vs Optional

* Make variables **required** when the AI cannot perform well without them
* Make variables **optional** when they add context but aren't critical
* Always provide **default values** for optional variables when possible

### Organization

* Create variables at the account level so they can be reused across agents
* Use similar variable names across related agents for consistency
* Document variable purposes in the description field

### Prompt Writing

* Reference variables where they make sense contextually
* Don't overload prompts with too many variables
* Test prompts with different variable values to ensure they work well

## Troubleshooting

### "Missing required variables" error

This occurs when trying to save an interview without filling in all required variable values. Fill in all fields marked with (\*).

### Variable not being replaced

Check that:

1. The variable name in the prompt exactly matches the defined name
2. The syntax is correct: `{{variable_name}}` with double curly braces
3. The variable is linked to the agent version being used

### Can't delete a variable

The variable is still referenced in one or more agent prompts. The error message shows which agents use the variable. Remove the references first, then delete.


---

# 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.insightagent.io/product-guides/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.