Crie um agente de dados com o SDK Python

Esta página mostra como usar o SDK Python para fazer pedidos à API Conversational Analytics. O exemplo de código Python demonstra como concluir as seguintes tarefas:

Autentique e configure o seu ambiente

Para usar o SDK Python para a API Conversational Analytics, siga as instruções no notebook do Colaboratory do SDK da API Conversational Analytics para transferir e instalar o SDK. Tenha em atenção que o método de transferência e os conteúdos do Colab do SDK estão sujeitos a alterações.

Depois de concluir as instruções de configuração no bloco de notas, pode usar o seguinte código para importar as bibliotecas de SDK necessárias, autenticar a sua Conta Google num ambiente do Colaboratory e inicializar um cliente para fazer pedidos de API:

from google.colab import auth
auth.authenticate_user()

from google.cloud import geminidataanalytics

data_agent_client = geminidataanalytics.DataAgentServiceClient()
data_chat_client = geminidataanalytics.DataChatServiceClient()

Especifique o projeto de faturação e as instruções do sistema

O seguinte exemplo de código Python define o projeto de faturação e as instruções do sistema que são usadas em todo o script:

# Billing project
billing_project = "my_project_name"

# System instructions
system_instruction = "Help the user analyze their data."

Substitua os valores de exemplo da seguinte forma:

  • my_project_name: o ID do seu projeto de faturação que tem as APIs necessárias ativadas.
  • Help the user analyze their data.: instruções do sistema para orientar o comportamento do agente e personalizá-lo de acordo com as suas necessidades de dados. Por exemplo, pode usar instruções do sistema para definir termos empresariais, controlar o comprimento das respostas ou definir a formatação de dados. Idealmente, defina instruções do sistema usando o formato YAML recomendado em Escreva instruções do sistema eficazes para fornecer orientações detalhadas e estruturadas.

Faça a associação a uma origem de dados

As secções seguintes mostram como definir os detalhes da ligação para as origens de dados do seu agente. O seu agente pode estabelecer ligação a dados no Looker, no BigQuery ou no Looker Studio.

Associe-se a dados do Looker

Os exemplos de código seguintes mostram como definir os detalhes de uma ligação a uma análise detalhada do Looker com chaves de API ou um token de acesso. Só pode estabelecer ligação a uma opção Explorar do Looker de cada vez com a API Conversational Analytics.

Chaves da API

Pode estabelecer uma ligação a uma instância do Looker com chaves da API Looker geradas, conforme descrito no artigo Autentique e ligue-se a uma origem de dados com a API Conversational Analytics.

looker_client_id = "my_looker_client_id"
looker_client_secret = "my_looker_client_secret"
looker_instance_uri = "https://my_company.looker.com"
lookml_model = "my_model"
explore = "my_explore"

looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

# Do not include the following line during agent creation
datasource_references.credentials = credentials

Substitua os valores de exemplo da seguinte forma:

  • my_looker_client_id: o ID de cliente da chave da API Looker gerada.
  • my_looker_client_secret: o segredo do cliente da chave da API Looker gerada.
  • https://my_company.looker.com: o URL completo da sua instância do Looker.
  • my_model: o nome do modelo do LookML que inclui a análise detalhada à qual quer estabelecer ligação.
  • my_explore: o nome da análise detalhada do Looker que quer que o agente de dados consulte.

Chave de acesso

Pode estabelecer uma ligação a uma instância do Looker através de um token de acesso, conforme descrito no artigo Autentique e ligue-se a uma origem de dados com a API Conversational Analytics.

looker_access_token = "my_access_token"
looker_instance_uri = "https://my_company.looker.com"
lookml_model = "my_model"
explore = "my_explore"

looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = looker_access_token

datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

# Do not include the following line during agent creation
datasource_references.credentials = credentials

