Receber respostas e acompanhamentos

Nesta página, apresentamos a pesquisa com resposta e acompanhamento para o Agent Search e mostramos como implementá-la em apps de pesquisa personalizados usando chamadas de método.

A pesquisa com resposta e acompanhamentos é baseada no método de resposta. O método de resposta substitui os recursos de resumo do método search mais antigo e todos os recursos do método converse, que foi descontinuado. O método de resposta também tem alguns recursos adicionais importantes, como a capacidade de processar consultas complexas.

Recursos do método de resposta

Os principais recursos do método de resposta são os seguintes:

  • A capacidade de gerar respostas para consultas complexas. Por exemplo, o método answer pode dividir consultas compostas, como as seguintes, em várias consultas menores para retornar resultados melhores que são usados para gerar respostas melhores:

    • "Qual é a receita do Google Cloud e do Google Ads em 2024?"
    • "Quantos anos após a fundação o Google levou para atingir US$ 1 bilhão em receita?"

  • A capacidade de combinar a pesquisa e a geração de respostas em uma conversa de vários turnos, chamando o método de resposta em cada turno.

  • A capacidade de parear com o método de pesquisa para reduzir a latência de pesquisa. É possível chamar o método de pesquisa e o método de resposta separadamente e renderizar os resultados da pesquisa e as respostas em diferentes iframes em momentos distintos. Isso significa que você pode mostrar aos usuários resultados da pesquisa (os 10 links azuis) em milissegundos. Não é necessário esperar que as respostas sejam geradas antes de mostrar os resultados da pesquisa.

Os recursos de resposta e acompanhamento podem ser divididos em três fases da consulta, pesquisa e resposta:

Quando usar a resposta e quando usar a pesquisa

A Pesquisa de Agentes tem dois métodos usados para consultar apps. Eles têm recursos diferentes, mas que se sobrepõem.

Use o método answer quando:

  • Você quer uma resposta (ou resumo) gerada com IA dos resultados da pesquisa.

  • Você quer uma pesquisa com várias interações, ou seja, que mantenha o contexto para permitir perguntas complementares.

Use o método search nos seguintes casos:

  • Você só precisa de resultados da pesquisa, não de uma resposta gerada.

  • Você tem uma das seguintes opções:

    • Dados de mídia ou de saúde
    • Seus próprios embeddings
    • Controles de sinônimos ou redirecionamento
    • Atributos
    • Códigos de país do usuário

  • Você precisa procurar os dados no seu repositório de dados genérico.

Use os métodos de resposta e pesquisa juntos quando:

  • Você quer retornar mais de dez resultados da pesquisa e quer uma resposta gerada.

  • Você tem problemas de latência e quer retornar e exibir os resultados da pesquisa rapidamente antes que a resposta gerada seja retornada.

Recursos da fase de consulta

O recurso de respostas e acompanhamentos é compatível com o processamento de consultas em linguagem natural.

Nesta seção, descrevemos e ilustramos as várias opções de reformulação e classificação de consultas.

Reformulação de consultas

A reformulação de consultas fica ativada por padrão. Esse recurso escolhe a melhor maneira de reformular as consultas automaticamente para melhorar os resultados da pesquisa. Esse recurso também pode lidar com consultas que não exigem reformulação.

  • Divida consultas complexas em várias consultas menores e realize subconsultas síncronas.

    Por exemplo: uma consulta complexa é dividida em quatro consultas menores e mais simples.

    Entrada do usuário Subconsultas criadas com base na consulta complexa
    Quais empregos e hobbies Andy Ram e Arnaud Clément têm em comum?
    • Profissão de Andie Ram
    • Arnaud Clément profissão
    • Hobby de Andie Ram
    • Hobby de Arnaud Clément

  • Sintetizar consultas multiturno para que as perguntas complementares sejam sensíveis ao contexto e com estado.

    Por exemplo: as consultas sintetizadas com base na entrada do usuário em cada turno podem ser assim:

    Entrada do usuário Consulta sintetizada
    Turno 1: laptops para a escola laptops para escola
    Turno 2: não é um Mac laptops para escola que não sejam mac
    Turno 3: tela maior e também preciso de um teclado e mouse sem fio laptops com tela maior para escola que não sejam Mac com teclado e mouse sem fio
    Turno 4: e uma mochila para ele laptops com tela maior para a escola que não sejam Mac com teclado e mouse sem fio e uma mochila para eles

  • Simplifique consultas longas para melhorar a recuperação (requer a opção Respostas generativas).

    Por exemplo: uma consulta longa é reduzida para uma consulta típica.

    Entrada do usuário Consulta simplificada
    Estou tentando descobrir por que o botão "Adicionar ao carrinho" no nosso site não está funcionando corretamente. Parece que, quando um usuário clica no botão, o item não é adicionado ao carrinho e ele recebe uma mensagem de erro. Verifiquei o código e ele parece estar correto, então não sei qual é o problema. Você pode me ajudar a resolver esse problema? O botão "Adicionar ao carrinho" não está funcionando no site.

  • Realizar raciocínio em várias etapas

    O raciocínio em várias etapas é baseado no paradigma ReAct (raciocínio + ação), que permite que os LLMs resolvam tarefas complexas usando o raciocínio em linguagem natural. Por padrão, o número máximo de etapas é cinco.

    Exemplo:

    Entrada do usuário Duas etapas para gerar a resposta
    Quantos anos após a fundação o Google atingiu US$ 1 bilhão em receita? Etapa 1:
    [Pensamento]: preciso saber quando o Google foi fundado para consultar a receita desde então.
    [Ação] Pesquisa: Quando o Google foi fundado?[Observar resultados da pesquisa]: "1998"

    Etapa 2:
    [Pensamento]: Agora preciso pesquisar a receita anual do Google desde 1998 e descobrir quando ela ultrapassou 1 bilhão pela primeira vez.
    [Ação] Pesquisar: receita do Google desde 1998
    [Observar os resultados da pesquisa] Receita do Google em 1998, receita do Google em 1999…
    [Resposta]: O Google alcançou mais de 1 bilhão de dólares em receita em 2003 [1], 5 anos após sua fundação em 1998 [2].

    O raciocínio em várias etapas exige que a opção Respostas generativas esteja ativada.

