Cómo 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 definir el comportamiento de un agente de datos y refinar las respuestas de la API. El contexto creado eficaz proporciona a tus agentes de datos de la API de Conversational Analytics un contexto útil para responder 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 definir el comportamiento de un agente de datos y refinar las respuestas de la API.

En esta página, se describe cómo escribir instrucciones del sistema para las 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.

Cómo 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 orientación sobre el rol del agente cuando responde preguntas. Puedes proporcionar instrucciones del sistema al agente de datos en el parámetro system_instruction como una cadena con formato YAML.

Después de definir las instrucciones del sistema que componen tu contexto creado, puedes proporcionarle ese contexto a la API en una de las siguientes llamadas:

En la siguiente plantilla de YAML, se muestra un ejemplo de cómo podrías 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 lo siguiente:

system_instruction

Usa la clave system_instruction para definir el rol y el arquetipo del agente. Esta instrucción inicial establece el tono y el estilo de las respuestas de la API, y ayuda al agente a comprender su propósito 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 preguntas de oro ayudan al agente a proporcionar respuestas más precisas y pertinentes a las preguntas comunes o importantes que puedes definir. Si le proporcionas al agente tanto una búsqueda en lenguaje natural como la búsqueda de Looker correspondiente y la información de LookML para cada búsqueda de referencia, puedes guiar al agente para que proporcione resultados de mayor calidad y más coherentes. Por ejemplo, puedes definir consultas de referencia para análisis comunes de los datos en 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 clave glossaries enumera las definiciones de términos comerciales, jerga y abreviaturas que son relevantes para tus datos y tu caso de uso, pero que aún no aparecen en tus datos. Por ejemplo, puedes definir términos como "Estados comerciales comunes" y "Cliente leal" 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 enumera cualquier instrucción o contexto general adicional que no se aborde en otras partes de las instrucciones del sistema. Por ejemplo, puedes usar la clave 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.