Substitua os valores de exemplo da seguinte forma:

  • my_access_token: o valor access_token que gera para autenticar no Looker.
  • https://my_company.looker.com: o URL completo da sua instância do Looker.
  • my_model: o nome do modelo do LookML que inclui a análise detalhada à qual quer estabelecer ligação.
  • my_explore: o nome da análise detalhada do Looker que quer que o agente de dados consulte.

Estabeleça ligação aos dados do BigQuery

Com a API Conversational Analytics, não existem limites rígidos quanto ao número de tabelas do BigQuery às quais se pode ligar. No entanto, a ligação a um grande número de tabelas pode reduzir a precisão ou fazer com que exceda o limite de tokens de entrada do modelo.

O seguinte exemplo de código define uma associação a várias tabelas do BigQuery.

bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "my_project_id"
bigquery_table_reference.dataset_id = "my_dataset_id"
bigquery_table_reference.table_id = "my_table_id"

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "my_project_id_2"
bigquery_table_reference_2.dataset_id = "my_dataset_id_2"
bigquery_table_reference_2.table_id = "my_table_id_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "my_project_id_3"
bigquery_table_reference_3.dataset_id = "my_dataset_id_3"
bigquery_table_reference_3.table_id = "my_table_id_3"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference, bigquery_table_reference_2, bigquery_table_reference_3]

Substitua os valores de exemplo da seguinte forma:

  • my_project_id: o ID do Google Cloud projeto que contém o conjunto de dados e a tabela do BigQuery aos quais quer estabelecer ligação. Para estabelecer ligação a um conjunto de dados público, especifique bigquery-public-data.
  • my_dataset_id: o ID do conjunto de dados do BigQuery. Por exemplo, san_francisco.
  • my_table_id: o ID da tabela do BigQuery. Por exemplo, street_trees.

Estabeleça ligação aos dados do Looker Studio

O seguinte código de exemplo define uma ligação a uma origem de dados do Looker Studio.

studio_datasource_id = "my_datasource_id"

studio_references = geminidataanalytics.StudioDatasourceReference()
studio_references.datasource_id = studio_datasource_id

## Connect to your data source
datasource_references.studio.studio_references = [studio_references]

No exemplo anterior, substitua my_datasource_id pelo ID da origem de dados.

Configure o contexto para o chat com ou sem estado

A API Conversational Analytics suporta conversas com várias interações, que permitem aos utilizadores fazer perguntas de seguimento com base no contexto anterior. O seguinte exemplo de código Python demonstra como configurar o contexto para um chat com estado ou sem estado:

  • Chat com estado: Google Cloud armazena e gere o histórico de conversas. O chat com estado é inerentemente de várias interações, uma vez que a API retém o contexto das mensagens anteriores. Só tem de enviar a mensagem atual para cada turno.
  • Chat sem estado: a sua aplicação gere o histórico de conversas. Tem de incluir todo o histórico da conversa em cada nova mensagem. Para ver exemplos detalhados sobre como gerir conversas com várias interações no modo sem estado, consulte o artigo Crie uma conversa com várias interações sem estado.

Chat com estado

O seguinte exemplo de código configura o contexto para o chat com estado, em que Google Cloud armazena e gere o histórico de conversas. Também pode ativar opcionalmente a análise avançada com Python, incluindo a linha published_context.options.analysis.python.enabled = True no seguinte exemplo de código.

# Set up context for stateful chat
published_context = geminidataanalytics.Context()
published_context.system_instruction = system_instruction
published_context.datasource_references = datasource_references
# Optional: To enable advanced analysis with Python, include the following line:
published_context.options.analysis.python.enabled = True

Chat sem estado

O seguinte código de exemplo configura o contexto para o chat sem estado, em que tem de enviar o histórico de conversas completo com cada mensagem. Também pode ativar opcionalmente a análise avançada com Python, incluindo a linha inline_context.options.analysis.python.enabled = True no seguinte exemplo de código.

# Set up context for stateless chat
# datasource_references.looker.credentials = credentials
inline_context = geminidataanalytics.Context()
inline_context.system_instruction = system_instruction
inline_context.datasource_references = datasource_references
# Optional: To enable advanced analysis with Python, include the following line:
inline_context.options.analysis.python.enabled = True