Classificação de consultas

As opções de classificação de consultas são para identificar consultas adversas e consultas que não buscam respostas. Por padrão, as opções de classificação de consultas estão desativadas.

Para mais informações sobre consultas adversárias e que não buscam respostas, consulte Ignorar consultas adversárias e Ignorar consultas que não buscam resumos.

Recursos da fase de pesquisa

Para pesquisa, o método de resposta tem as mesmas opções que o método de pesquisa. Exemplo:

Recursos da fase de resposta

Durante a fase de resposta, quando as respostas são geradas com base nos resultados da pesquisa, é possível ativar os mesmos recursos do método de pesquisa. Exemplo:

Outros recursos da fase de resposta que não estão disponíveis no método de pesquisa são:

  • Receber uma pontuação de suporte para cada declaração (frase na resposta gerada). Uma pontuação de suporte é um valor de ponto flutuante no intervalo [0,1] que indica o nível de embasamento da declaração nos dados do repositório de dados. Para mais informações, consulte Retornar pontuações de suporte de embasamento.

  • Recebendo uma pontuação de suporte agregada para a resposta. A pontuação de suporte indica o quanto a resposta está fundamentada nos dados do repositório de dados. Para mais informações, consulte Retornar pontuações de suporte de embasamento.

  • Retorne apenas respostas bem fundamentadas. É possível retornar apenas as respostas que atendem a um determinado limite de pontuação de suporte. Para mais informações, consulte Mostrar apenas respostas bem fundamentadas.

  • Escolha se quer retornar perguntas relacionadas. As perguntas relacionadas são sugestões que os usuários podem escolher em vez de digitar as próprias perguntas.

  • Adicione informações de personalização às consultas para que as respostas possam ser personalizadas para usuários individuais. Para mais informações, consulte Personalizar respostas.

Para receber respostas multimodais que incluem gráficos ou imagens além de texto, as seguintes opções estão disponíveis:

  • Receber respostas que incluem gráficos que mostram os dados contidos nas respostas. Para mais informações, consulte Gerar gráficos para respostas.

  • Recuperando imagens do repositório de dados. Se o repositório de dados tiver imagens, o método de resposta poderá retornar uma imagem na resposta. As imagens do repositório de dados também podem ser retornadas em referências se as citações forem solicitadas. Para mais informações, consulte Recuperar imagens do repositório de dados.

Antes de começar

Dependendo do tipo de app, atenda aos seguintes requisitos:

  • Se você tiver um app de pesquisa estruturada, não estruturada ou de site, ative as seguintes opções:

    • Recursos da edição Enterprise: dão acesso aos principais recursos de respostas generativas. Isso inclui todos os recursos de geração de respostas, exceto os recursos de respostas generativas avançadas, como perguntas relacionadas, simplificação de consultas, consultas de vários turnos e respostas multimodais que retornam imagens e gráficos.
    • Respostas generativas: dão acesso aos recursos avançados de respostas generativas que exigem raciocínio em várias etapas, simplificação de consultas, consultas com várias interações, perguntas relacionadas e respostas multimodais que retornam imagens e gráficos.

  • Além disso, se você tiver um repositório de dados de pesquisa de site, ative a indexação avançada de sites.

Pesquisa e resposta (básico)

O comando a seguir mostra como chamar o método answer e retornar uma resposta gerada e uma lista de resultados da pesquisa, com links para as fontes.

Esse comando mostra apenas a entrada necessária. As opções são deixadas nos padrões.

REST

Para pesquisar e receber resultados com uma resposta gerada, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"}
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Compare os bancos de dados do BigQuery e do Spanner".

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandos da fase de consulta

Esta seção mostra como especificar opções para a fase de consulta da chamada de método answer.

