Memandu perilaku agen dengan konteks yang dibuat

Halaman ini menjelaskan struktur yang direkomendasikan untuk menulis perintah yang efektif bagi agen data Conversational Analytics API Anda. Perintah ini adalah konteks yang dibuat yang Anda tentukan sebagai string menggunakan parameter system_instruction. Petunjuk sistem yang disusun dengan baik dapat meningkatkan akurasi dan relevansi respons yang diberikan API.

Apa yang dimaksud dengan petunjuk sistem?

Petunjuk sistem adalah panduan yang ditentukan pengguna yang dapat diberikan developer untuk membentuk perilaku agen data dan menyempurnakan respons API. Petunjuk sistem adalah bagian dari konteks yang digunakan API untuk menjawab pertanyaan. Konteks ini juga mencakup sumber data yang terhubung (tabel BigQuery, Eksplorasi Looker, sumber data Looker Studio), dan histori percakapan (untuk percakapan multi-turn).

Dengan memberikan panduan terstruktur yang jelas melalui petunjuk sistem, Anda dapat meningkatkan kemampuan agen dalam menafsirkan pertanyaan pengguna dan menghasilkan respons yang berguna dan akurat. Petunjuk sistem yang ditentukan dengan baik sangat berguna jika Anda terhubung ke data seperti tabel BigQuery, yang mungkin tidak memiliki lapisan semantik yang telah ditentukan sebelumnya seperti pada Eksplorasi Looker.

Misalnya, Anda dapat menggunakan petunjuk sistem untuk memberikan jenis panduan berikut kepada agen:

  • Logika khusus bisnis: Tentukan pelanggan "loyal" sebagai pelanggan yang telah melakukan lebih dari lima pembelian dalam jangka waktu tertentu.
  • Pemformatan respons: Ringkas semua respons dari agen data Anda dalam 20 kata atau kurang untuk menghemat waktu pengguna Anda.
  • Presentasi data: Format semua angka agar sesuai dengan panduan gaya perusahaan.

Memberikan petunjuk sistem

Anda dapat memberikan petunjuk sistem ke Conversational Analytics API sebagai string berformat YAML menggunakan parameter system_instruction. Meskipun parameter system_instruction bersifat opsional, sebaiknya berikan petunjuk sistem yang terstruktur dengan baik untuk mendapatkan respons yang akurat dan relevan.

Anda dapat menentukan string berformat YAML dalam kode selama penyiapan awal, seperti yang ditunjukkan dalam Mengonfigurasi setelan awal dan autentikasi (HTTP) atau Menentukan project penagihan dan petunjuk sistem (Python SDK). Kemudian, Anda dapat menyertakan parameter system_instruction dalam panggilan API berikut:

Template YAML untuk petunjuk sistem

Template berikut menunjukkan struktur YAML yang direkomendasikan untuk string yang Anda berikan ke parameter system_instruction, termasuk kunci yang tersedia dan jenis data yang diharapkan. Untuk contoh petunjuk sistem dengan nilai yang telah diisi, lihat Contoh: Petunjuk sistem.

Anda dapat menggunakan template YAML berikut untuk memberikan petunjuk sistem Anda sendiri:

- system_instruction: str # A description of the expected behavior of the agent. For example: You are a sales agent.
- tables: # A list of tables to describe for the agent.
    - table: # Details about a single table that is relevant for the agent.
        - name: str # The name of the table.
        - description: str # A description of the table.
        - synonyms: list[str] # Alternative terms for referring to the table.
        - tags: list[str] # Keywords or tags that are associated with the table.
        - fields: # Details about columns (fields) within the table.
            - field: # Details about a single column within the current table.
                - name: str # The name of the column.
                - description: str # A description of the column.
                - synonyms: list[str] # Alternative terms for referring to the column.
                - tags: list[str] # Keywords or tags that are associated with the column.
                - sample_values: list[str] # Sample values that are present within the column.
                - aggregations: list[str] # Commonly used or default aggregations for the column.
        - measures: # A list of calculated metrics (measures) for the table.
            - measure: # Details about a single measure within the table.
                - name: str # The name of the measure.
                - description: str # A description of the measure.
                - exp: str # The expression that is used to construct the measure.
                - synonyms: list[str] # Alternative terms for referring to the measure.
        - golden_queries: # A list of important or popular ("golden") queries for the table.
            - golden_query: # Details about a single golden query.
                - natural_language_query: str # The natural language query.
                - sql_query: str # The SQL query that corresponds to the natural language query.
        - golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
            - golden_action_plan: # Details about a single action plan.
                - natural_language_query: str # The natural language query.
                - action_plan: # A list of the steps for this action plan.
                    - step: str # A single step within the action plan.
    - relationships: # A list of join relationships between tables.
        - relationship: # Details about a single join relationship.
            - name: str # The name of this join relationship.
            - description: str # A description of the relationship.
            - relationship_type: str # The join relationship type: one-to-one, one-to-many, many-to-one, or many-to-many.
            - join_type: str # The join type: inner, outer, left, right, or full.
            - left_table: str # The name of the left table in the join.
            - right_table: str # The name of the right table in the join.
            - relationship_columns: # A list of columns that are used for the join.
                - left_column: str # The join column from the left table.
                - right_column: str # The join column from the right table.
- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
    - glossary: # The definition for a single glossary item.
        - term: str # The term, phrase, or abbreviation to define.
        - description: str # A description or definition of the term.
        - synonyms: list[str] # Alternative terms for the glossary entry.
- additional_descriptions: # A list of any other general instructions or content.
    - text: str # Any additional general instructions or context not covered elsewhere.

Komponen utama petunjuk sistem

Bagian berikut menjelaskan komponen utama petunjuk sistem dan cara menggunakannya untuk meningkatkan kualitas respons agen Anda.

Tentukan peran dan persona agen dengan system_instruction

Tentukan peran dan persona agen menggunakan kunci system_instruction. Petunjuk awal ini menetapkan nada dan gaya untuk respons API serta membantu agen memahami tujuan utamanya.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci system_instrucction:

- system_instruction: str

Misalnya, Anda dapat menentukan agen sebagai analis penjualan untuk toko e-commerce fiktif sebagai berikut:

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

Mendeskripsikan data Anda dengan tables

Kunci tables berisi daftar deskripsi tabel untuk agen dan memberikan detail tentang data spesifik yang tersedia bagi agen untuk menjawab pertanyaan. Setiap objek table dalam daftar ini berisi metadata untuk tabel tertentu, termasuk nama, deskripsi, sinonim, tag, kolom, ukuran, kueri utama, dan rencana tindakan utama tabel tersebut.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci tables:

- tables:
    - table:
      - name: str # The name of the table.
      - description: str # A description of the table.
      - synonyms: list[str] # Alternative terms for referring to the table.
      - tags: list[str] # Keywords or tags that are associated with the table.
      - fields: # A list of the fields in the table.
      - measures: # A list of the measures in the table.
      - golden_queries: # A list of golden queries for the table.
      - golden_action_plans: # A list of golden action plans for the table.

Misalnya, blok kode YAML berikut menunjukkan struktur dasar untuk kunci tables untuk tabel bigquery-public-data.thelook_ecommerce.orders:

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - description: Data for customer orders in The Look fictitious e-commerce store.
        - synonyms:
            - sales
            - orders_data
        - tags:
            - ecommerce
            - transaction

Mendeskripsikan kolom yang umum digunakan dengan fields

Kunci fields, yang bertingkat dalam objek table, mengambil daftar objek kolom untuk mendeskripsikan setiap kolom. Tidak semua kolom memerlukan konteks tambahan; namun, untuk kolom yang umum digunakan, menyertakan detail tambahan dapat membantu meningkatkan performa agen.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci fields:

- fields: # Details about columns (fields) within the table.
    - field: # Details about a single column within the current table.
        - name: str # The name of the column.
        - description: str # A description of the column.
        - synonyms: list[str] # Alternative terms for referring to the column.
        - tags: list[str] # Keywords or tags that are associated with the column.
        - sample_values: list[str] # Sample values that are present within the column.
        - aggregations: list[str] # Commonly used or default aggregations for the column.

Misalnya, kode YAML contoh berikut menjelaskan kolom utama seperti order_id, status, created_at, num_of_items, dan earnings untuk tabel orders:

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - fields:
            - field:
                - name: order_id
                - description: The unique identifier for each customer order.
            - field:
                - name: user_id
                - description: The unique identifier for each customer.
            - field:
                - name: status
                - description: The current status of the order.
                - sample_values:
                    - complete
                    - shipped
                    - returned
            - field:
                - name: created_at
                - description: The timestamp when the order was created.
            - field:
                - name: num_of_items
                - description: The total number of items in the order.
                - aggregations:
                    - sum
                    - avg
            - field:
                - name: earnings
                - description: The sales amount for the order.
                - aggregations:
                    - sum
                    - avg

Menentukan metrik bisnis dengan measures

Kunci measures, yang berada di dalam objek table, menentukan metrik atau penghitungan bisnis kustom yang tidak secara langsung ada sebagai kolom dalam tabel Anda. Memberikan konteks untuk ukuran membantu agen menjawab pertanyaan tentang indikator performa utama (KPI) atau nilai terhitung lainnya.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci measures:

- measures: # A list of calculated metrics (measures) for the table.
    - measure: # Details about a single measure within the table.
        - name: str # The name of the measure.
        - description: str # A description of the measure.
        - exp: str # The expression that is used to construct the measure.
        - synonyms: list[str] # Alternative terms for referring to the measure.

Misalnya, Anda dapat menentukan ukuran profit sebagai penghitungan penghasilan dikurangi biaya sebagai berikut:

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - measures:
            - measure:
                - name: profit
                - description: Raw profit (earnings minus cost).
                - exp: earnings - cost
                - synonyms:
                    - gains

Meningkatkan akurasi dengan golden_queries

Kunci golden_queries, yang berada dalam objek table, mengambil daftar objek golden_query. Kueri emas membantu agen memberikan respons yang lebih akurat dan relevan terhadap pertanyaan umum atau penting. Dengan memberikan kueri bahasa alami dan kueri SQL yang sesuai untuk setiap kueri emas kepada agen, Anda dapat memandu agen untuk memberikan hasil yang berkualitas lebih tinggi dan lebih konsisten.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci golden_queries:

- golden_queries: # A list of important or popular ("golden") queries for the table.
    - golden_query: # Details about a single golden query.
        - natural_language_query: str # The natural language query.
        - sql_query: str # The SQL query that corresponds to the natural language query.

Misalnya, Anda dapat menentukan kueri utama untuk analisis umum data dalam tabel orders sebagai berikut:

- tables:
    - table:
        - golden_queries:
            - golden_query:
                - natural_language_query: How many orders are there?
                - sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
            - golden_query:
                - natural_language_query: How many orders were shipped?
                - sql_query: >-
                    SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
                    WHERE status = 'shipped'

Menguraikan tugas multi-langkah dengan golden_action_plans

Kunci golden_action_plans, yang berada dalam objek table, mengambil daftar objek golden_action_plan. Anda dapat menggunakan rencana tindakan terbaik untuk memberikan contoh kepada agen tentang cara menangani permintaan multi-langkah, seperti mengambil data lalu membuat visualisasi.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci golden_action_plans:

- golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
    - golden_action_plan: # Details about a single action plan.
        - natural_language_query: str # The natural language query.
        - action_plan: # A list of the steps for this action plan.
            - step: str # A single step within the action plan.

Misalnya, Anda dapat menentukan rencana tindakan untuk menampilkan perincian pesanan menurut kelompok usia dan menyertakan detail tentang kueri SQL dan langkah-langkah terkait visualisasi:

