Guiar el comportamiento de los agentes con contexto creado

En esta página se describe la estructura recomendada para escribir peticiones eficaces para tus agentes de datos de la API Conversational Analytics. Estas peticiones son contextos creados que se definen como cadenas mediante el parámetro system_instruction. Las instrucciones del sistema bien estructuradas pueden mejorar la precisión y la relevancia de las respuestas que proporciona la API.

Para ver ejemplos de contexto creado en diferentes entornos, consulta las siguientes páginas de documentación:

¿Qué son las instrucciones del sistema?

Las instrucciones del sistema son directrices definidas por el usuario que los desarrolladores pueden proporcionar para dar forma al comportamiento de un agente de datos y para refinar las respuestas de la API. Las instrucciones del sistema forman parte del contexto que usa la API para responder a las preguntas. Este contexto también incluye fuentes de datos conectadas (tablas de BigQuery, Exploraciones de Looker y fuentes de datos de Looker Studio) y el historial de conversaciones (en el caso de las conversaciones de varias interacciones).

Si proporcionas instrucciones claras y estructuradas a través de las instrucciones del sistema, puedes mejorar la capacidad del agente para interpretar las preguntas de los usuarios y generar respuestas útiles y precisas. Las instrucciones del sistema bien definidas son especialmente útiles si te conectas a datos como tablas de BigQuery, donde puede que no haya una capa semántica predefinida como en Exploraciones de Looker.

Por ejemplo, puedes usar instrucciones del sistema para proporcionar los siguientes tipos de orientación a un agente:

  • Lógica específica de la empresa: define a un cliente fiel como aquel que ha hecho más de cinco compras en un periodo determinado.
  • Formato de respuesta: resume todas las respuestas de tu agente de datos en 20 palabras o menos para ahorrar tiempo a tus usuarios.
  • Presentación de datos: da formato a todos los números para que coincidan con la guía de estilo de la empresa.

Proporcionar instrucciones del sistema

Puede proporcionar instrucciones del sistema a la API Conversational Analytics como una cadena con formato YAML mediante el parámetro system_instruction. Aunque el parámetro system_instruction es opcional, se recomienda proporcionar instrucciones del sistema bien estructuradas para obtener respuestas precisas y pertinentes.

Puedes definir la cadena con formato YAML en tu código durante la configuración inicial, tal como se muestra en Configurar los ajustes iniciales y la autenticación (HTTP) o Especificar el proyecto de facturación y las instrucciones del sistema (SDK de Python). Después, puede incluir el parámetro system_instruction en las siguientes llamadas a la API:

Plantilla YAML para instrucciones del sistema

En la siguiente plantilla se muestra la estructura YAML recomendada para la cadena que proporciones al parámetro system_instruction, incluidas las claves disponibles y los tipos de datos esperados.

Puedes usar la siguiente plantilla YAML para proporcionar tus propias instrucciones del 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.

Componentes clave de las instrucciones del sistema

En las siguientes secciones se describen los componentes clave de las instrucciones del sistema y cómo usarlos para mejorar la calidad de las respuestas de tu agente. Estas claves incluyen las siguientes:

Define el rol y el perfil del agente con system_instruction

Define el rol y el perfil del agente con la tecla system_instruction. 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.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave system_instruction:

- system_instruction: str

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.

Describir los datos con tables

La clave tables contiene una lista de descripciones de tablas para el agente y proporciona detalles sobre los datos específicos que tiene a su disposición para responder preguntas. Cada objeto table de esta lista contiene los metadatos de una tabla específica, incluidos el nombre, la descripción, los sinónimos, las etiquetas, los campos, las medidas, las consultas de referencia y los planes de acción de referencia de esa tabla.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Describir los campos que se usan con frecuencia con fields

La clave fields, que está anidada en un objeto table, toma una lista de objetos de campo para describir columnas concretas. No todos los campos necesitan contexto adicional, pero, en el caso de los campos que se usan con frecuencia, incluir más detalles puede ayudar a mejorar el rendimiento del agente.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Definir métricas de negocio con measures

La clave measures, que está anidada en un objeto table, define métricas o cálculos empresariales personalizados que no están presentes directamente como columnas en sus tablas. Proporcionar contexto para las métricas ayuda al agente a responder preguntas sobre los indicadores clave de rendimiento u otros valores calculados.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Mejorar la precisión con golden_queries

La clave golden_queries, que está anidada en un objeto table, toma una lista de objetos golden_query. Las consultas destacadas ayudan al agente a proporcionar respuestas más precisas y relevantes a preguntas habituales o importantes. Si proporcionas al agente tanto una consulta en lenguaje natural como la consulta SQL correspondiente para cada consulta de referencia, puedes guiar al agente para que proporcione resultados de mayor calidad y más coherentes.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Describir tareas de varios pasos con golden_action_plans

La clave golden_action_plans, que está anidada en un objeto table, toma una lista de objetos golden_action_plan. Puedes usar planes de acción óptimos para proporcionar al agente ejemplos de cómo gestionar solicitudes de varios pasos, como obtener datos y, a continuación, crear una visualización.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Definir combinaciones de tablas con relationships

La clave relationships contiene una lista de relaciones de unión entre tablas. Al definir relaciones de unión, puedes ayudar al agente a entender cómo unir datos de varias tablas al responder preguntas.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Explicar términos empresariales con glossaries

La glossaries clave incluye definiciones de términos empresariales, jerga y abreviaturas relevantes para tus datos y tu caso práctico. Si proporcionas definiciones de glosario, puedes ayudar al agente a interpretar y responder con precisión a preguntas que utilicen un lenguaje empresarial específico.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave 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.

Incluye más instrucciones con 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. Si proporciona descripciones adicionales, puede ayudar al agente a entender mejor el contexto de sus datos y su caso práctico.

En el siguiente bloque de código YAML se muestra la estructura básica de la clave additional_descriptions:

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