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.