Pesquisa e resposta (reformulação desativada)

O comando a seguir mostra como chamar o método answer e retornar uma resposta gerada e uma lista de resultados da pesquisa. A resposta pode ser diferente da anterior porque a opção de reformulação está desativada.

REST

Para pesquisar e receber resultados com uma resposta gerada sem aplicar a reformulação da consulta, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
           "queryRephraserSpec": {
              "disable": true
        }
    }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Compare os bancos de dados do BigQuery e do Spanner".

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Pesquisar e responder (especificar o número máximo de etapas)

O comando a seguir mostra como chamar o método answer e retornar uma resposta gerada e uma lista de resultados da pesquisa. A resposta é diferente das anteriores porque o número de etapas de reformulação foi aumentado.

REST

Para pesquisar e receber resultados com uma resposta gerada que permite até cinco etapas de reformulação, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
            "queryRephraserSpec": {
                "maxRephraseSteps": MAX_REPHRASE
             }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Compare os bancos de dados do BigQuery e do Spanner".
    • MAX_REPHRASE: o número máximo de etapas de reformulação. O maior valor permitido é 5. Se não for definido ou se for definido como menos de 1, o valor será o padrão, 1.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Pesquisar e responder com classificação de consulta

O comando a seguir mostra como chamar o método answer para perguntar se uma consulta é contraditória, não busca respostas ou nenhuma das duas.

A resposta inclui o tipo de classificação da consulta, mas a resposta em si não é afetada pela classificação. Se você quiser mudar o comportamento da resposta de acordo com o tipo de consulta, faça isso na fase de resposta. Consulte Ignorar consultas adversárias e Ignorar consultas que não buscam resumos.

REST

Para determinar se uma consulta é contraditória ou não busca uma resposta, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
            "queryClassificationSpec": {
                "types": ["QUERY_CLASSIFICATION_TYPE"]
             }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "olá".
    • QUERY_CLASSIFICATION_TYPE: os tipos de consulta que você quer identificar: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY ou ambos.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandos da fase de pesquisa: pesquisar e responder com opções de resultados da pesquisa

Nesta seção, mostramos como especificar opções para a parte da fase de pesquisa da chamada do método answer, como definir o número máximo de documentos retornados, otimizar e filtrar, além de como receber uma resposta quando você fornece seus próprios resultados de pesquisa.

O comando a seguir mostra como chamar o método answer e especificar várias opções de como o resultado da pesquisa é retornado. Os resultados da pesquisa são independentes da resposta.

REST