Crie um agente de dados

O seguinte exemplo de código Python faz um pedido de API para criar um agente de dados, que pode usar para ter uma conversa sobre os seus dados. O agente de dados está configurado com a origem de dados, as instruções do sistema e o contexto especificados.

data_agent_id = "data_agent_1"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.name = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}" # Optional

request = geminidataanalytics.CreateDataAgentRequest(
    parent=f"projects/{billing_project}/locations/global",
    data_agent_id=data_agent_id, # Optional
    data_agent=data_agent,
)

try:
    data_agent_client.create_data_agent(request=request)
    print("Data Agent created")
except Exception as e:
    print(f"Error creating Data Agent: {e}")

No exemplo anterior, substitua o valor data_agent_1 por um identificador exclusivo do agente de dados.

Crie uma conversa

O seguinte exemplo de código Python faz um pedido de API para criar uma conversa.

# Initialize request arguments
data_agent_id = "data_agent_1"
conversation_id = "conversation_1"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f'projects/{billing_project}/locations/global/dataAgents/{data_agent_id}']
conversation.name = f"projects/{billing_project}/locations/global/conversations/{conversation_id}"

request = geminidataanalytics.CreateConversationRequest(
    parent=f"projects/{billing_project}/locations/global",
    conversation_id=conversation_id,
    conversation=conversation,
)

# Make the request
response = data_chat_client.create_conversation(request=request)

# Handle the response
print(response)

Substitua os valores de exemplo da seguinte forma:

  • data_agent_1: o ID do agente de dados, conforme definido no bloco de código de exemplo em Crie um agente de dados.
  • conversation_1: um identificador exclusivo da conversa.

Faça a gestão dos agentes de dados e das conversas

Os seguintes exemplos de código mostram como gerir os seus agentes de dados e conversas através da API Conversational Analytics. Pode realizar as seguintes tarefas:

Obtenha um agente de dados

O seguinte exemplo de código Python demonstra como fazer um pedido de API para obter um agente de dados que criou anteriormente.

# Initialize request arguments
data_agent_id = "data_agent_1"
request = geminidataanalytics.GetDataAgentRequest(
    name=f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}",
)

# Make the request
response = data_agent_client.get_data_agent(request=request)

# Handle the response
print(response)

No exemplo anterior, substitua o valor data_agent_1 pelo identificador exclusivo do agente de dados que quer obter.

Apresente agentes de dados

O código seguinte demonstra como listar todos os agentes de dados de um determinado projeto chamando o método list_data_agents. Para listar todos os agentes, tem de ter a autorização geminidataanalytics.dataAgents.list no projeto. Para mais informações sobre as funções de IAM que incluem esta autorização, consulte a lista de funções predefinidas.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
request = geminidataanalytics.ListDataAgentsRequest(
    parent=f"projects/{billing_project}/locations/global",
)

# Make the request
page_result = data_agent_client.list_data_agents(request=request)

# Handle the response
for response in page_result:
    print(response)

Substitua YOUR-BILLING-PROJECT pelo ID do seu projeto de faturação.

Apresente os agentes de dados acessíveis

O código seguinte demonstra como listar todos os agentes de dados acessíveis para um determinado projeto chamando o método list_accessible_data_agents.

billing_project = "YOUR-BILLING-PROJECT"
creator_filter = "YOUR-CREATOR-FILTER"
location = "global"
request = geminidataanalytics.ListAccessibleDataAgentsRequest(
    parent=f"projects/{billing_project}/locations/global",
    creator_filter=creator_filter
)

# Make the request
page_result = data_agent_client.list_accessible_data_agents(request=request)

# Handle the response
for response in page_result:
    print(response)

Substitua os valores de exemplo da seguinte forma:

  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • YOUR-CREATOR-FILTER: o filtro a aplicar com base no criador do agente de dados. Os valores possíveis incluem NONE (predefinição), CREATOR_ONLY e NOT_CREATOR_ONLY.

