作成されたコンテキストは、データ エージェントのオーナーがデータ エージェントの動作を形成し、API の回答を調整するために提供できるガイダンスです。効果的な作成済みコンテキストは、データソースに関する質問に回答するための有用なコンテキストを Conversational Analytics API データ エージェントに提供します。システム指示は、データ エージェントのオーナーがデータ エージェントの動作を形成し、API の回答を調整するために提供できる作成済みのコンテキストの一種です。
このページでは、Looker Explore に基づく Looker データソースのシステム指示を作成する方法について説明します。Looker Explore に接続する場合、システム指示を通じてのみ、データ エージェントに作成されたコンテキストを提供します。
システム指示でコンテキストを定義する
システム指示は、データ エージェントにデータソースの詳細と、質問に回答する際のエージェントの役割に関するガイダンスを提供する一連の主要コンポーネントとオブジェクトで構成されます。system_instruction パラメータで、YAML 形式の文字列としてデータ エージェントにシステム指示を指定できます。
作成したコンテキストを構成するシステム指示を定義したら、次のいずれかの呼び出しで API にコンテキストを指定できます。
- 永続データ エージェントの作成: リクエスト本文の
published_contextオブジェクト内に作成されたコンテキストを含めて、複数の会話にわたって持続するエージェントの動作を構成します。詳細については、データ エージェントを作成する（HTTP）またはステートフルまたはステートレス チャットのコンテキストを設定する（Python SDK）をご覧ください。 - ステートレス リクエストの送信: チャット リクエストの
inline_contextオブジェクト内で作成されたコンテキストを指定して、特定の API 呼び出しにおけるエージェントの動作を定義します。詳細については、ステートレス マルチターンの会話を作成する（HTTP）またはインライン コンテキストを含むステートレス チャット リクエストを送信する（Python SDK）をご覧ください。
次の YAML テンプレートは、Looker データソースのシステム指示を構成する方法の例を示しています。
- 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
システム指示の主な構成要素の説明
以降のセクションでは、Looker のシステム指示のキー コンポーネントの例を示します。これらのキーには、次のものがあります。
system_instruction
system_instruction キーを使用して、エージェントの役割とペルソナを定義します。この最初の指示は、API の回答のトーンとスタイルを設定し、エージェントがその主な目的を理解するのに役立ちます。
たとえば、次のように、架空の e コマースストアのセールス アナリストとしてエージェントを定義できます。
- 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
golden_queries キーには、golden_query オブジェクトのリストを指定します。ゴールデン クエリは、エージェントが一般的な質問や重要な質問に対して、より正確で関連性の高い回答を提供できるようにします。各ゴールデン クエリに対応する自然言語クエリと Looker クエリおよび LookML 情報の両方をエージェントに提供することで、エージェントがより高品質で一貫性のある結果を提供できるようにガイドできます。たとえば、order_items テーブルのデータの一般的な分析用に、次のようにゴールデン クエリを定義できます。
- 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
glossaries キーには、データとユースケースに関連するビジネス用語、専門用語、略語の定義のリストを記述します。これらの用語は、データにはまだ表示されていません。たとえば、特定のビジネス コンテキストに従って、一般的なビジネス ステータスや「Loyal Customer」などの用語を次のように定義できます。
- 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
additional_descriptions キーには、システム指示の他の部分で説明されていない追加の指示やコンテキストのリストを記述します。たとえば、additional_descriptions キーを使用して、エージェントに関する情報を次のように提供できます。
- 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.
例: YAML を使用した Looker のシステム指示
次の例は、架空のセールス アナリストとして定義したエージェントへのシステム指示のサンプルを示しています。
- 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.