Para definir várias opções relacionadas a quais resultados da pesquisa são retornados e como, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
          "searchSpec": {
          "searchParams": {
            "maxReturnResults": MAX_RETURN_RESULTS,
            "filter": "FILTER",
            "boostSpec": BOOST_SPEC,
            "orderBy": "ORDER_BY",
            "searchResultMode": SEARCH_RESULT_MODE
           }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "Compare os bancos de dados do BigQuery e do Spanner".
    • MAX_RETURN_RESULTS: o número de resultados da pesquisa a serem retornados. O valor padrão é 10. O valor máximo é 25.
    • FILTER: o filtro especifica quais documentos são consultados. Se os metadados de um documento atenderem à especificação do filtro, o documento será consultado. Para mais informações, incluindo a sintaxe de filtro, consulte Filtrar a pesquisa personalizada para dados estruturados ou não estruturados.
    • BOOST_SPEC: a especificação de otimização permite otimizar determinados documentos nos resultados da pesquisa, o que pode afetar a resposta. Para mais informações, incluindo a sintaxe da especificação de otimização, consulte Otimizar resultados da pesquisa.
    • ORDER_BY: a ordem em que os documentos são retornados. Os documentos podem ser ordenados por um campo em um objeto Document. A expressão orderBy diferencia maiúsculas de minúsculas. Se esse campo não for reconhecido, um INVALID_ARGUMENT será retornado.
    • SEARCH_RESULT_MODE: especifica o modo de resultado da pesquisa: DOCUMENTS ou CHUNKS. Para mais informações, consulte Analisar e dividir documentos e ContentSearchSpec. Esse campo está disponível apenas na versão v1alpha da API.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandos da fase de resposta

Nesta seção, mostramos como personalizar a chamada de método answer. É possível combinar as seguintes opções conforme necessário.

Ignorar consultas adversárias e consultas que não buscam respostas

O comando a seguir mostra como evitar responder a consultas adversas e consultas que não buscam respostas ao chamar o método answer.

REST

Para pular respostas a consultas que são adversárias ou que não buscam respostas, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "ignoreAdversarialQuery": true,
           "ignoreNonAnswerSeekingQuery": true
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Mostrar apenas respostas relevantes

A Pesquisa de Agentes pode avaliar a relevância dos resultados para uma consulta. Se nenhum resultado for considerado suficientemente relevante, em vez de gerar uma resposta com base em resultados não relevantes ou minimamente relevantes, você poderá retornar uma resposta substituta: "We do not have a summary for your query."

O comando a seguir mostra como retornar a resposta de fallback no caso de resultados irrelevantes ao chamar o método answer.

REST

Para retornar uma resposta substituta se nenhum resultado relevante for encontrado, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "ignoreLowRelevantContent": true
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Retornar pontuações de suporte de embasamento

O comando a seguir mostra como retornar pontuações de suporte de embasamento para respostas e declarações.

Para informações gerais sobre o embasamento na Vertex AI, consulte Verificar o embasamento com RAG. O método groundingConfigs.check é chamado pelo método answer.

REST

Para retornar uma pontuação de suporte para cada declaração (frase na resposta) e uma pontuação de suporte agregada para a resposta, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "groundingSpec": {
           "includeGroundingSupports": true,
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.

Mostrar apenas respostas bem fundamentadas

O comando a seguir mostra como retornar apenas as respostas consideradas bem fundamentadas no corpus, as informações no repositório de dados. As respostas sem embasamento são filtradas.

Você escolhe um limite de nível baixo ou alto para a pontuação de suporte de embasamento. Em seguida, a resposta só será retornada se atingir ou exceder esse nível. Você pode testar os dois limites de filtro e sem limite para determinar qual nível de filtro provavelmente fornecerá os melhores resultados para seus usuários.

Para informações gerais sobre o embasamento na Vertex AI, consulte Verificar o embasamento com RAG. O método groundingConfigs.check é chamado pelo método answer.

REST

Para retornar uma resposta somente se ela atender a um limite de pontuação de suporte, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "groundingSpec": {
           "filteringLevel": "FILTER_LEVEL"
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • FILTER_LEVEL: uma enumeração para filtrar respostas com base na pontuação de embasamento. As opções são: FILTERING_LEVEL_LOW e FILTERING_LEVEL_HIGH. Se filteringLevel não for incluído, nenhum filtro de pontuação de suporte será aplicado à resposta.

Especificar o modelo de resposta

O comando a seguir mostra como mudar a versão do modelo usada para gerar respostas.

Para informações sobre os modelos compatíveis, consulte Versões e ciclo de vida do modelo de geração de respostas.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "modelSpec": {
              "modelVersion": "MODEL_VERSION",
           }
         }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • MODEL_VERSION: a versão do modelo que você quer usar para gerar a resposta. Para mais informações, consulte Versões e ciclo de vida do modelo de geração de respostas.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Especificar um preâmbulo personalizado

O comando a seguir mostra como definir um preâmbulo para a resposta gerada. Um preâmbulo contém instruções em linguagem natural para personalizar a resposta. Você pode solicitar personalizações como tamanho, nível de detalhes, estilo de saída (como "simples"), idioma de saída, foco da resposta e formato (como tabelas, marcadores e XML). Por exemplo, um preâmbulo pode ser "Explique como se eu fosse uma criança de dez anos".

O preâmbulo pode ter um efeito significativo na qualidade da resposta gerada. Para saber o que escrever em preâmbulos e ver exemplos de bons preâmbulos, consulte Sobre preâmbulos personalizados.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "promptSpec": {
               "preamble": "PREAMBLE",
           }
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • PREAMBLE: uma instrução em linguagem natural para personalizar a resposta. Por exemplo, tente show the answer format in an ordered list ou give a very detailed answer.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

O método de resposta pode sugerir perguntas relacionadas, que os usuários podem escolher em vez de inserir as próprias perguntas. Por exemplo, quando você pergunta "Qual é a melhor época do ano para passar férias no México?", além de responder à pergunta, o método de resposta pode sugerir outras perguntas que você pode fazer, como "Qual é o mês mais barato para passar férias no México?" e "Quais são os meses turísticos no México?".

Para receber perguntas relacionadas, é preciso especificar a inclusão delas em cada consulta, e elas são retornadas como uma matriz de strings na resposta.

Se a resposta for ignorada e um campo answerSkippedReasons for retornado na resposta, as perguntas relacionadas não serão incluídas na saída.

Antes de começar

Verifique se você ativou a opção Respostas generativas para o app.

Procedimento

O comando a seguir mostra como solicitar que perguntas relacionadas sejam incluídas na resposta.

REST

Para receber perguntas relacionadas com uma resposta gerada:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "relatedQuestionsSpec": { "enable": true }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa. Por exemplo, "que tipos de dados posso importar para a Pesquisa de Agentes?".

Incluir citações

O comando a seguir mostra como solicitar que as citações sejam incluídas na resposta.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "includeCitations": INCLUDE_CITATIONS
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • INCLUDE_CITATIONS: especifica se os metadados de citação devem ser incluídos na resposta. O valor padrão é false.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Definir o código de idioma da resposta

O comando a seguir mostra como definir o código de idioma para as respostas.

REST

Para gerar uma resposta usando um modelo diferente do padrão, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "answerLanguageCode": "ANSWER_LANGUAGE_CODE"
           }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • ANSWER_LANGUAGE_CODE: um código de idioma para a resposta. Use tags de idioma definidas por BCP47: tags para identificar idiomas.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
        # Use the 2026 stable production model for answer generation
        model_version="gemini-2.5-flash/answer_gen/stable",
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
        user_pseudo_id="user-pseudo-id",  # Optional: Add user pseudo-identifier for queries.
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Personalizar respostas

Se houver informações específicas sobre o usuário disponíveis, como dados em um perfil, você poderá especificá-las no objeto endUserMetadata para que os resultados da consulta sejam personalizados para o usuário.

Por exemplo, se um usuário conectado estiver procurando informações sobre como fazer upgrade de um smartphone, as informações do perfil dele, como o modelo atual do smartphone e o plano de celular, fornecem informações que podem personalizar a resposta gerada.

Para adicionar informações pessoais sobre o usuário que está fazendo uma consulta e gerar uma resposta que leve em conta essas informações, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
-d '{
    "query": { "text": "QUERY"},
    "endUserSpec": {
       "endUserMetadata": [
         {
           "chunkInfo": {
              "content": "PERSONALIZED_INFO",
              "documentMetadata":  { "title": "INFO_DESCRIPTION"}
           }
         }
       ]
    }
  }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • PERSONALIZATION_INFO: uma string que contém informações específicas do usuário que está fazendo a consulta. Por exemplo, This customer has a Pixel 6 Pro purchased over a period of 24-months starting 2023-01-15. This customer is on the Business Plus International plan. No payment is due at this time. O limite de comprimento para essa string é de 8.000 caracteres.
    • INFO_DESCRIPTION: uma string que descreve brevemente as informações de personalização, por exemplo, Customer profile data, including model, plan, and billing status.. O modelo usa essa descrição e as informações de personalização ao gerar uma resposta personalizada para a consulta.