Atualize um agente de dados

O seguinte exemplo de código demonstra como atualizar um agente de dados chamando o método update_data_agent no recurso do agente de dados. O pedido requer um objeto DataAgent que inclua os novos valores dos campos que quer alterar e um parâmetro update_mask que recebe um objeto FieldMask para especificar os campos a atualizar.

Para atualizar um agente de dados, tem de ter a autorização de IAM geminidataanalytics.dataAgents.update no agente. Para mais informações sobre as funções de IAM que incluem esta autorização, consulte a lista de funções predefinidas.

data_agent_id = "data_agent_1"
billing_project = "YOUR-BILLING-PROJECT"
data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.name = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}"
data_agent.description = "Updated description of the data agent."

update_mask = field_mask_pb2.FieldMask(paths=['description', 'data_analytics_agent.published_context'])

request = geminidataanalytics.UpdateDataAgentRequest(
    data_agent=data_agent,
    update_mask=update_mask,
)

try:
    # Make the request
    data_agent_client.update_data_agent(request=request)
    print("Data Agent Updated")
except Exception as e:
    print(f"Error updating Data Agent: {e}")

Substitua os valores de exemplo da seguinte forma:

  • data_agent_1: o ID do agente de dados que quer atualizar.
  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • Updated description of the data agent.: uma descrição do agente de dados atualizado.

Defina a Política IAM para um agente de dados

Para partilhar um agente, pode usar o método set_iam_policy para atribuir funções da IAM a utilizadores num agente específico. O pedido inclui associações que especificam as funções que devem ser atribuídas a que utilizadores.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"
role = "roles/geminidataanalytics.dataAgentEditor"
users = "222larabrown@gmail.com, cloudysanfrancisco@gmail.com"

resource = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}"

# Construct the IAM policy
binding = policy_pb2.Binding(
    role=role,
    members= [f"user:{i.strip()}" for i in users.split(",")]
)

policy = policy_pb2.Policy(bindings=[binding])

# Create the request
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)

# Send the request
try:
    response = data_agent_client.set_iam_policy(request=request)
    print("IAM Policy set successfully!")
    print(f"Response: {response}")
except Exception as e:
    print(f"Error setting IAM policy: {e}")

Substitua os valores de exemplo da seguinte forma:

  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • data_agent_1: o ID do agente de dados para o qual quer definir a política IAM.
  • 222larabrown@gmail.com, cloudysanfrancisco@gmail.com: uma lista de emails de utilizadores separados por vírgulas aos quais quer conceder a função especificada.

Obtenha a Política IAM para um agente de dados

O seguinte código de exemplo demonstra como usar o método get_iam_policy para obter a política de IAM de um agente de dados. O pedido especifica o caminho do recurso do agente de dados.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"

resource = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )
try:
    response = data_agent_client.get_iam_policy(request=request)
    print("IAM Policy fetched successfully!")
    print(f"Response: {response}")
except Exception as e:
    print(f"Error setting IAM policy: {e}")

Substitua os valores de exemplo da seguinte forma:

  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • data_agent_1: o ID do agente de dados para o qual quer obter a Política IAM.

Elimine um agente de dados

O seguinte código de exemplo demonstra como usar o método delete_data_agent para eliminar um agente de dados de forma reversível. Quando elimina um agente de forma temporária, este é eliminado, mas ainda pode ser obtido no prazo de 30 dias. O pedido especifica o URL do recurso do agente de dados.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
data_agent_id = "data_agent_1"

request = geminidataanalytics.DeleteDataAgentRequest(
    name=f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}",
)

try:
    # Make the request
    data_agent_client.delete_data_agent(request=request)
    print("Data Agent Deleted")
except Exception as e:
    print(f"Error deleting Data Agent: {e}")

Substitua os valores de exemplo da seguinte forma:

  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • data_agent_1: o ID do agente de dados que quer eliminar.

Receba uma conversa

