Definir el contexto del agente de datos para las fuentes de datos de Looker

El contexto creado es una guía que los propietarios de agentes de datos pueden proporcionar para dar forma al comportamiento de un agente de datos y para refinar las respuestas de la API. El contexto creado eficaz proporciona a tus agentes de datos de la API Conversational Analytics información útil para responder a preguntas sobre tus fuentes de datos. Las instrucciones del sistema son un tipo de contexto creado que los propietarios de agentes de datos pueden proporcionar para dar forma al comportamiento de un agente de datos y para refinar las respuestas de la API.

En esta página se describe cómo escribir instrucciones del sistema para fuentes de datos de Looker, que se basan en Exploraciones de Looker. Cuando te conectas a Exploraciones de Looker, proporcionas contexto creado a los agentes de datos exclusivamente a través de instrucciones del sistema.

Definir el contexto en las instrucciones del sistema

Las instrucciones del sistema constan de una serie de componentes y objetos clave que proporcionan al agente de datos detalles sobre la fuente de datos y directrices sobre el rol del agente a la hora de responder preguntas. Puede proporcionar instrucciones del sistema al agente de datos en el parámetro system_instruction como una cadena con formato YAML.

Una vez que hayas definido las instrucciones del sistema que componen el contexto creado, puedes proporcionar ese contexto a la API en una de las siguientes llamadas:

En la siguiente plantilla YAML se muestra un ejemplo de cómo puedes estructurar las instrucciones del sistema para una fuente de datos de 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

Descripciones de los componentes clave de las instrucciones del sistema

En las siguientes secciones se incluyen ejemplos de componentes clave de las instrucciones del sistema en Looker. Estas claves incluyen las siguientes:

system_instruction

Usa la clave system_instruction para definir el rol y el perfil del agente. Esta instrucción inicial marca el tono y el estilo de las respuestas de la API y ayuda al agente a entender su objetivo principal.

Por ejemplo, puedes definir un agente como analista de ventas de una tienda de comercio electrónico ficticia de la siguiente manera:

- 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

La clave golden_queries toma una lista de objetos golden_query. Las consultas de oro ayudan al agente a proporcionar respuestas más precisas y relevantes a preguntas comunes o importantes que puedes definir. Si proporciona al agente tanto una consulta en lenguaje natural como la consulta de Looker y la información de LookML correspondientes a cada consulta de referencia, puede guiar al agente para que proporcione resultados de mayor calidad y más coherentes. Por ejemplo, puede definir consultas de referencia para análisis habituales de los datos de la tabla order_items de la siguiente manera:

- 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

La glossaries incluye definiciones de términos empresariales, jerga y abreviaturas que son relevantes para tus datos y tu caso práctico, pero que aún no aparecen en tus datos. Por ejemplo, puedes definir términos como "Estado de la empresa habitual" y "Cliente fiel" según el contexto específico de tu empresa de la siguiente manera:

- 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

La clave additional_descriptions incluye cualquier instrucción general o contexto adicional que no se haya tratado en otras partes de las instrucciones del sistema. Por ejemplo, puedes usar la tecla additional_descriptions para proporcionar información sobre tu agente de la siguiente manera:

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

Ejemplo: instrucciones del sistema en Looker con YAML

En el siguiente ejemplo se muestran instrucciones del sistema de muestra para un agente analista de ventas ficticio.

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