작성된 컨텍스트로 에이전트 동작 안내

이 페이지에서는 Conversational Analytics API 데이터 에이전트에 효과적인 프롬프트를 작성하기 위한 권장 구조를 설명합니다. 이러한 프롬프트는 system_instruction 매개변수를 사용하여 문자열로 정의하는 작성된 컨텍스트입니다. 잘 구성된 시스템 안내는 API가 제공하는 대답의 정확성과 관련성을 개선할 수 있습니다.

시스템 요청 사항이란 무엇인가요?

시스템 안내는 개발자가 데이터 에이전트의 동작을 형성하고 API의 응답을 개선하기 위해 제공할 수 있는 사용자 정의 안내입니다. 시스템 안내는 API가 질문에 답변하는 데 사용하는 컨텍스트의 일부입니다. 이 컨텍스트에는 연결된 데이터 소스 (BigQuery 표, Looker Explore, Looker Studio 데이터 소스)와 대화 기록 (다중 턴 대화의 경우)도 포함됩니다.

시스템 안내를 통해 명확하고 구조화된 안내를 제공하면 상담사가 사용자 질문을 해석하고 유용하고 정확한 대답을 생성하는 능력을 개선할 수 있습니다. 잘 정의된 시스템 프롬프트는 Looker Explore와 같이 사전 정의된 시맨틱 레이어가 없을 수 있는 BigQuery 테이블과 같은 데이터에 연결하는 경우 특히 유용합니다.

예를 들어 시스템 안내를 사용하여 다음과 같은 유형의 안내를 에이전트에게 제공할 수 있습니다.

  • 비즈니스별 로직: 특정 기간 내에 5회 이상 구매한 고객을 '충성도 높은' 고객으로 정의합니다.
  • 대답 형식: 사용자의 시간을 절약하기 위해 데이터 에이전트의 모든 대답을 20단어 이하로 요약합니다.
  • 데이터 표시: 회사의 스타일 가이드에 맞게 모든 숫자의 형식을 지정합니다.

시스템 요청 사항 제공

system_instruction 매개변수를 사용하여 시스템 지침을 YAML 형식 문자열로 Conversational Analytics API에 제공할 수 있습니다. system_instruction 매개변수는 선택사항이지만 정확하고 관련성 있는 대답을 위해 잘 구조화된 시스템 안내를 제공하는 것이 좋습니다.

초기 설정 및 인증 구성 (HTTP) 또는 결제 프로젝트 및 시스템 안내 지정 (Python SDK)에 표시된 대로 초기 설정 중에 코드에서 YAML 형식 문자열을 정의할 수 있습니다. 그런 다음 다음 API 호출에 system_instruction 매개변수를 포함할 수 있습니다.

시스템 안내용 YAML 템플릿

다음 템플릿은 사용 가능한 키와 예상 데이터 유형을 포함하여 system_instruction 매개변수에 제공하는 문자열의 권장 YAML 구조를 보여줍니다. 값이 채워진 시스템 안내의 샘플은 예: 시스템 안내를 참고하세요.

다음 YAML 템플릿을 사용하여 자체 시스템 안내를 제공할 수 있습니다.

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

시스템 안내의 주요 구성요소

다음 섹션에서는 시스템 지침의 주요 구성요소와 이를 사용하여 에이전트의 대답 품질을 개선하는 방법을 설명합니다.

system_instruction을 사용하여 에이전트의 역할과 페르소나 정의

system_instruction 키를 사용하여 상담사의 역할과 페르소나를 정의합니다. 이 초기 안내는 API의 응답에 대한 어조와 스타일을 설정하고 상담사가 핵심 목적을 이해하는 데 도움이 됩니다.

다음 YAML 코드 블록은 system_instrucction 키의 기본 구조를 보여줍니다.

- system_instruction: str

예를 들어 가상의 전자상거래 스토어의 영업 분석가로 에이전트를 다음과 같이 정의할 수 있습니다.

- 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로 데이터 설명하기

tables 키에는 에이전트의 표 설명 목록이 포함되어 있으며, 질문에 답변하기 위해 에이전트가 사용할 수 있는 특정 데이터에 관한 세부정보가 제공됩니다. 이 목록의 각 table 객체에는 테이블 이름, 설명, 동의어, 태그, 필드, 측정항목, 골든 질문, 골든 작업 계획 등 특정 테이블의 메타데이터가 포함됩니다.

다음 YAML 코드 블록은 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.