O seguinte código de exemplo demonstra como usar o método get_conversation para obter informações sobre uma conversa existente. O pedido especifica o caminho do recurso de conversa.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
conversation_id = "conversation_1"

request = geminidataanalytics.GetConversationRequest(
    name = f"projects/{billing_project}/locations/global/conversations/{conversation_id}"
)

# Make the request
response = data_chat_client.get_conversation(request=request)

# Handle the response
print(response)

Substitua os valores de exemplo da seguinte forma:

  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • conversation_1: o ID da conversa que quer obter.

Listar conversas

O seguinte exemplo de código demonstra como listar conversas para um determinado projeto chamando o método list_conversations. O pedido especifica o URL do recurso principal, que é o projeto e a localização (por exemplo, projects/my-project/locations/global).

Por predefinição, este método devolve as conversas que criou. Os administradores (utilizadores com a cloudaicompanion.topicAdminfunção do IAM) podem ver todas as conversas no projeto.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"
request = geminidataanalytics.ListConversationsRequest(
    parent=f"projects/{billing_project}/locations/global",
)

# Make the request
response = data_chat_client.list_conversations(request=request)

# Handle the response
print(response)

Substitua YOUR-BILLING-PROJECT pelo ID do projeto de faturação no qual ativou as APIs necessárias.

Liste mensagens numa conversa

O exemplo de código seguinte demonstra como usar o método list_messages para obter todas as mensagens numa conversa. O pedido especifica o caminho do recurso de conversa.

Para listar mensagens, tem de ter a autorização cloudaicompanion.topics.get na conversa.

billing_project = "YOUR-BILLING-PROJECT"
location = "global"

conversation_id = "conversation_1"

request = geminidataanalytics.ListMessagesRequest(
    parent=f"projects/{billing_project}/locations/global/conversations/{conversation_id}",
)

# Make the request
response = data_chat_client.list_messages(request=request)

# Handle the response
print(response)

Substitua os valores de exemplo da seguinte forma:

  • YOUR-BILLING-PROJECT: o ID do seu projeto de faturação.
  • conversation_1: o ID da conversa para a qual quer listar mensagens.

Use a API para fazer perguntas

Depois de criar um agente de dados e uma conversa, o seguinte código Python de exemplo envia uma consulta ao agente. O código usa o contexto que configurou para o chat com ou sem estado. A API devolve uma stream de mensagens que representam os passos que o agente realiza para responder à consulta.

Chat com estado

Envie um pedido de chat com estado com uma referência Conversation

Pode enviar um pedido de chat com estado ao agente de dados referindo-se a um recurso Conversation que criou anteriormente.

# Create a request that contains a single user message (your question)
question = "Which species of tree is most prevalent?"
messages = [geminidataanalytics.Message()]
messages[0].user_message.text = question

data_agent_id = "data_agent_1"
conversation_id = "conversation_1"

# Create a conversation_reference
conversation_reference = geminidataanalytics.ConversationReference()
conversation_reference.conversation = f"projects/{billing_project}/locations/global/conversations/{conversation_id}"
conversation_reference.data_agent_context.data_agent = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}"
# conversation_reference.data_agent_context.credentials = credentials

# Form the request
request = geminidataanalytics.ChatRequest(
    parent = f"projects/{billing_project}/locations/global",
    messages = messages,
    conversation_reference = conversation_reference
)

# Make the request
stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

# Handle the response
for response in stream:
    show_message(response)

Substitua os valores de exemplo da seguinte forma:

  • Which species of tree is most prevalent?: uma pergunta em linguagem natural para enviar ao agente de dados.
  • data_agent_1: o identificador exclusivo do agente de dados, conforme definido em Crie um agente de dados.
  • conversation_1: o identificador exclusivo da conversa, conforme definido em Criar uma conversa.

Chat sem estado

Os seguintes exemplos de código demonstram como enviar uma consulta ao agente de dados quando configurou o contexto para o chat sem estado. Pode enviar consultas sem estado referenciando um recurso DataAgent definido anteriormente ou usando o contexto inline no pedido.

