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.

Untuk contoh konteks yang dibuat di lingkungan yang berbeda, lihat halaman dokumentasi berikut:

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.

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. Kunci ini mencakup:

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_instruction:

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

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.

Menentukan metrik bisnis dengan measures

Kunci measures, yang berada di dalam objek table, menentukan metrik atau penghitungan bisnis kustom yang tidak secara langsung ditampilkan 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.

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.

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.

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.

Menjelaskan istilah bisnis dengan glossaries

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

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.