Guida il comportamento dell'agente con il contesto creato

Questa pagina descrive la struttura consigliata per scrivere prompt efficaci per gli agenti di dati dell'API Conversational Analytics. Questi prompt sono contesti creati che definisci come stringhe utilizzando il parametro system_instruction. Istruzioni di sistema ben strutturate possono migliorare l'accuratezza e la pertinenza delle risposte fornite dall'API.

Per esempi di contesto creato in ambienti diversi, consulta le seguenti pagine della documentazione:

Che cosa sono le istruzioni di sistema?

Le istruzioni di sistema sono indicazioni definite dall'utente che gli sviluppatori possono fornire per modellare il comportamento di un agente dati e perfezionare le risposte dell'API. Le istruzioni di sistema fanno parte del contesto che l'API utilizza per rispondere alle domande. Questo contesto include anche le origini dati connesse (tabelle BigQuery, esplorazioni di Looker, origini dati di Looker Studio) e la cronologia delle conversazioni (per le conversazioni a più turni).

Fornendo indicazioni chiare e strutturate tramite le istruzioni di sistema, puoi migliorare la capacità dell'agente di interpretare le domande degli utenti e generare risposte utili e accurate. Le istruzioni di sistema ben definite sono particolarmente utili se ti connetti a dati come le tabelle BigQuery, dove potrebbe non essere presente un livello semantico predefinito come in un'esplorazione di Looker.

Ad esempio, puoi utilizzare le istruzioni di sistema per fornire i seguenti tipi di indicazioni a un agente:

  • Logica specifica per l'attività: definisci un cliente "fedele" come un cliente che ha effettuato più di cinque acquisti in un determinato periodo di tempo.
  • Formattazione della risposta: riepiloga tutte le risposte del tuo agente dati in 20 parole o meno per far risparmiare tempo agli utenti.
  • Presentazione dei dati: formatta tutti i numeri in modo che corrispondano alla guida di stile dell'azienda.

Fornire istruzioni di sistema

Puoi fornire istruzioni di sistema all'API Conversational Analytics come stringa formattata in YAML utilizzando il parametro system_instruction. Sebbene il parametro system_instruction sia facoltativo, è consigliabile fornire istruzioni di sistema ben strutturate per ottenere risposte accurate e pertinenti.

Puoi definire la stringa formattata in YAML nel codice durante la configurazione iniziale, come mostrato in Configurare le impostazioni iniziali e l'autenticazione (HTTP) o Specificare il progetto di fatturazione e le istruzioni di sistema (SDK Python). Puoi quindi includere il parametro system_instruction nelle seguenti chiamate API:

Modello YAML per le istruzioni di sistema

Il seguente modello mostra la struttura YAML consigliata per la stringa che fornisci al parametro system_instruction, incluse le chiavi disponibili e i tipi di dati previsti.

Puoi utilizzare il seguente modello YAML per fornire le tue istruzioni di sistema:

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

Componenti chiave delle istruzioni di sistema

Le sezioni seguenti descrivono i componenti chiave delle istruzioni di sistema e come utilizzarli per migliorare la qualità delle risposte dell'agente. Queste chiavi includono:

Definisci il ruolo e la personalità dell'agente con system_instruction

Definisci il ruolo e la personalità dell'agente utilizzando il tasto system_instruction. Questa istruzione iniziale definisce il tono e lo stile delle risposte dell'API e aiuta l'agente a comprendere il suo scopo principale.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave system_instruction:

- system_instruction: str

Ad esempio, puoi definire un agente come analista delle vendite per un negozio e-commerce fittizio nel seguente modo:

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

Descrivere i dati con tables

La chiave tables contiene un elenco di descrizioni delle tabelle per l'agente e fornisce dettagli sui dati specifici disponibili per l'agente per rispondere alle domande. Ogni oggetto table all'interno di questo elenco contiene i metadati di una tabella specifica, inclusi nome, descrizione, sinonimi, tag, campi, misure, query principali e piani d'azione principali della tabella.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Descrivere i campi utilizzati di frequente con fields

La chiave fields, nidificata all'interno di un oggetto table, accetta un elenco di oggetti campo per descrivere le singole colonne. Non tutti i campi richiedono un contesto aggiuntivo, ma per i campi di uso comune, l'inclusione di dettagli aggiuntivi può contribuire a migliorare il rendimento dell'agente.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Definisci le metriche aziendali con measures

La chiave measures, nidificata all'interno di un oggetto table, definisce metriche o calcoli aziendali personalizzati che non sono direttamente presenti come colonne nelle tabelle. Fornire il contesto per le misure aiuta l'agente a rispondere a domande sugli indicatori chiave di prestazione (KPI) o su altri valori calcolati.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Migliorare la precisione con golden_queries

La chiave golden_queries, nidificata all'interno di un oggetto table, accetta un elenco di oggetti golden_query. Le query d'oro aiutano l'agente a fornire risposte più accurate e pertinenti a domande comuni o importanti. Fornendo all'agente sia una query in linguaggio naturale sia la query SQL corrispondente per ogni query di riferimento, puoi guidarlo a fornire risultati di qualità superiore e più coerenti.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Delineare le attività in più passaggi con golden_action_plans

La chiave golden_action_plans, nidificata all'interno di un oggetto table, accetta un elenco di oggetti golden_action_plan. Puoi utilizzare i piani d'azione di riferimento per fornire all'agente esempi di come gestire le richieste in più passaggi, ad esempio per recuperare i dati e poi creare una visualizzazione.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Definisci i join delle tabelle con relationships

La chiave relationships contiene un elenco di relazioni di unione tra le tabelle. Definendo le relazioni di join, puoi aiutare l'agente a capire come unire i dati di più tabelle quando risponde alle domande.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Spiegare i termini commerciali con glossaries

L'elenco delle glossaries chiavi definisce i termini aziendali, il gergo e le abbreviazioni pertinenti ai tuoi dati e al tuo caso d'uso. Fornendo le definizioni del glossario, puoi aiutare l'agente a interpretare e rispondere con precisione alle domande che utilizzano un linguaggio aziendale specifico.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave 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.

Includi ulteriori istruzioni con additional_descriptions

Il tasto additional_descriptions elenca eventuali istruzioni generali o contesto aggiuntivi non trattati altrove nelle istruzioni di sistema. Fornendo descrizioni aggiuntive, puoi aiutare l'agente a comprendere meglio il contesto dei tuoi dati e il caso d'uso.

Il seguente blocco di codice YAML mostra la struttura di base per la chiave additional_descriptions:

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