- tables:
    - table:
        - golden_action_plans:
            - golden_action_plan:
                - natural_language_query: Show me the number of orders broken down by age group.
                - action_plan:
                    - step: >-
                        Run a SQL query that joins the table
                        sqlgen-testing.thelook_ecommerce.orders and
                        sqlgen-testing.thelook_ecommerce.users to get a
                        breakdown of order count by age group.
                    - step: >-
                        Create a vertical bar plot using the retrieved data,
                        with one bar per age group.

Tentukan gabungan tabel dengan relationships

Kunci relationships berisi daftar hubungan gabungan antar tabel. Dengan menentukan hubungan gabungan, Anda dapat membantu agen memahami cara menggabungkan data dari beberapa tabel saat menjawab pertanyaan.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci relationships:

- relationships: # A list of join relationships between tables.
    - relationship: # Details for a single join relationship.
        - name: str # A unique name for this join relationship.
        - description: str # A description of the relationship.
        - relationship_type: str # The join relationship type (e.g., "one-to-one", "one-to-many", "many-to-one", "many-to-many").
        - join_type: str # The join type (e.g., "inner", "outer", "left", "right", "full").
        - left_table: str # The name of the left table in the join.
        - right_table: str # The name of the right table in the join.
        - relationship_columns: # A list of columns that are used for the join.
            - left_column: str # The join column from the left table.
            - right_column: str # The join column from the right table.

Misalnya, Anda dapat menentukan hubungan orders_to_user antara tabel bigquery-public-data.thelook_ecommerce.orders dan tabel bigquery-public-data.thelook_ecommerce.users sebagai berikut:

- relationships:
    - relationship:
        - name: orders_to_user
        - description: >-
            Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
        - relationship_type: many-to-one
        - join_type: left
        - left_table: bigquery-public-data.thelook_ecommerce.orders
        - right_table: bigquery-public-data.thelook_ecommerce.users
        - relationship_columns:
            - left_column: user_id
            - right_column: id

Menjelaskan istilah bisnis dengan glossaries

Kunci glossaries mencantumkan definisi untuk istilah bisnis, jargon, dan singkatan yang relevan dengan data dan kasus penggunaan Anda. Dengan memberikan definisi glosarium, Anda dapat membantu agen menafsirkan dan menjawab pertanyaan yang menggunakan bahasa bisnis tertentu secara akurat.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci glossaries:

- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
    - glossary: # The definition for a single glossary item.
        - term: str # The term, phrase, or abbreviation to define.
        - description: str # A description or definition of the term.
        - synonyms: list[str] # Alternative terms for the glossary entry.

Misalnya, Anda dapat menentukan istilah seperti status bisnis umum dan "OMPF" sesuai dengan konteks bisnis spesifik Anda sebagai berikut:

- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: shipped
        - description: Represents an order status where the order has been shipped to the customer.
    - glossary:
        - term: returned
        - description: Represents an order status where the customer has returned the order.
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment

Sertakan petunjuk lebih lanjut dengan additional_descriptions

Kunci additional_descriptions mencantumkan petunjuk atau konteks umum tambahan yang tidak tercakup di bagian lain dalam petunjuk sistem. Dengan memberikan deskripsi tambahan, Anda dapat membantu agen lebih memahami konteks data dan kasus penggunaan Anda.

Blok kode YAML berikut menunjukkan struktur dasar untuk kunci additional_descriptions:

- additional_descriptions: # A list of any other general instructions or content.
    - text: str # Any additional general instructions or context not covered elsewhere.

Misalnya, Anda dapat menggunakan kunci additional_descriptions untuk memberikan informasi tentang organisasi Anda sebagai berikut:

- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.
    - text: 'Orders can be of three categories: food, clothes, and electronics.'

Contoh: Petunjuk sistem

Contoh berikut menunjukkan contoh petunjuk sistem untuk agen analis penjualan fiktif.

