Best Practices

Follow these guidelines to build effective, efficient agents that deliver accurate insights while managing costs.

Model Selection

Choosing the Right Model

Different models excel at different tasks:

Model Type	Best For	Cost	Speed
GPT-4	Complex reasoning, detailed analysis	High	Slower
GPT-4o	Balanced performance, general use	Medium	Medium
GPT-4o-mini	Simple queries, high volume	Low	Fast
Claude 3.5 Sonnet	Code generation, structured data	Medium	Medium
Claude 3 Haiku	Quick answers, basic queries	Low	Fast

Use Case Guidelines

Complex Analysis → GPT-4 or Claude 3.5 Sonnet

Multi-step reasoning required
Deep data analysis
Code generation needs

General Use → GPT-4o or Claude 3.5 Sonnet

Balanced performance
Most common questions
Good for production agents

High Volume → GPT-4o-mini or Claude 3 Haiku

Simple queries
Cost-sensitive applications
Fast response times needed

Start with a mid-tier model (GPT-4o or Claude 3.5 Sonnet) and adjust based on actual usage patterns.

Model Parameters

Settings beyond the model itself go in Advanced parameters on the agent’s Model tab. Enter a JSON object. It is passed to the provider’s chat client as keyword arguments, so use the argument names of that client:

{
  "reasoning": { "effort": "high" }
}

Parameters are provider-specific. The Model tab offers ready-made examples for each provider, such as OpenAI reasoning effort, Anthropic extended thinking, and Gemini thinking budget.

Sampling settings such as temperature and max_tokens can be set the same way, for models that accept them. For data analysis agents, a low temperature (0.2 to 0.5) gives more reliable answers.
Reasoning models reject sampling settings such as temperature. For these models, use reasoning settings instead.
Connection and credential settings such as API keys, base URLs, and model names are not allowed. A parameter the provider client rejects fails the save with an error.

Since 1.7.1, temperature, max tokens, top P, and penalty fields no longer exist on agents. Values saved on existing agents are no longer applied. Enter the ones you still need under Advanced parameters.

Data Source Optimization

Use Views Instead of Datasets

Why Views Are Better:

✅ Faster query execution
✅ Pre-filtered, relevant data only
✅ Better security (control data access)
✅ Lower token usage
✅ More accurate agent responses

Example:

Instead of: Full "orders" dataset (millions of rows)
Create: "recent_orders" view (last 90 days, key columns)

The agent queries faster and gets relevant data immediately.

Always use Views instead of raw datasets for better performance and cost efficiency.

Limit Data Sources

Only grant access to necessary datasets/views: Too Broad:

Sales data
HR data
Marketing data
Finance data

Focused:

Sales summary view
Revenue trends view

Fewer sources = faster decisions + lower costs.

Optimize View Definitions

Create views with:

Only necessary columns
Pre-aggregated data where possible
Relevant date ranges
Indexed fields

Agent Instructions

Write Clear System Prompts

Good Instructions:

You are a sales analytics expert. Help users analyze:
- Revenue trends and forecasting
- Customer behavior and segmentation
- Product performance metrics

Always provide specific numbers and dates. When showing
trends, create visualizations. Be concise and actionable.

Poor Instructions:

You are helpful. Answer questions about data.

Define Scope

Tell the agent:

What data it has access to
What questions it should handle
What format responses should take
Any business rules to follow

Include Examples

Provide specific examples in instructions:

When asked about "top customers," show:
1. Customer name
2. Total revenue
3. Number of orders
4. Comparison to average

Example format:
"Top 5 customers by revenue:
1. Acme Corp - $150K (45 orders) - 3x average
..."

Cost Optimization

Control Token Usage

Input Tokens:

Keep system instructions concise
Limit conversation history length
Use focused data sources

Output Tokens:

Set an appropriate max_tokens in Advanced parameters
Request concise answers when possible
Avoid asking for repeated information

Monitor Spending

Review token usage per conversation
Track costs by agent
Set up alerts for high usage
Regularly audit agent performance

Batch Similar Questions

If running automated analysis:

Group related queries
Reuse context where possible
Cache frequently accessed data

Agent Configuration

Tool Selection

Enable only what you need: Optional Tools:

Chart Generator - For data visualizations (recommended for most agents)
Python Executor - For complex calculations and advanced analytics
Web Search - For external context and current information

Query Executor is enabled by default and cannot be disabled.

Data Access Control

Grant minimum necessary access
Use views to restrict data
Separate agents by use case
Review permissions regularly

Regular Maintenance

Update instructions based on user feedback
Refine data sources as needs change
Adjust model selection for cost/performance
Archive unused agents

Query Performance

Faster Queries

Use Views - Pre-filtered, optimized data
Limit Result Sets - Ask for “top 10” not “all”
Specific Time Ranges - “last month” not “all time”
Indexed Columns - Ensure views use indexed fields

Example Optimizations

Slow: “Show all customer transactions” Fast: “Show top 20 customers by revenue this quarter”

Testing & Validation

Test Common Questions

Before deploying:

Ask typical user questions
Verify data accuracy
Check tool usage patterns
Measure response times

Validate Answers

Compare agent responses to known results
Verify calculations manually
Check chart accuracy
Test edge cases

Iterate

Gather user feedback
Refine instructions
Adjust parameters
Optimize data sources

Security

Data Access

Only grant necessary permissions
Use views to limit sensitive data
Review agent access regularly
Audit query logs

Credentials

Secure model account API keys
Rotate credentials periodically
Monitor for unusual usage
Implement access controls

Get Started

Reference

Deployment

Tutorial

Best Practices

Best Practices

Model Selection

Choosing the Right Model

Use Case Guidelines

Model Parameters

Data Source Optimization

Use Views Instead of Datasets

Limit Data Sources

Optimize View Definitions

Agent Instructions

Write Clear System Prompts

Define Scope

Include Examples

Cost Optimization

Control Token Usage

Monitor Spending

Batch Similar Questions

Agent Configuration

Tool Selection

Data Access Control

Regular Maintenance

Query Performance

Faster Queries

Example Optimizations

Testing & Validation

Test Common Questions

Validate Answers

Iterate

Security

Data Access

Credentials

Next Steps

​Best Practices

​Model Selection

​Choosing the Right Model

​Use Case Guidelines

​Model Parameters

​Data Source Optimization

​Use Views Instead of Datasets

​Limit Data Sources

​Optimize View Definitions

​Agent Instructions

​Write Clear System Prompts

​Define Scope

​Include Examples

​Cost Optimization

​Control Token Usage

​Monitor Spending

​Batch Similar Questions

​Agent Configuration

​Tool Selection

​Data Access Control

​Regular Maintenance

​Query Performance

​Faster Queries

​Example Optimizations

​Testing & Validation

​Test Common Questions

​Validate Answers

​Iterate

​Security

​Data Access

​Credentials

​Next Steps

Best Practices

Model Selection

Choosing the Right Model

Use Case Guidelines

Model Parameters

Data Source Optimization

Use Views Instead of Datasets

Limit Data Sources

Optimize View Definitions

Agent Instructions

Write Clear System Prompts

Define Scope

Include Examples

Cost Optimization

Control Token Usage

Monitor Spending

Batch Similar Questions

Agent Configuration

Tool Selection

Data Access Control

Regular Maintenance

Query Performance

Faster Queries

Example Optimizations

Testing & Validation

Test Common Questions

Validate Answers

Iterate

Security

Data Access

Credentials

Next Steps