Gerar gráficos para respostas

O método answer pode gerar gráficos e retorná-los como parte da resposta a uma consulta.

Você pode pedir especificamente que uma resposta inclua um gráfico, por exemplo, "Plote a taxa de crescimento anual dos pagamentos de pequenas empresas ao longo dos anos com os dados disponíveis". Se o sistema determinar que há dados suficientes, um gráfico será retornado. Normalmente, algum texto de resposta é retornado junto com o gráfico.

Além disso, se houver dados suficientes para criar um gráfico, o método de resposta poderá retornar um gráfico, mesmo que a consulta não tenha solicitado um explicitamente. Por exemplo, "Qual foi a melhoria nas pontuações do IDH associada ao maior acesso à água potável na década entre 2010 e 2020?"

Apenas um gráfico é gerado por resposta. No entanto, o gráfico pode ser composto, contendo outros gráficos menores. Exemplo de um gráfico composto:

gráfico composto com quatro gráficos menores

Limitação

As consultas precisam estar em inglês.

Cenários comuns de falha

Nem sempre você vai receber uma imagem com a resposta. Se não houver dados suficientes, não será possível gerar um valor.

Outros cenários de falha incluem falhas de execução de código e tempos limite. Se isso acontecer, reformule a consulta e tente de novo.

Antes de começar

Antes de executar uma consulta que pede gráficos gerados, faça o seguinte:

Procedimento

REST

Chame o método answer da seguinte maneira para retornar uma resposta que pode incluir um gráfico gerado com base nos dados do repositório de dados:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
          "model_spec": {
             "model_version": "MODEL_VERSION"
         },
          "multimodalSpec": {
             "imageSource": "IMAGE_SOURCE"
             }
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre em inglês que contém a pergunta ou consulta de pesquisa.
    • MODEL_VERSION: versão do modelo. Para mais informações, consulte Versões e ciclo de vida do modelo de geração de respostas.
    • IMAGE_SOURCE: uma enumeração para solicitar que a resposta inclua um gráfico gerado, FIGURE_GENERATION_ONLY, ou que a resposta possa incluir um gráfico gerado ou uma imagem existente dos repositórios de dados, ALL_AVAILABLE_SOURCES.

Recuperar imagens do repositório de dados

É possível escolher se as imagens do repositório de dados serão retornadas com a resposta e nas referências de citação. O repositório de dados precisa ser não estruturado com o analisador de layout ativado.

Para receber gráficos nas respostas, ative a opção Respostas generativas.

Quando imageSource é CORPUS_IMAGE_ONLY ou ALL_AVAILABLE_SOURCES, o método answer pode recuperar imagens do repositório de dados, conforme apropriado. No entanto, ativar essa opção não significa que as imagens sempre serão retornadas.

Você recebe uma imagem (no máximo) por resposta. As citações podem conter várias imagens.

Limitações

  • O app que você está usando precisa estar conectado a um repositório de dados não estruturados. Não é possível retornar imagens de sites ou de repositórios de dados estruturados.

  • As consultas precisam estar em inglês.

  • A anotação de imagem pelo analisador de layout precisa ser aplicada ao repositório de dados. Para informações sobre o analisador de layout, consulte Analisar e dividir documentos.