Envie um pedido de chat sem estado com uma referência DataAgent

Pode enviar uma consulta ao agente de dados referindo-se a um recurso DataAgent que criou anteriormente.

# Create a request that contains a single user message (your question)
question = "Which species of tree is most prevalent?"
messages = [geminidataanalytics.Message()]
messages[0].user_message.text = question

data_agent_id = "data_agent_1"

data_agent_context = geminidataanalytics.DataAgentContext()
data_agent_context.data_agent = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}"
# data_agent_context.credentials = credentials

# Form the request
request = geminidataanalytics.ChatRequest(
    parent=f"projects/{billing_project}/locations/global",
    messages=messages,
    data_agent_context = data_agent_context
)

# Make the request
stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

# Handle the response
for response in stream:
    show_message(response)

Substitua os valores de exemplo da seguinte forma:

  • Which species of tree is most prevalent?: uma pergunta em linguagem natural para enviar ao agente de dados.
  • data_agent_1: o identificador exclusivo do agente de dados, conforme definido em Crie um agente de dados.

Envie um pedido de chat sem estado com contexto inline

O seguinte código de exemplo demonstra como usar o parâmetro inline_context para fornecer contexto diretamente no seu pedido de chat sem estado.

# Create a request that contains a single user message (your question)
question = "Which species of tree is most prevalent?"
messages = [geminidataanalytics.Message()]
messages[0].user_message.text = question

request = geminidataanalytics.ChatRequest(
    inline_context=inline_context,
    parent=f"projects/{billing_project}/locations/global",
    messages=messages,
)

# Make the request
stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

# Handle the response
for response in stream:
    show_message(response)

No exemplo anterior, substitua Which species of tree is most prevalent? por uma pergunta em linguagem natural para enviar ao agente de dados.

Crie uma conversa sem estado com várias interações

Para fazer perguntas de seguimento numa conversa sem estado, a sua aplicação tem de gerir o contexto da conversa enviando todo o histórico de mensagens com cada novo pedido. O exemplo seguinte mostra como criar uma conversa de várias interações referenciando um agente de dados ou usando o contexto inline para fornecer diretamente a origem de dados.

# List that is used to track previous turns and is reused across requests
conversation_messages = []

data_agent_id = "data_agent_1"

# Use data agent context
data_agent_context = geminidataanalytics.DataAgentContext()
data_agent_context.data_agent = f"projects/{billing_project}/locations/global/dataAgents/{data_agent_id}"
# data_agent_context.credentials = credentials