예를 들어 다음 YAML 코드 블록은 bigquery-public-data.thelook_ecommerce.orders 테이블의 tables 키의 기본 구조를 보여줍니다.

- 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

fields를 사용하여 일반적으로 사용되는 필드 설명

table 객체 내에 중첩된 fields 키는 개별 열을 설명하는 필드 객체 목록을 사용합니다. 모든 필드에 추가 컨텍스트가 필요한 것은 아니지만, 일반적으로 사용되는 필드의 경우 추가 세부정보를 포함하면 상담사의 실적을 개선하는 데 도움이 될 수 있습니다.

다음 YAML 코드 블록은 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.

예를 들어 다음 샘플 YAML 코드는 orders 테이블의 order_id, status, created_at, num_of_items, earnings과 같은 주요 필드를 설명합니다.

- 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

measures로 비즈니스 측정항목 정의

table 객체 내에 중첩된 measures 키는 표에 열로 직접 표시되지 않는 맞춤 비즈니스 측정항목 또는 계산을 정의합니다. 측정값에 대한 컨텍스트를 제공하면 상담사가 핵심성과지표 (KPI) 또는 기타 계산된 값에 관한 질문에 답변하는 데 도움이 됩니다.

다음 YAML 코드 블록은 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.

예를 들어 다음과 같이 수입에서 비용을 뺀 값으로 profit 측정값을 정의할 수 있습니다.

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

golden_queries로 정확도 개선

table 객체 내에 중첩된 golden_queries 키는 golden_query 객체 목록을 사용합니다. 골든 질문은 상담사가 일반적이거나 중요한 질문에 더 정확하고 관련성 있는 답변을 제공하는 데 도움이 됩니다. 각 골든 질문에 대해 자연어 질문과 해당 SQL 질문을 모두 에이전트에게 제공하면 에이전트가 더 높은 품질의 일관된 결과를 제공하도록 안내할 수 있습니다.

다음 YAML 코드 블록은 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.

예를 들어 orders 테이블의 데이터에 대한 일반적인 분석의 골든 쿼리를 다음과 같이 정의할 수 있습니다.

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

golden_action_plans로 여러 단계의 작업 개요 작성

table 객체 내에 중첩된 golden_action_plans 키는 golden_action_plan 객체 목록을 사용합니다. 골든 액션 계획을 사용하여 데이터를 가져온 다음 시각화하는 것과 같은 다단계 요청을 처리하는 방법을 에이전트에게 예시로 제공할 수 있습니다.

다음 YAML 코드 블록은 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.

예를 들어 연령대별 주문 분류를 표시하는 작업 계획을 정의하고 SQL 쿼리 및 시각화 관련 단계에 관한 세부정보를 포함할 수 있습니다.

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

relationships로 테이블 조인 정의

relationships 키에는 테이블 간의 조인 관계 목록이 포함됩니다. 조인 관계를 정의하면 에이전트가 질문에 답변할 때 여러 테이블의 데이터를 조인하는 방법을 이해하는 데 도움이 됩니다.

다음 YAML 코드 블록은 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.

예를 들어 bigquery-public-data.thelook_ecommerce.orders 테이블과 bigquery-public-data.thelook_ecommerce.users 테이블 간에 다음과 같이 orders_to_user 관계를 정의할 수 있습니다.

- 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를 사용하여 비즈니스 용어 설명

glossaries 키에는 데이터 및 사용 사례와 관련된 비즈니스 용어, 전문 용어, 약어의 정의가 나열됩니다. 용어집 정의를 제공하면 에이전트가 특정 비즈니스 언어를 사용하는 질문을 정확하게 해석하고 답변하는 데 도움이 됩니다.

다음 YAML 코드 블록은 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.

예를 들어 다음과 같이 특정 비즈니스 컨텍스트에 따라 일반적인 비즈니스 상태 및 'OMPF'와 같은 용어를 정의할 수 있습니다.

- 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에 추가 안내 포함

additional_descriptions 키는 시스템 안내의 다른 곳에서 다루지 않는 추가 일반 안내나 컨텍스트를 나열합니다. 추가 설명을 제공하면 상담사가 데이터와 사용 사례의 맥락을 더 잘 이해할 수 있습니다.

다음 YAML 코드 블록은 additional_descriptions 키의 기본 구조를 보여줍니다.

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

예를 들어 additional_descriptions 키를 사용하여 다음과 같이 조직에 관한 정보를 제공할 수 있습니다.

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

예: 시스템 안내

다음 예는 가상의 판매 분석가 에이전트에 대한 샘플 시스템 안내를 보여줍니다.

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