Procedimento

REST

Chame o método answer da seguinte maneira para retornar uma resposta que pode incluir uma imagem do repositório de dados:

  1. Execute o seguinte comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
          "model_spec": {
             "model_version": "MODEL_VERSION"
          },
          includeCitations: true,
          "multimodalSpec": {
             "imageSource": "IMAGE_SOURCE"
             }
        }
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa de agentes que você quer consultar.
    • QUERY: uma string de texto livre em inglês que contém a pergunta ou consulta de pesquisa.
    • MODEL_VERSION: versão do modelo. Para mais informações, consulte Versões e ciclo de vida do modelo de geração de respostas.
    • IMAGE_SOURCE: uma enumeração para solicitar que a resposta inclua uma imagem do repositório de dados, CORPUS_IMAGE_ONLY, ou que a resposta possa incluir uma imagem do repositório de dados ou um gráfico gerado, ALL_AVAILABLE_SOURCES.

Comandos para perguntas complementares

As perguntas complementares são consultas multiturno. Depois da primeira consulta em uma sessão de acompanhamento, as "rodadas" seguintes consideram as interações anteriores. Com as perguntas complementares, o método de resposta também pode sugerir perguntas relacionadas, que os usuários podem escolher em vez de inserir as próprias perguntas complementares. Para receber sugestões de perguntas relacionadas, ative a opção Respostas generativas.

Todos os recursos de resposta e acompanhamento descritos nas seções anteriores, como citações, filtros, SafeSearch, ignorar determinados tipos de consultas e usar um preâmbulo para personalizar respostas, podem ser aplicados junto com os acompanhamentos.

Exemplo de uma sessão de acompanhamento

Veja a seguir um exemplo de sessão com acompanhamentos. Suponha que você queira saber sobre férias no México:

  • Interação 1:

    • Você:Qual é a melhor época do ano para passar as férias no México?

    • Resposta com acompanhamento:a melhor época para passar férias no México é durante a estação seca, que vai de novembro a abril.

  • Interação 2:

    • Você:Qual é a taxa de câmbio?

    • Resposta com acompanhamento:1 USD equivale a aproximadamente 17,65 pesos mexicanos.

  • Interação 3:

    • Você:Qual é a temperatura média em dezembro?

    • Resposta com acompanhamento:a temperatura média varia de 21 a 25 °C. A média de Cancún é de aproximadamente 25 °C.

Sem as perguntas complementares, sua pergunta "Qual é a taxa de câmbio?" não seria respondida porque a pesquisa normal não saberia que você queria a taxa de câmbio mexicana. Da mesma forma, sem as perguntas de acompanhamento, não haveria o contexto necessário para fornecer as temperaturas especificamente para o México.

Sobre sessões

Para entender como os acompanhamentos funcionam na Pesquisa de Agentes, é preciso entender as sessões.

Uma sessão é composta por consultas de texto fornecidas por um usuário e respostas fornecidas pela Agent Search.

Esses pares de consulta e resposta às vezes são chamados de turnos. No exemplo anterior, o segundo turno é composto por "Qual é a taxa de câmbio?" e "1 USD é igual a aproximadamente 17,65 pesos mexicanos".

As sessões são armazenadas com o app. No app, uma sessão é representada pelo recurso de sessão.

Além de conter as mensagens de consulta e resposta, o recurso de sessão tem:

  • Um nome exclusivo (o ID da sessão).

  • Um estado (em andamento ou concluído).

  • Um pseudoid do usuário, que é um ID de visitante que rastreia o usuário. Ele pode ser atribuído de forma programática. Quando mapeado para o pseudoid do usuário nos eventos de usuário do app, o modelo pode ajudar a veicular resultados personalizados para o usuário.

  • Um horário de início e um de término.

  • Uma rodada, que é um par de consulta e resposta.

Antes de começar

Antes de executar uma consulta que solicita perguntas complementares, verifique se você ativou a opção Respostas generativas para o app.

Armazenar informações da sessão e receber respostas

É possível usar a linha de comando para gerar respostas de pesquisa e armazená-las, junto com cada consulta em uma sessão.

REST

