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
Kind	Simple (a single value) or Conditional block (an optional prompt section) — see Conditional (Block) Variables below	No (defaults to Simple)
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 (Simple variables only)	No

Kind cannot be changed after a variable is created — like Name, it's fixed at creation time.

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..."

Conditional (Block) Variables

Every variable so far in this guide is a simple variable: a single value substituted directly into the prompt. A conditional (block) variable is different — instead of a value, it resolves to an entire optional section of the prompt, decided by whether the interview provided a value at all.

What a Block Variable Is

A block variable has no default value of its own. Instead, when you create it you author two prompt templates:

Template	Rendered when...
When filled	The interview provides a value for this variable
When blank	The interview leaves this variable empty

Both templates are written once, in Settings → Variables, by whoever configures the agent. This resolution happens server-side, before the prompt reaches the AI model — the model never sees a conditional or an empty placeholder, only the finished section that was chosen for that interview.

Referencing the Value

Inside the When filled template, insert whatever the interview creator entered by referencing it either way — both resolve to the same value:

• the special inner placeholder {{value}}, or
• the block variable's own name, e.g. {{preliminary_vetting_question}} for a variable named preliminary_vetting_question.

When filled:  Ask about {{value}} before moving to the main questions.
When blank:   Skip the preliminary question and go straight to the main questions.

If the interview provides "pricing objections" as the value, the prompt receives:

Ask about pricing objections before moving to the main questions.

If the value is left empty, the prompt receives the When blank text instead.

Resolution Rules

• Filled — the value is present and not just whitespace → the When filled template is used, with {{value}} (and the variable's own name) substituted.
• Blank — the value is missing, an empty string, or whitespace-only → the When blank fallback is used.
• Both a When filled and a When blank template are required when creating a block variable; there's no unconfigured state where a block variable resolves to nothing.

Interview Creators Still Just Fill In Data

From the interview creation/edit form, a block variable looks exactly like any other variable field — a single input the interview creator fills in or leaves blank. They are never asked to write or edit prompt text; the When filled/When blank templates are fixed by whoever set up the variable in Settings.

Limitation: No Nested Variables Inside a Block Template

Substitution inside a block template is a single pass that only resolves the value — via {{value}} or the block variable's own name. Do not reference other custom or system variables (e.g. {{expert_name}}, {{client_name}}) inside a When filled or When blank template — they will not be substituted and will appear literally in the prompt. Keep block templates self-contained; reference other variables elsewhere in the main prompt instead.

Example: Preliminary Vetting Question

A common use case is an optional screening question that should only be asked when a specific topic is supplied for that interview:

Variable: preliminary_vetting_question (kind: Conditional block)

When filled:  Before the main questions, ask the expert about their experience with
              {{value}}. If they have no relevant experience, thank them and end
              the call early.
When blank:   Skip the preliminary vetting step and go directly to the main
              interview questions.

• An interview created with the value "enterprise procurement software" asks the vetting question about that topic before continuing.
• An interview left with that field blank skips straight to the main questions — no leftover "ask about ___" text and no visible conditional logic in the prompt.

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.