Nesta página, descrevemos como escrever instruções do sistema para agentes de dados que usam fontes de dados do Looker, que são baseadas em Análises do Looker.
O contexto criado é uma orientação que os proprietários de agentes de dados podem fornecer para moldar o comportamento de um agente de dados e refinar as respostas da API. Um contexto criado de forma eficaz fornece aos agentes de dados da API Análise conversacional um contexto útil para responder a perguntas sobre suas fontes de dados.
Para fontes de dados do Looker, é possível fornecer contexto criado por meio de uma combinação de contexto estruturado e instruções do sistema. Sempre que possível, forneça
contexto usando campos de contexto estruturados. Em seguida, use o parâmetro system_instruction para orientações complementares que não são cobertas pelos campos estruturados. As instruções do sistema são um tipo de contexto criado que os proprietários de agentes de dados podem fornecer a um agente para informar o papel, o tom e o comportamento geral dele. Muitas vezes, as instruções do sistema podem ser mais em formato livre do que o contexto estruturado.
Embora os campos de contexto estruturado e as instruções do sistema sejam opcionais, fornecer um contexto robusto permite que o agente dê respostas mais precisas e relevantes. Durante a criação do agente de dados, todas as informações de contexto estruturadas que você forneceu serão adicionadas automaticamente às instruções do sistema.
Definir contexto estruturado
Você pode fornecer perguntas e respostas de referência em um contexto estruturado para seu agente de dados. Depois de definir o contexto estruturado, é possível fornecê-lo ao agente de dados usando solicitações HTTP diretas ou com o SDK do Python.
Para fontes de dados do Looker, as consultas de ouro são capturadas na chave looker_golden_queries, que define pares de perguntas em linguagem natural e as consultas correspondentes do Looker. Ao fornecer ao agente
um par de perguntas em linguagem natural e os metadados de Análise
correspondentes, você pode orientar o agente a fornecer resultados de maior qualidade e mais
consistentes. Exemplos de consultas de ouro do Looker
estão incluídos nesta página.
Para definir cada consulta de ouro do Looker, forneça valores para os dois campos a seguir:
natural_language_questions: a pergunta em linguagem natural que um usuário pode fazer.looker_query: a consulta de ouro do Looker que corresponde à pergunta em linguagem natural.
Veja um exemplo de par natural_language_questions — looker_query
de uma análise chamada "Aeroportos":
natural_language_questions: ["What are the major airport codes and cities in CA?"]
looker_query": {
"model": "airports",
"explore": "airports",
"fields": ["airports.city", "airports.code"],
"filters": [
{
"field": "airports.major",
"value": "Y"
},
{
"field": "airports.state",
"value": "CA"
}
]
}
Definir uma consulta de ouro do Looker
Defina uma consulta de ouro do Looker para uma determinada Análise fornecendo
valores para os campos natural_language_questions e looker_query. Para o campo
natural_language_questions, considere as perguntas que um usuário pode fazer
sobre essa Análise e escreva essas perguntas em linguagem natural. É possível
incluir mais de uma pergunta no valor desse campo. É possível receber o valor
do campo looker_query nos metadados de consulta da Análise.
O objeto LookerQuery é compatível com os seguintes campos:
model(string): o modelo do LookML usado para gerar a consulta. Este campo é obrigatório.explore(string): a Análise que foi usada para gerar a consulta. Este campo é obrigatório.fields[](string): os campos a serem recuperados da Análise, incluindo dimensões e medidas. Esse campo é opcional.filters[](objeto (Filter)): os filtros a serem aplicados à Análise. Esse campo é opcional.sorts[](string): a classificação a ser aplicada à Análise. Esse campo é opcional.limit(string): o limite de linhas de dados a ser aplicado à Análise. Esse campo é opcional.
É possível recuperar os metadados de consulta da Análise das seguintes maneiras:
- Recuperar os metadados da consulta na página "Análise"
- Recuperar o objeto de consulta do Looker no endpoint de API
GetQueryForSlug
Recuperar os metadados da consulta na interface do usuário da Análise
- Na Análise, selecione o menu Ações da Análise e, em seguida, selecione Acessar LookML.
- Selecione a guia Painel.
- Copie os detalhes da consulta do LookML. Por exemplo, a imagem a seguir mostra o LookML de uma Análise chamada "Itens do pedido":