- 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.
- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - description: Data for orders in The Look, a fictitious ecommerce store.
        - synonyms: sales
        - tags: 'sale, order, sales_order'
        - fields:
            - field:
                - name: order_id
                - description: The unique identifier for each customer order.
            - field:
                - name: user_id
                - description: The unique identifier for each customer.
            - field:
                - name: status
                - description: The current status of the order.
                - sample_values:
                    - complete
                    - shipped
                    - returned
            - field:
                - name: created_at
                - description: >-
                    The date and time at which the order was created in timestamp
                    format.
            - field:
                - name: returned_at
                - description: >-
                    The date and time at which the order was returned in timestamp
                    format.
            - field:
                - name: num_of_items
                - description: The total number of items in the order.
                - aggregations: 'sum, avg'
            - field:
                - name: earnings
                - description: The sales revenue for the order.
                - aggregations: 'sum, avg'
            - field:
                - name: cost
                - description: The cost for the items in the order.
                - aggregations: 'sum, avg'
        - measures:
            - measure:
                - name: profit
                - description: Raw profit (earnings minus cost).
                - exp: earnings - cost
                - synonyms: gains
        - golden_queries:
            - golden_query:
                - natural_language_query: How many orders are there?
                - sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
            - golden_query:
                - natural_language_query: How many orders were shipped?
                - sql_query: >-
                    SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
                    WHERE status = 'shipped'
        - golden_action_plans:
            - golden_action_plan:
                - natural_language_query: Show me the number of orders broken down by age group.
                - action_plan:
                    - step: >-
                        Run a SQL query that joins the table
                        sqlgen-testing.thelook_ecommerce.orders and
                        sqlgen-testing.thelook_ecommerce.users to get a
                        breakdown of order count by age group.
                    - step: >-
                        Create a vertical bar plot using the retrieved data,
                        with one bar per age group.
    - table:
        - name: bigquery-public-data.thelook_ecommerce.users
        - description: Data for users in The Look, a fictitious ecommerce store.
        - synonyms: customers
        - tags: 'user, customer, buyer'
        - fields:
            - field:
                - name: id
                - description: The unique identifier for each user.
            - field:
                - name: first_name
                - description: The first name of the user.
                - tag: person
                - sample_values: 'alex, izumi, nur'
            - field:
                - name: last_name
                - description: The first name of the user.
                - tag: person
                - sample_values: 'warmer, stilles, smith'
            - field:
                - name: age_group
                - description: The age demographic group of the user.
                - sample_values:
                    - 18-24
                    - 25-34
                    - 35-49
                    - 50+
            - field:
                - name: email
                - description: The email address of the user.
                - tag: contact
                - sample_values: '222larabrown@gmail.com, cloudysanfrancisco@gmail.com'
        - golden_queries:
            - golden_query:
                - natural_language_query: How many unique customers are there?
                - sql_query: >-
                    SELECT COUNT(DISTINCT id) FROM
                    bigquery-public-data.thelook_ecommerce.users
            - golden_query:
                - natural_language_query: How many users in the 25-34 age group have a cymbalgroup email address?
                - sql_query: >-
                    SELECT COUNT(DISTINCT id) FROM
                    bigquery-public-data.thelook_ecommerce.users WHERE users.age_group =
                    '25-34' AND users.email LIKE '%@cymbalgroup.com';
    - relationships:
        - relationship:
            - name: orders_to_user
            - description: >-
                Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
            - relationship_type: many-to-one
            - join_type: left
            - left_table: bigquery-public-data.thelook_ecommerce.orders
            - right_table: bigquery-public-data.thelook_ecommerce.users
            - relationship_columns:
                - left_column: user_id
                - right_column: id
- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: shipped
        - description: Represents an order status where the order has been shipped to the customer.
    - glossary:
        - term: returned
        - description: Represents an order status where the customer has returned the order.
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment
- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.
    - text: 'Orders can be of three categories: food, clothes, and electronics.'