Define data agent context for Looker data sources

Authored context is guidance that data agent owners can provide to shape the behavior of a data agent and to refine the API's responses. Effective authored context provides 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 . When you connect to Looker Explores, you provide authored context to data agents exclusively through system instructions.

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.

After you define the system instructions that make up your authored context, you can provide that context to the API in one of the following calls:

Creating a persistent data agent: Include authored context within the published_context object in the request body to configure agent behavior that persists across multiple conversations. For more information, see Create a data agent (HTTP) or Set up context for stateful or stateless chat (Python SDK).
Sending a stateless request: Provide authored context within the inline_context object in a chat request to define the agent's behavior for that specific API call. For more information, see Create a stateless multi-turn conversation (HTTP) or Send a stateless chat request with inline context (Python SDK).
Send a query data request: For database data sources, provide the context set ID of the authored context within the agent_context_reference object in the query data request. For more information about, see Define data agent context for database data sources .

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 
 - 
  
 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
golden_queries
glossaries
additional_descriptions

`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

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

Related resource

Guide agent behavior with authored context

Define data agent context for Looker data sources Stay organized with collections Save and categorize content based on your preferences.

Define context in system instructions

Descriptions of key components of system instructions

system_instruction

golden_queries

glossaries

additional_descriptions