Para usar a linha de comando para criar uma sessão e gerar respostas com base na entrada do usuário, siga estas etapas:

  1. Especifique o app em que você quer armazenar a sessão:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions" \
  -d '{
        "userPseudoId": "USER_PSEUDO_ID"
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .

    • APP_ID: o ID do app de pesquisa do agente.

    • USER_PSEUDO_ID: uma string codificada em UTF-8, que atua como um identificador pseudonimizado exclusivo que rastreia os usuários. Ele pode ter no máximo 128 caracteres. O Google recomenda o uso desse campo porque ele melhora o desempenho do modelo e a qualidade da personalização. É possível usar um cookie HTTP para esse campo, que identifica exclusivamente um visitante em um único dispositivo. Algumas considerações importantes:

      • Esse identificador não muda quando o visitante faz login ou sai de um site.
      • Esse campo não pode ser definido com o mesmo identificador para vários usuários. Caso contrário, o mesmo ID do usuário pode combinar históricos de eventos de usuários diferentes e degradar a qualidade do modelo.
      • Esse campo não pode incluir informações de identificação pessoal (PII).
      • Para uma determinada solicitação de pesquisa ou navegação, esse campo precisa ser mapeado para o campo userPseudoId correspondente nos eventos do usuário.

      Para obter mais informações, consulte userPseudoId.

    Exemplo de comando e resultado

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/sessions"
-d '{
"userPseudoId": "test_user"
}'

    
{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_user",
  "startTime": "2024-09-13T18:47:10.465311Z",
  "endTime": "2024-09-13T18:47:10.465311Z"
}

  2. Anote o ID da sessão, os números no final do campo name: na resposta JSON. No resultado de exemplo, o ID é 5386462384953257772. Você vai precisar desse ID na próxima etapa.

  3. Gere uma resposta e adicione-a a uma sessão no seu app:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "session": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
          "searchSpec":{ "searchParams": {"filter": "FILTER"} }
}'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • SESSION_ID: o ID da sessão que você criou na etapa 1. Esses são os dígitos no final do campo name:, anotados na etapa 2. Para uma sessão, use o mesmo ID de sessão em cada turno.
    • FILTER: um campo de texto para filtrar a pesquisa usando uma expressão de filtro. O valor padrão é uma string vazia. A maneira de criar o filtro varia de acordo com o tipo de dados: não estruturados com metadados, estruturados ou de site. Para mais informações, consulte Filtrar a pesquisa personalizada para dados estruturados ou não estruturados e Filtrar a pesquisa no site.

    Exemplo de comando e resultado

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:answer"
-d '{
"query": { "text": "Compare bigquery with spanner database?"},
"session":  "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
}'
    
    
{
  "answer": {
    "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943/answers/4861507376861383072",
    "state": "SUCCEEDED",
    "answerText": "BigQuery and Spanner are both powerful tools that can be used together to handle transactional and analytical workloads. Spanner is a fully managed relational database optimized for transactional workloads, while BigQuery is a serverless data warehouse designed for business agility. Spanner provides seamless replication across regions in Google Cloud and processes over 1 billion requests per second at peak. BigQuery analyzes over 110 terabytes of data per second. Users can leverage federated queries to read data from Spanner and write to a native BigQuery table. \n",
    "steps": [
      {
        "state": "SUCCEEDED",
        "description": "Rephrase the query and search.",
        "actions": [
          {
            "searchAction": {
              "query": "Compare bigquery with spanner database?"
            },
            "observation": {
              "searchResults": [
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/ecc0e7547253f4ca3ff3328ce89995af",
                  "uri": "https://cloud.google.com/blog/topics/developers-practitioners/how-spanner-and-bigquery-work-together-handle-transactional-and-analytical-workloads",
                  "title": "How Spanner and BigQuery work together to handle transactional and analytical workloads | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "Using Cloud \u003cb\u003eSpanner\u003c/b\u003e and \u003cb\u003eBigQuery\u003c/b\u003e also allows customers to build their \u003cb\u003edata\u003c/b\u003e clouds using Google Cloud, a unified, open approach to \u003cb\u003edata\u003c/b\u003e-driven transformation ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/d7e238f73608a860e00b752ef80e2941",
                  "uri": "https://cloud.google.com/blog/products/databases/cloud-spanner-gets-stronger-with-bigquery-federated-queries",
                  "title": "Cloud Spanner gets stronger with BigQuery-federated queries | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "As enterprises compete for market share, their need for real-time insights has given rise to increased demand for transactional \u003cb\u003edatabases\u003c/b\u003e to support \u003cb\u003edata\u003c/b\u003e ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/e10a5a3c267dc61579e7c00fefe656eb",
                  "uri": "https://cloud.google.com/blog/topics/developers-practitioners/replicating-cloud-spanner-bigquery-scale",
                  "title": "Replicating from Cloud Spanner to BigQuery at scale | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "... \u003cb\u003eSpanner data\u003c/b\u003e into \u003cb\u003eBigQuery\u003c/b\u003e for analytics. In this post, you will learn how to efficiently use this feature to replicate large tables with high throughput ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                ...
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/8100ad36e1cac149eb9fc180a41d8f25",
                  "uri": "https://cloud.google.com/blog/products/gcp/from-nosql-to-new-sql-how-spanner-became-a-global-mission-critical-database",
                  "title": "How Spanner became a global, mission-critical database | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "... SQL \u003cb\u003evs\u003c/b\u003e. NoSQL dichotomy may no longer be relevant." The \u003cb\u003eSpanner\u003c/b\u003e SQL query processor, while recognizable as a standard implementation, has unique ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  },
  "session": {
    "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
    "state": "IN_PROGRESS",
    "userPseudoId": "test_user",
    "turns": [
      {
        "query": {
          "queryId": "projects/123456/locations/global/questions/741830",
          "text": "Compare bigquery with spanner database?"
        },
        "answer": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943/answers/4861507376861383072"
      }
    ],
    "startTime": "2024-09-13T18:47:10.465311Z",
    "endTime": "2024-09-13T18:47:10.465311Z"
  },
  "answerQueryToken": "NMwKDAjFkpK3BhDU24uZAhIkNjZlNDIyZWYtMDAwMC0yMjVmLWIxMmQtZjQwMzA0M2FkYmNj"
}

  4. Repita a etapa 3 para cada nova consulta na sessão.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine


def create_session(
    project_id: str,
    location: str,
    engine_id: str,
    user_pseudo_id: str,
) -> discoveryengine.Session:
    """Creates a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        user_pseudo_id: A unique identifier for tracking visitors. For example, this
          could be implemented with an HTTP cookie, which should be able to
          uniquely identify a visitor on a single device.
    Returns:
        discoveryengine.Session: The newly created Session.
    """

    client = discoveryengine.SessionServiceClient()

    session = client.create_session(
        # The full resource name of the engine
        parent=f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}",
        session=discoveryengine.Session(user_pseudo_id=user_pseudo_id),
    )

    # Send Session name in `answer_query()`
    print(f"Session: {session.name}")
    return session

Acessar uma sessão do repositório de dados

O comando a seguir mostra como chamar o método get e receber uma sessão do repositório de dados.

REST

Para receber uma sessão de um repositório de dados, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID"

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • SESSION_ID: o ID da sessão que você quer receber.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine


def get_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> discoveryengine.Session:
    """Retrieves a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    """

    client = discoveryengine.SessionServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    session = client.get_session(name=name)

    print(f"Session details: {session}")
    return session

Excluir uma sessão do app

O comando a seguir mostra como chamar o método delete e excluir uma sessão do repositório de dados.

Por padrão, as sessões com mais de 60 dias são excluídas automaticamente. No entanto, se você quiser excluir uma sessão específica, por exemplo, se ela contiver conteúdo sensível, use essa chamada de API para excluí-la.

REST

Para excluir uma sessão de um app, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID"

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • SESSION_ID: o ID da sessão que você quer excluir.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine


def delete_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> None:
    """Deletes a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    """

    client = discoveryengine.SessionServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    client.delete_session(name=name)

    print(f"Session {name} deleted.")

Atualizar uma sessão

Há vários motivos para atualizar uma sessão. Por exemplo, para fazer o seguinte:

  • Marcar uma sessão como concluída
  • Mesclar as mensagens de uma sessão em outra
  • Mudar o pseudoid de um usuário

O comando a seguir mostra como chamar o método patch e atualizar uma sessão no repositório de dados.

REST

Para atualizar uma sessão de um app, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID?updateMask=state" \
  -d '{
        "state": "NEW_STATE"
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • SESSION_ID: o ID da sessão que você quer atualizar.
    • NEW_STATE: o novo valor do estado, por exemplo, IN_PROGRESS.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine
from google.protobuf import field_mask_pb2


def update_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> discoveryengine.Session:
    """Updates a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    Returns:
        discoveryengine.Session: The updated Session.
    """
    client = discoveryengine.SessionServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    session = discoveryengine.Session(
        name=name,
        state=discoveryengine.Session.State.IN_PROGRESS,  # Options: IN_PROGRESS, STATE_UNSPECIFIED
    )

    # Fields to Update
    update_mask = field_mask_pb2.FieldMask(paths=["state"])

    session = client.update_session(session=session, update_mask=update_mask)
    print(f"Updated session: {session.name}")
    return session

Listar todas as sessões

O comando a seguir mostra como chamar o método list e listar as sessões no repositório de dados.

REST

Para listar as sessões de um app, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions"

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.SessionServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response

Listar sessões de um usuário

O comando a seguir mostra como chamar o método list para listar sessões associadas a um usuário ou visitante.

REST

Para listar as sessões associadas a um usuário ou visitante, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions?filter=userPseudoId=USER_PSEUDO_ID"

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • USER_PSEUDO_ID: o pseudoid do usuário com as sessões que você quer listar.

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.SessionServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response

Listar sessões de um usuário e estado

O comando a seguir mostra como chamar o método list para listar sessões em um determinado estado para um usuário específico.

REST

Para listar as sessões de um usuário que estão abertas ou fechadas e associadas a um determinado usuário ou visitante, faça o seguinte:

  1. Execute o seguinte comando curl:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions?filter=userPseudoId=USER_PSEUDO_ID%20AND%20state=STATE"

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app de pesquisa do agente.
    • USER_PSEUDO_ID: o pseudoid do usuário com as sessões que você quer listar.
    • STATE: o estado da sessão: STATE_UNSPECIFIED (fechada ou desconhecida) ou IN_PROGRESS (aberta).

Python

Para mais informações, consulte a documentação de referência da API Agent Search Python.

Para autenticar na Pesquisa de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.SessionServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response