# Helper function for calling the API
def multi_turn_Conversation(msg):

    message = geminidataanalytics.Message()
    message.user_message.text = msg

    # Send a multi-turn request by including previous turns and the new message
    conversation_messages.append(message)

    request = geminidataanalytics.ChatRequest(
        parent=f"projects/{billing_project}/locations/global",
        messages=conversation_messages,
        # Use data agent context
        data_agent_context=data_agent_context,
        # Use inline context
        # inline_context=inline_context,
    )

    # Make the request
    stream = data_chat_client.chat(request=request, timeout=300 #custom timeout up to 600s)

    # Handle the response
    for response in stream:
      show_message(response)
      conversation_messages.append(response)

# Send the first turn request
multi_turn_Conversation("Which species of tree is most prevalent?")

# Send follow-up turn request
multi_turn_Conversation("Can you show me the results as a bar chart?")

No exemplo anterior, substitua os valores de amostra da seguinte forma:

  • data_agent_1: o identificador exclusivo do agente de dados, conforme definido no bloco de código de exemplo em Crie um agente de dados.
  • Which species of tree is most prevalent?: uma pergunta em linguagem natural para enviar ao agente de dados.
  • Can you show me the results as a bar chart?: uma pergunta de seguimento que se baseia na pergunta anterior ou a refina.

Defina funções auxiliares

O exemplo de código seguinte contém definições de funções auxiliares que são usadas nos exemplos de código anteriores. Estas funções ajudam a analisar a resposta da API e a apresentar os resultados.

from pygments import highlight, lexers, formatters
import pandas as pd
import requests
import json as json_lib
import altair as alt
import IPython
from IPython.display import display, HTML

import proto
from google.protobuf.json_format import MessageToDict, MessageToJson

def handle_text_response(resp):
  parts = getattr(resp, 'parts')
  print(''.join(parts))

def display_schema(data):
  fields = getattr(data, 'fields')
  df = pd.DataFrame({
    "Column": map(lambda field: getattr(field, 'name'), fields),
    "Type": map(lambda field: getattr(field, 'type'), fields),
    "Description": map(lambda field: getattr(field, 'description', '-'), fields),
    "Mode": map(lambda field: getattr(field, 'mode'), fields)
  })
  display(df)

def display_section_title(text):
  display(HTML('<h2>{}</h2>'.format(text)))

def format_looker_table_ref(table_ref):
 return 'lookmlModel: {}, explore: {}, lookerInstanceUri: {}'.format(table_ref.lookml_model, table_ref.explore, table_ref.looker_instance_uri)

def format_bq_table_ref(table_ref):
  return '{}.{}.{}'.format(table_ref.project_id, table_ref.dataset_id, table_ref.table_id)

def display_datasource(datasource):
  source_name = ''
  if 'studio_datasource_id' in datasource:
   source_name = getattr(datasource, 'studio_datasource_id')
  elif 'looker_explore_reference' in datasource:
   source_name = format_looker_table_ref(getattr(datasource, 'looker_explore_reference'))
  else:
    source_name = format_bq_table_ref(getattr(datasource, 'bigquery_table_reference'))

  print(source_name)
  display_schema(datasource.schema)

def handle_schema_response(resp):
  if 'query' in resp:
    print(resp.query.question)
  elif 'result' in resp:
    display_section_title('Schema resolved')
    print('Data sources:')
    for datasource in resp.result.datasources:
      display_datasource(datasource)

def handle_data_response(resp):
  if 'query' in resp:
    query = resp.query
    display_section_title('Retrieval query')
    print('Query name: {}'.format(query.name))
    print('Question: {}'.format(query.question))
    print('Data sources:')
    for datasource in query.datasources:
      display_datasource(datasource)
  elif 'generated_sql' in resp:
    display_section_title('SQL generated')
    print(resp.generated_sql)
  elif 'result' in resp:
    display_section_title('Data retrieved')

    fields = [field.name for field in resp.result.schema.fields]
    d = {}
    for el in resp.result.data:
      for field in fields:
        if field in d:
          d[field].append(el[field])
        else:
          d[field] = [el[field]]

    display(pd.DataFrame(d))

def handle_chart_response(resp):
  def _value_to_dict(v):
    if isinstance(v, proto.marshal.collections.maps.MapComposite):
      return _map_to_dict(v)
    elif isinstance(v, proto.marshal.collections.RepeatedComposite):
      return [_value_to_dict(el) for el in v]
    elif isinstance(v, (int, float, str, bool)):
      return v
    else:
      return MessageToDict(v)

  def _map_to_dict(d):
    out = {}
    for k in d:
      if isinstance(d[k], proto.marshal.collections.maps.MapComposite):
        out[k] = _map_to_dict(d[k])
      else:
        out[k] = _value_to_dict(d[k])
    return out

  if 'query' in resp:
    print(resp.query.instructions)
  elif 'result' in resp:
    vegaConfig = resp.result.vega_config
    vegaConfig_dict = _map_to_dict(vegaConfig)
    alt.Chart.from_json(json_lib.dumps(vegaConfig_dict)).display();

def show_message(msg):
  m = msg.system_message
  if 'text' in m:
    handle_text_response(getattr(m, 'text'))
  elif 'schema' in m:
    handle_schema_response(getattr(m, 'schema'))
  elif 'data' in m:
    handle_data_response(getattr(m, 'data'))
  elif 'chart' in m:
    handle_chart_response(getattr(m, 'chart'))
  print('\n')