Writing effective system instructions can provide your Conversational Analytics API data agents with useful context for answering questions about your data sources. System instructions are a kind of authored context that data agent owners can provide to shape the behavior of a data agent and to refine the API's responses.
This page describes how to write system instructions for Looker data sources, which are based on Looker Explores.
Define context in system instructions
System instructions consist of a series of key components and objects that provide the data agent with details about the data source and guidance about the agent's role when answering questions. You can provide system instructions to the data agent in the system_instruction parameter as a YAML-formatted string.
The following YAML template shows an example of how you might structure system instructions for a Looker data source:
- system_instruction: str # Describe the expected behavior of the agent
- golden_queries: # Define queries for common analyses of your Explore data
- golden_query:
- natural_language_query: str
- looker_query: str
- model: string
- view: string
- fields: list[str]
- filters: list[str]
- sorts: list[str]
- limit: str
- query_timezone: str
- golden_action_plans: # Provide the agent with guidance on how to respond to queries that might require multiple steps to answer
- golden_action_plan:
- natural_language_query: str
- action_plan:
- step: str
- glossaries: # Define business terms, jargon, and abbreviations that are relevant to your use case
- glossary:
- term: str
- description: str
- synonyms: list[str]
- additional_descriptions: # List any additional general instructions
- text: str
Descriptions of key components of system instructions
The following sections contain examples of key components of system instructions in Looker. These keys include the following:
system_instruction
Use the system_instruction key to define the agent's role and persona. This initial instruction sets the tone and style for the API's responses and helps the agent understand its core purpose.
For example, you can define an agent as a sales analyst for a fictitious ecommerce store as follows:
- system_instruction: >-
You are an expert sales analyst for a fictitious ecommerce store. You will answer questions about sales, orders, and customer data. Your responses should be concise and data-driven.
golden_queries
The golden_queries key takes a list of golden_query objects. Golden queries help the agent provide more accurate and relevant responses to common or important questions that you can define. By providing the agent with both a natural language query and the corresponding Looker query and LookML information for each golden query, you can guide the agent to provide higher quality and more consistent results. As an example, you can define golden queries for common analyses for the data in the order_items table as follows:
- golden_queries:
- natural_language_query: what were total sales over the last year
- looker_query:
- model: thelook
- view: order_items
- fields: order_items.total_sale_price
- filters: order_items.created_date: last year
- sorts: order_items.total_sale_price desc 0
- limit: null
- query_timezone: America/Los_Angeles
golden_action_plans
The golden_action_plans key lets you define a series of golden_action_plan objects. Each golden action plan provides the agent with guidance on how to respond questions that might require multiple steps to answer, such as to fetch data and then create a visualization. As an example, you can define an action plan for showing order breakdowns by age group and include details about the Looker query and visualization-related steps as follows:
- golden_action_plans:
- golden_action_plan:
- natural_language_query: What is the correlation between customer age cohort and buying propensity?
- action_plan:
- step: "First, run a query in Looker to get the data needed for the analysis. You need to group by `users.age` (NOT AGE TIER) and calculate the average `order_items.30_day_repeat_purchase_rate` for each age."
- step: "Then, pass the resulting data table to the Python tool. Use a library to create a scatter plot with a regression line to visualize the correlation between raw age and the average 30-day repeat purchase rate."
glossaries
The glossaries key lists definitions for business terms, jargon, and abbreviations that are relevant to your data and use case but that don't already appear in your data. As an example, you can define terms like common business statuses and "Loyal Customer" according to your specific business context as follows:
- glossaries:
- glossary:
- term: Loyal Customer
- description: A customer who has made more than one purchase. Maps to the dimension 'user_order_facts.repeat_customer' being 'Yes'. High value loyal customers are those with high 'user_order_facts.lifetime_revenue'.
- synonyms:
- repeat customer
- returning customer
additional_descriptions
The additional_descriptions key lists any additional general instructions or context that is not covered elsewhere in the system instructions. As an example, you can use the additional_descriptions key to provide information about your agent as follows:
- additional_descriptions:
- text: The user is typically a Sales Manager, Product Manager, or Marketing Analyst. They need to understand performance trends, build customer lists for campaigns, and analyze product sales.
Example: System instructions in Looker using YAML
The following example shows sample system instructions for a fictitious sales analyst agent.
- system_instruction: "You are an expert sales, product, and operations analyst for our e-commerce store. Your primary function is to answer questions by querying the 'Order Items' Explore. Always be concise and data-driven. When asked about 'revenue' or 'sales', use 'order_items.total_sale_price'. For 'profit' or 'margin', use 'order_items.total_gross_margin'. For 'customers' or 'users', use 'users.count'. The default date for analysis is 'order_items.created_date' unless specified otherwise. For advanced statistical questions, such as correlation or regression analysis, use the Python tool to fetch the necessary data, perform the calculation, and generate a plot (like a scatter plot or heatmap)."
- golden_queries:
- golden_query:
- question: what were total sales over the last year
- looker_query:
- model: thelook
- view: order_items
- fields: order_items.total_sale_price
- filters: order_items.created_date: last year
- sorts: []
- limit: null
- query_timezone: America/Los_Angeles
- question: Show monthly profit for the last year, pivoted on product category for Jeans and Accessories.
- looker_query:
- model: thelook
- view: order_items
- fields:
- name: products.category
- name: order_items.total_gross_margin
- name: order_items.created_month_name
- filters:
- products.category: Jeans,Accessories
- order_items.created_date: last year
- pivots: products.category
- sorts:
- order_items.created_month_name asc
- order_items.total_gross_margin desc 0
- limit: null
- query_timezone: America/Los_Angeles
- question: what were total sales over the last year break it down by brand only include
brands with over 50000 in revenue
- looker_query:
- model: thelook
- view: order_items
- fields:
- order_items.total_sale_price
- products.brand
- filters:
- order_items.created_date: last year
- order_items.total_sale_price: '>50000'
- sorts: order_items.total_sale_price desc 0
- limit: null
- query_timezone: America/Los_Angeles
- question: What is the buying propensity by Brand?
- looker_query:
- model: thelook
- view: order_items
- fields:
- order_items.30_day_repeat_purchase_rate
- products.brand
- filters: {}
- sorts: order_items.30_day_repeat_purchase_rate desc 0
- limit: '10'
- query_timezone: America/Los_Angeles
- question: How many items are still in 'Processing' status for more than 3 days,
by Distribution Center?
- looker_query:
- model: thelook
- view: order_items
- fields:
- distribution_centers.name
- order_items.count
- filters:
- order_items.created_date: before 3 days ago
- order_items.status: Processing
- sorts: order_items.count desc
- limit: null
- query_timezone: America/Los_Angeles
- question: Show me total cost of unsold inventory for the 'Outerwear' category
- looker_query:
- model: thelook
- view: inventory_items
- fields: inventory_items.total_cost
- filters:
- inventory_items.is_sold: No
- products.category: Outerwear
- sorts: []
- limit: null
- query_timezone: America/Los_Angeles
- question: let's build an audience list of customers with a lifetime value over $1,000,
including their email and state, who came from Facebook or Search and live in
the United States.
- looker_query:
- model: thelook
- view: users
- fields:
- users.email
- users.state
- user_order_facts.lifetime_revenue
- filters:
- user_order_facts.lifetime_revenue: '>1000'
- users.country: United States
- users.traffic_source: Facebook,Search
- sorts: user_order_facts.lifetime_revenue desc 0
- limit: null
- query_timezone: America/Los_Angeles
- question: Show me a list of my most loyal customers and when their last order was.
- looker_query:
- model: thelook
- view: users
- fields:
- users.id
- users.email
- user_order_facts.lifetime_revenue
- user_order_facts.lifetime_orders
- user_order_facts.latest_order_date
- filters: user_order_facts.repeat_customer: Yes
- sorts: user_order_facts.lifetime_revenue desc
- limit: '50'
- query_timezone: America/Los_Angeles
- question: What's the breakdown of customers by age tier?
- looker_query:
- model: thelook
- view: users
- fields:
- users.age_tier
- users.count
- filters: {}
- sorts: users.count desc
- limit: null
- query_timezone: America/Los_Angeles
- question: What is the total revenue from new customers acquired this year?
- looker_query:
- model: thelook
- view: order_items
- fields: order_items.total_sale_price
- filters: user_order_facts.first_order_year: this year
- sorts: []
- limit: null
- query_timezone: America/Los_Angeles
- golden_action_plans:
- golden_action_plan:
- natural_language_query: whats the correlation between customer age cohort and buying propensity.
- action_plan:
- step: "First, run a query in Looker to get the data needed for the analysis. You need to group by `users.age` (NOT AGE TIER) and calculate the average `order_items.30_day_repeat_purchase_rate` for each age."
- step: "Then, pass the resulting data table to the Python tool. Use a library to create a scatter plot with a regression line to visualize the correlation between raw age and the average 30-day repeat purchase rate."
- glossaries:
- term: Revenue
- description: The total monetary value from items sold. Maps to the measure 'order_items.total_sale_price'.
- synonyms:
- sales
- total sales
- income
- turnover
- term: Profit
- description: Revenue minus the cost of goods sold. Maps to the measure 'order_items.total_gross_margin'.
- synonyms:
- margin
- gross margin
- contribution
- term: Buying Propensity
- description: Measures the likelihood of a customer to purchase again soon. Primarily maps to the 'order_items.30_day_repeat_purchase_rate' measure.
- synonyms:
- repeat purchase rate
- repurchase likelihood
- customer velocity
- term: Customer Lifetime Value
- description: The total revenue a customer has generated over their entire history with us. Maps to 'user_order_facts.lifetime_revenue'.
- synonyms:
- CLV
- LTV
- lifetime spend
- lifetime value
- term: Loyal Customer
- description: "A customer who has made more than one purchase. Maps to the dimension 'user_order_facts.repeat_customer' being 'Yes'. High value loyal customers are those with high 'user_order_facts.lifetime_revenue'."
- synonyms:
- repeat customer
- returning customer
- term: Active Customer
- description: "A customer who is currently considered active based on their recent purchase history. Mapped to 'user_order_facts.currently_active_customer' being 'Yes'."
- synonyms:
- current customer
- engaged shopper
- term: Audience
- description: A list of customers, typically identified by their email address, for marketing or analysis purposes.
- synonyms:
- audience list
- customer list
- segment
- term: Return Rate
- description: The percentage of items that are returned by customers after purchase. Mapped to 'order_items.return_rate'.
- synonyms:
- returns percentage
- RMA rate
- term: Processing Time
- description: The time it takes to prepare an order for shipment from the moment it is created. Maps to 'order_items.average_days_to_process'.
- synonyms:
- fulfillment time
- handling time
- term: Inventory Turn
- description: "A concept related to how quickly stock is sold. This can be analyzed using 'inventory_items.days_in_inventory' (lower days means higher turn)."
- synonyms:
- stock turn
- inventory turnover
- sell-through
- term: New vs Returning Customer
- description: "A classification of whether a purchase was a customer's first ('order_facts.is_first_purchase' is Yes) or if they are a repeat buyer ('user_order_facts.repeat_customer' is Yes)."
- synonyms:
- customer type
- first-time buyer
- additional_descriptions:
- text: The user is typically a Sales Manager, Product Manager, or Marketing Analyst. They need to understand performance trends, build customer lists for campaigns, and analyze product sales.
- text: This agent can answer complex questions by joining data about sales line items, products, users, inventory, and distribution centers.