System Prompts

System prompts define how your agent behaves and what context it has about your data and business.

SystemPromptBuilder Interface

Vanna uses a SystemPromptBuilder to generate the system prompt dynamically based on the current context:

from vanna.core.system_prompt import SystemPromptBuilder
from typing import List, Dict, Any

class SystemPromptBuilder(ABC):
    @abstractmethod
    async def build_system_prompt(
        self,
        user: User,
        tool_schemas: List[Dict[str, Any]],
        context: Dict[str, Any]
    ) -> str:
        """Build the system prompt for the LLM"""
        pass

Default System Prompt

Vanna includes a DefaultSystemPromptBuilder that provides sensible defaults:

from vanna.core.system_prompt import DefaultSystemPromptBuilder

agent = Agent(
    llm_service=llm,
    sql_runner=sql_runner,
    system_prompt_builder=DefaultSystemPromptBuilder()
)

The default prompt includes:

• Agent role and capabilities
• Available tools and their schemas
• Best practices for tool usage
• Database schema information (if available)
• User-specific context

Custom System Prompts

Create a custom prompt builder for your specific needs:

from vanna.core.system_prompt import SystemPromptBuilder
from vanna.core.user import User
from typing import List, Dict, Any

class CustomSystemPromptBuilder(SystemPromptBuilder):
    def __init__(self, company_name: str, domain: str):
        self.company_name = company_name
        self.domain = domain
    
    async def build_system_prompt(
        self,
        user: User,
        tool_schemas: List[Dict[str, Any]],
        context: Dict[str, Any]
    ) -> str:
        prompt = f"""You are a data analyst assistant for {self.company_name}.
        
Your role is to help users understand and analyze {self.domain} data.

## Guidelines

1. Always be helpful and professional
2. Explain your reasoning when writing SQL queries
3. Suggest visualizations when appropriate
4. If you're unsure, ask clarifying questions

## Available Tools

"""
        
        # Add tool documentation
        for tool in tool_schemas:
            prompt += f"\n### {tool['name']}\n"
            prompt += f"{tool['description']}\n"
            prompt += f"Parameters: {tool['parameters']}\n"
        
        # Add database-specific guidance
        if 'database_schema' in context:
            prompt += "\n## Database Schema\n"
            prompt += context['database_schema']
        
        # Add user-specific context
        prompt += f"\n## Current User\n"
        prompt += f"Name: {user.username}\n"
        prompt += f"Groups: {', '.join(user.group_memberships)}\n"
        
        return prompt

# Use your custom builder
agent = Agent(
    llm_service=llm,
    sql_runner=sql_runner,
    system_prompt_builder=CustomSystemPromptBuilder(
        company_name="Acme Corp",
        domain="e-commerce"
    )
)

Dynamic Prompts Based on User

Customize the prompt for different user types:

class RoleBasedSystemPromptBuilder(SystemPromptBuilder):
    async def build_system_prompt(
        self,
        user: User,
        tool_schemas: List[Dict[str, Any]],
        context: Dict[str, Any]
    ) -> str:
        base_prompt = "You are a helpful data assistant.\n\n"
        
        # Customize based on user role
        if 'admin' in user.group_memberships:
            base_prompt += """As an admin user, you have access to all data and tools.
Be thorough in your analysis and provide detailed explanations."""
        
        elif 'analyst' in user.group_memberships:
            base_prompt += """You're assisting a data analyst. Focus on:
- Writing efficient SQL queries
- Suggesting appropriate visualizations
- Highlighting data quality issues"""
        
        elif 'executive' in user.group_memberships:
            base_prompt += """You're assisting an executive. Focus on:
- High-level insights and trends
- Business impact
- Clear, concise summaries
- Avoid technical jargon"""
        
        else:
            base_prompt += "Provide clear, user-friendly responses."
        
        # Add tool schemas
        base_prompt += "\n## Available Tools\n"
        for tool in tool_schemas:
            base_prompt += f"- {tool['name']}: {tool['description']}\n"
        
        return base_prompt

Including Database Schema

Automatically include table and column information:

class SchemaAwarePromptBuilder(SystemPromptBuilder):
    def __init__(self, sql_runner):
        self.sql_runner = sql_runner
    
    async def build_system_prompt(
        self,
        user: User,
        tool_schemas: List[Dict[str, Any]],
        context: Dict[str, Any]
    ) -> str:
        prompt = "You are a SQL expert assistant.\n\n"
        
        # Fetch schema information
        try:
            schema_info = await self.sql_runner.get_schema_info()
            
            prompt += "## Database Schema\n\n"
            for table in schema_info['tables']:
                prompt += f"### {table['name']}\n"
                prompt += f"Columns:\n"
                for col in table['columns']:
                    prompt += f"  - {col['name']} ({col['type']})\n"
                prompt += "\n"
        
        except Exception as e:
            # Schema fetch failed, continue without it
            pass
        
        prompt += "## Tools\n"
        for tool in tool_schemas:
            prompt += f"- {tool['name']}\n"
        
        return prompt

Best Practices for System Prompts

1. Be Specific About Behavior

prompt = """You are a SQL query assistant.

IMPORTANT GUIDELINES:

- ALWAYS use table aliases in joins
- NEVER use SELECT *
- PREFER window functions over subqueries
- ALWAYS include LIMIT clauses for exploratory queries
- ASK for clarification if the request is ambiguous
"""

2. Provide Examples

prompt += """
## Example Interactions

User: "Show me top customers"
Assistant: I'll query the customers table and order by total_purchases.
[calls run_sql with appropriate query]

User: "Visualize that"
Assistant: [calls visualize_data on the results file]
"""

3. Define Data Semantics

prompt += """
## Business Definitions

- Customer: A user who has made at least one purchase
- Active Customer: Purchased within last 90 days
- Revenue: Sum of order_total excluding refunds
- MRR: Sum of subscription amounts for active subscriptions
"""

4. Set Tone and Style

prompt += """
## Communication Style

- Be concise and professional
- Use bullet points for lists
- Highlight key insights in bold
- Explain technical concepts in simple terms
- End responses with a question if next steps aren't clear
"""

Testing System Prompts

Test your prompts with different scenarios:

# Test prompt generation
builder = CustomSystemPromptBuilder("Acme", "sales")

admin_user = User(id="1", username="admin", group_memberships=["admin"])
regular_user = User(id="2", username="user", group_memberships=["user"])

admin_prompt = await builder.build_system_prompt(
    admin_user,
    tool_schemas,
    context={}
)

user_prompt = await builder.build_system_prompt(
    regular_user,
    tool_schemas,
    context={}
)

print("Admin prompt:", admin_prompt)
print("User prompt:", user_prompt)

Prompt Versioning

Track system prompt versions for consistency:

class VersionedPromptBuilder(SystemPromptBuilder):
    VERSION = "2.1.0"
    
    async def build_system_prompt(self, user, tool_schemas, context):
        prompt = f"[System Prompt v{self.VERSION}]\n\n"
        # ... rest of prompt
        return prompt

See Also

• Agent Configuration
• Custom Tools
• Tool Memory
• Lifecycle Hooks