Copie os metadados selecionados para usar na consulta de ouro do Looker:
model: thelook
explore: order_items
fields: [order_items.order_id, orders.status]
sorts: [orders.status, order_items.order_id]
limit: 500
Recuperar o objeto de consulta do Looker usando a API Looker
Para recuperar informações sobre a Análise usando a API Looker, siga estas etapas:
- Na Análise, selecione o menu Ações de análise e, em seguida, selecione Compartilhar. O Looker exibe URLs que você pode
copiar para compartilhar a Análise. Os URLs de compartilhamento geralmente são assim:
https://looker.yourcompany/x/vwGSbfc. OvwGSbfcfinal no URL de compartilhamento é o slug de compartilhamento. - Copie o slug de compartilhamento.
- Faça uma solicitação à API Looker:
GET /queries/slug/Explore_slugtransmitindo o slug do URL da Análise como uma string emExplore_slug. Na solicitação, inclua os campos dos metadados da consulta do Explorar que você quer que sejam retornados. Consulte a página de referência da API Get Query for Slug para mais informações. - Copie os metadados da consulta da resposta da API.
Exemplos de consultas de ouro do Looker
Os exemplos a seguir mostram como fornecer consultas de ouro para a Análise do airports
com solicitações HTTP diretas e com o SDK do Python.
HTTP
Em uma solicitação HTTP direta, forneça uma lista de objetos de consulta de ouro do Looker para a chave looker_golden_queries. Cada objeto precisa conter
uma chave natural_Language_questions e uma chave looker_query correspondente.
looker_golden_queries = [
{
"natural_language_questions": ["What is the highest observed positive longitude?"],
"looker_query": {
"model": "airports",
"explore": "airports",
"fields": ["airports.longitude"],
"filters": [
{
"field": "airports.longitude",
"value": ">0"
}
],
"sorts": ["airports.longitude desc"],
"limit": "1"
}
},
{
"natural_language_questions": ["What are the major airport codes and cities in CA?", "Can you list the cities and airport codes of airports in CA?"],
"looker_query": {
"model": "airports",
"explore": "airports",
"fields": ["airports.city", "airports.code"],
"filters": [
{
"field": "airports.major",
"value": "Y"
},
{
"field": "airports.state",
"value": "CA"
}
]
}
},
]
SDK do Python
Ao usar o SDK do Python, é possível fornecer uma lista de objetos LookerGoldenQuery. Para cada objeto, forneça valores para os parâmetros natural_language_questions e looker_query.
looker_golden_queries = [geminidataanalytics.LookerGoldenQuery(
natural_language_questions=[
"What is the highest observed positive longitude?"
],
looker_query=geminidataanalytics.LookerQuery(
model="airports",
explore="airports",
fields=["airports.longitude"],
filters=[
geminidataanalytics.LookerQuery.Filter(
field="airports.longitude", value=">0"
)
],
sorts=["airports.longitude desc"],
limit="1",
),
),
geminidataanalytics.LookerGoldenQuery(
natural_language_questions=[
"What are the major airport codes and cities in CA?",
"Can you list the cities and airport codes of airports in CA?",
],
looker_query=geminidataanalytics.LookerQuery(
model="airports",
explore="airports",
fields=["airports.city", "airports.code"],
filters=[
geminidataanalytics.LookerQuery.Filter(
field="airports.major", value="Y"
),
geminidataanalytics.LookerQuery.Filter(
field="airports.state", value="CA"
),
],
),
),
]
Definir contexto adicional nas instruções do sistema
As instruções do sistema consistem em uma série de componentes e objetos principais que fornecem ao agente de dados detalhes sobre a fonte de dados e orientações sobre o papel do agente ao responder a perguntas. É possível fornecer instruções do sistema ao agente de dados no parâmetro system_instruction como uma string formatada em YAML.
O modelo YAML a seguir mostra um exemplo de como estruturar as instruções do sistema para uma fonte de dados do Looker:
- system_instruction: str # Describe the expected behavior of the agent
- glossaries: # Define business terms, jargon, and abbreviations that are relevant to your use case
- glossary:
- term: str
- description: str
- synonyms: list[str]
- additional_descriptions: # List any additional general instructions
- text: str
Descrições dos principais componentes das instruções do sistema
As seções a seguir contêm exemplos dos componentes principais das instruções do sistema no Looker. Essas chaves incluem:
system_instruction
Use a chave system_instruction para definir a função e o perfil do agente. Esse conjunto de instruções inicial define o tom e o estilo das respostas da API e ajuda o agente a entender o objetivo principal dele.
Por exemplo, você pode definir um agente como analista de vendas de uma loja de e-commerce fictícia da seguinte maneira:
- 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.
glossaries
A chave glossaries lista definições de termos comerciais, jargões e
abreviações relevantes para seus dados e caso de uso, mas que ainda não
aparecem nos dados. Por exemplo, você pode definir termos como status da empresa comuns e "Cliente fiel" de acordo com seu contexto comercial específico da seguinte forma:
- glossaries:
- glossary:
- term: Loyal Customer
- description: A customer who has made more than one purchase.
Maps to the dimension 'user_order_facts.repeat_customer' being
'Yes'. High value loyal customers are those with high
'user_order_facts.lifetime_revenue'.
- synonyms:
- repeat customer
- returning customer
additional_descriptions
A chave additional_descriptions lista outras instruções gerais ou contextos não abordados em outras partes das instruções do sistema. Por exemplo,
é possível usar a chave additional_descriptions para fornecer informações sobre seu
agente da seguinte forma:
- additional_descriptions:
- text: The user is typically a Sales Manager, Product Manager, or
Marketing Analyst. They need to understand performance trends, build
customer lists for campaigns, and analyze product sales.
Exemplo: instruções do sistema no Looker
O exemplo a seguir mostra instruções de sistema de amostra para um agente analista de vendas fictício:
- system_instruction: "You are an expert sales, product, and operations
analyst for our e-commerce store. Your primary function is to answer
questions by querying the 'Order Items' Explore. Always be concise and
data-driven. When asked about 'revenue' or 'sales', use
'order_items.total_sale_price'. For 'profit' or 'margin', use
'order_items.total_gross_margin'. For 'customers' or 'users', use
'users.count'. The default date for analysis is 'order_items.created_date'
unless specified otherwise. For advanced statistical questions, such as
correlation or regression analysis, use the Python tool to fetch the
necessary data, perform the calculation, and generate a plot (like a scatter
plot or heatmap)."
- glossaries:
- term: Revenue
- description: The total monetary value from items sold. Maps to the
measure 'order_items.total_sale_price'.
- synonyms:
- sales
- total sales
- income
- turnover
- term: Profit
- description: Revenue minus the cost of goods sold. Maps to the measure
'order_items.total_gross_margin'.
- synonyms:
- margin
- gross margin
- contribution
- term: Buying Propensity
- description: Measures the likelihood of a customer to purchase again
soon. Primarily maps to the 'order_items.30_day_repeat_purchase_rate'
measure.
- synonyms:
- repeat purchase rate
- repurchase likelihood
- customer velocity
- term: Customer Lifetime Value
- description: The total revenue a customer has generated over their
entire history with us. Maps to 'user_order_facts.lifetime_revenue'.
- synonyms:
- CLV
- LTV
- lifetime spend
- lifetime value
- term: Loyal Customer
- description: "A customer who has made more than one purchase. Maps to
the dimension 'user_order_facts.repeat_customer' being 'Yes'. High value
loyal customers are those with high
'user_order_facts.lifetime_revenue'."
- synonyms:
- repeat customer
- returning customer
- term: Active Customer
- description: "A customer who is currently considered active based on
their recent purchase history. Mapped to
'user_order_facts.currently_active_customer' being 'Yes'."
- synonyms:
- current customer
- engaged shopper
- term: Audience
- description: A list of customers, typically identified by their email
address, for marketing or analysis purposes.
- synonyms:
- audience list
- customer list
- segment
- term: Return Rate
- description: The percentage of items that are returned by customers
after purchase. Mapped to 'order_items.return_rate'.
- synonyms:
- returns percentage
- RMA rate
- term: Processing Time
- description: The time it takes to prepare an order for shipment from the
moment it is created. Maps to 'order_items.average_days_to_process'.
- synonyms:
- fulfillment time
- handling time
- term: Inventory Turn
- description: "A concept related to how quickly stock is sold. This can
be analyzed using 'inventory_items.days_in_inventory' (lower days means
higher turn)."
- synonyms:
- stock turn
- inventory turnover
- sell-through
- term: New vs Returning Customer
- description: "A classification of whether a purchase was a customer's
first ('order_facts.is_first_purchase' is Yes) or if they are a repeat
buyer ('user_order_facts.repeat_customer' is Yes)."
- synonyms:
- customer type
- first-time buyer
- additional_descriptions:
- text: The user is typically a Sales Manager, Product Manager, or
Marketing Analyst. They need to understand performance trends, build
customer lists for campaigns, and analyze product sales.
- text: This agent can answer complex questions by joining data about
sales line items, products, users, inventory, and distribution centers.
A seguir
Depois de definir os campos estruturados e as instruções do sistema que compõem o contexto criado, é possível fornecer esse contexto à API Análise conversacional em uma das seguintes chamadas:
- Criar um agente de dados persistente: inclua o contexto criado no objeto
published_contextno corpo da solicitação para configurar um comportamento do agente que persista em várias conversas. Para mais informações, consulte Criar um agente de dados (HTTP) ou Configurar o contexto para chat com ou sem estado (SDK do Python). - Envio de uma solicitação sem estado: forneça o contexto criado no objeto
inline_contextem uma solicitação de chat para definir o comportamento do agente para essa chamada de API específica. Para mais informações, consulte Criar uma conversa sem estado com várias interações (HTTP) ou Usar a API para fazer perguntas (SDK do Python). - Enviar uma solicitação de dados de consulta: para fontes de dados de banco de dados, forneça o ID do conjunto de contexto do contexto criado no objeto
agent_context_referencena solicitação de dados de consulta. Para mais informações, consulte Definir o contexto do agente de dados para fontes de dados de banco de dados.