Transmitir respostas usando a recuperação agêntica

Nesta página, apresentamos a recuperação com agente e explicamos como usá-la com o método stream answers.

Sobre a recuperação agêntica

A recuperação com agente usada com o método de respostas de stream pode gerar resultados melhores para determinados casos de uso, por exemplo, para ativar a recuperação de várias passagens em apps com vários repositórios de dados ou para personalizar a geração de respostas para diferentes classes de consultas.

Usar a recuperação com agente adiciona alguma complexidade aos seus apps, mas, em troca, oferece mais controle sobre os resultados.

A Pesquisa de agentes inclui um agente predefinido que pode ser usado para personalizar o comportamento de um mecanismo de pesquisa. Isso permite mais personalização do que está disponível na interface de configurações do app ou no método resposta de streaming sem recuperação de agente.

Pesquisa combinada com e sem recuperação agêntica

A recuperação com agente é particularmente útil para apps de pesquisa combinada. Sem a recuperação agêntica, a pesquisa usa uma distribuição de dados de passagem única que consulta todos os seus repositórios de dados de uma só vez. Em contraste, a recuperação com agentes permite a pesquisa de várias passagens. O agente planeja e executa pesquisas sequencialmente, escolhendo as melhores ferramentas para cada etapa. Ele pode combinar resultados de vários repositórios de dados da Pesquisa do agente e usar ferramentas como a Pesquisa Google e o Google Maps.

Por exemplo, você tem repositórios de dados separados para políticas globais da empresa e detalhes do escritório regional. Um usuário pergunta: "Quais são as regras de compliance do nosso escritório em Tóquio?"

  • Sem recuperação com agente: consulta simultaneamente o repositório de políticas e o repositório do escritório regional com a string de consulta completa. Isso pode retornar resultados fragmentados.

  • Com a recuperação de agente: o agente planeja a execução. Primeiro, ele recupera detalhes sobre o escritório de Tóquio na loja regional. Em seguida, usando esse contexto específico, ele realiza uma segunda pesquisa segmentada no repositório de políticas.

    O agente sintetiza essas descobertas em uma resposta única, coerente e mais precisa.

A recuperação agêntica também permite fazer consultas de pesquisa em vários turnos (perguntas de acompanhamento) em apps de pesquisa combinada. Sem a recuperação com agente, a pesquisa em várias etapas funciona apenas com apps de repositório de dados único. Para manter o contexto da conversa em várias interações, combine a recuperação agêntica com uma sessão da plataforma do agente (opcional).

Classificação de consultas personalizadas

Os métodos answer e streaming answer fornecem dois tipos de classificação de consulta: ADVERSARIAL_QUERY e NON_ANSWER_SEEKING_QUERY.

Com a recuperação generativa, você pode definir outros tipos de classificação para corresponder aos fluxos de trabalho da sua empresa. O sistema usa um classificador para determinar a intenção do usuário e encaminha a solicitação para a configuração de agente adequada.

Por exemplo, da consulta, você determina que a intenção é rastrear um pedido e especificou uma classificação TRACK_ORDER. Em vez de executar uma pesquisa genérica em todos os repositórios de dados, o sistema carrega um agente especializado equipado com as ferramentas e os dados necessários para recuperar o status do envio.

Como ativar e usar a recuperação com agentes

Há duas maneiras de ativar a recuperação com agente:

  • Agente de respostas predefinido do Google:se você já tiver um app de pesquisa na Pesquisa do agente, poderá ativar a recuperação de agente definindo enable_agent_invocation=true em solicitações de API ao enviar consultas para o app. Nesse caso, você mantém a configuração de veiculação de pesquisa atual.

  • App personalizado no modo de IA:ao criar um app da Pesquisa do agente, você define um tipo diferente de configuração de veiculação, a configuração de veiculação default_agent_answer. Isso também pode ser chamado de mecanismo personalizado do modo de IA, porque "app" e "mecanismo" são usados de forma intercambiável na Pesquisa do agente.

Antes de começar

Antes de usar a recuperação com agente, faça o seguinte:

Configurar um mecanismo de raciocínio para sessões de várias rodadas

Para manter o contexto da conversa em várias interações, crie um Agent Runtime na plataforma de agentes do Gemini Enterprise engine (também chamado de mecanismo de raciocínio).

Ao fazer uma solicitação streamAnswer, transmita o nome do recurso do tempo de execução do agente como o campo reasoningEngine na solicitação streamAnswer.

  1. Ative a plataforma de agente no seu projeto do Google Cloud .

  2. Crie uma instância do Agent Runtime (também chamada de mecanismo de raciocínio) usando a API REST do Agent Engine (ou o Kit de Desenvolvimento de Agente). A instância hospeda as sessões usadas pelo método streamAnswer.

    O nome do recurso da instância tem o formato:

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. Conceda ao agente de serviço do Discovery Engine acesso ao mecanismo de raciocínio atribuindo o papel roles/aiplatform.reasoningEngineServiceAgent à conta de serviço do Discovery Engine:

    service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com

    em que PROJECT_NUMBER é o número do projeto que hospeda o mecanismo de inferência. Essa permissão permite que o back-end de resposta de streaming crie, leia e adicione eventos a sessões em seu nome.

  4. Revise as cotas aplicáveis. As sessões com suporte do Agent Runtime consomem cotas da API Agent Platform. As cotas relevantes são:

    • aiplatform.googleapis.com/session_write_requests: criar, excluir ou atualizar sessões do ambiente de execução do agente por minuto.

    • aiplatform.googleapis.com/session_event_append_requests — adiciona um evento às sessões do Agent Runtime por minuto.

    Para mais informações, consulte Cotas do Agent Engine da plataforma de agentes do Gemini Enterprise.

  5. Anote o nome do recurso do ambiente de execução do agente porque você precisa transmiti-lo como o campo reasoningEngine na solicitação streamAnswer.

Opcional: configurar um app personalizado no modo de IA

Por padrão, a recuperação com agente usa o agente de respostas do Google predefinido. Isso classifica as consultas em intents DEFAULT_ANSWER_SEEKING e DO_NOT_ANSWER. Você pode criar um app personalizado no modo de IA quando quiser personalizar ferramentas ou adicionar suporte para novas classes de intents de consulta. Cada intent personalizada (ou frame) declara as condições em que o agente classifica uma consulta na intent e as instruções e ferramentas que ele usa para processá-la.

  1. Crie o mecanismo usando o método REST engines.create com um bloco engine_config.answer_agent.

    A configuração é estruturada da seguinte maneira:

    engine {
 name: "YOUR_AI_MODE_ENGINE"
 display_name: "YOUR_AI_MODE_ENGINE_DISPLAY_NAME"
 engine_config {
   answer_agent {
     frames {
       vertical_intent: "YOUR_CUSTOM_INTENT"
       vertical_intent_prompt {
         instructions: "Instructions for when to classify a user query as YOUR_CUSTOM_INTENT."
       }
       initial_prompt {
         instructions: "Instructions for the agent on how to process a user query classified as YOUR_CUSTOM_INTENT."
         tools {
           discovery_engine_search_tool_config {
             serving_config: "YOUR_SEARCH_SERVING_CONFIG_1"
             page_size: 10
           }
           tool_description: "This tool can help search corpus 1."
         }
         tools {
           discovery_engine_search_tool_config {
             serving_config: "YOUR_SEARCH_SERVING_CONFIG_2"
             page_size: 10
           }
           tool_description: "This tool can help search corpus 2."
         }
       }
     }
   }
 }
}
engine_id: "SAMPLE_MULTI_SEARCH_RETRIEVAL"

  2. Depois de criar o mecanismo, encaminhe as solicitações pela configuração de veiculação default_agent_answer dele:

    projects/*/locations/*/collections/*/engines/YOUR_AI_MODE_ENGINE/servingConfigs/default_agent_answer

  3. Para receber ajuda com o design ou registro de um app personalizado no modo de IA, entre em contato com o suporte.

Transmitir uma resposta usando a recuperação agêntica

O comando a seguir mostra como chamar o método streaming answer com a recuperação generativa ativada. Semelhante à saída sem recuperação generativa, essa chamada transmite uma resposta gerada na forma de uma série de respostas JSON.

Se você configurou um mecanismo de raciocínio, inclua o nome do recurso dele no campo reasoningEngine para manter a sessão em todas as interações.

REST

Para pesquisar e receber resultados com uma resposta gerada transmitida, 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/SERVING_CONFIG_ID:streamAnswer" \
  -d '{
        "query": { "text": "QUERY" },
        "session": "SESSION",
        "enableAgentInvocation": true,
        "userPseudoId": "USER_PSEUDO_ID",
        "reasoningEngine": "projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID"
      }'

    Substitua:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • APP_ID: o ID do app Pesquisa do agente que você quer consultar.
    • SERVING_CONFIG_ID: para usar um app personalizado no modo de IA, defina como default_agent_answer. Para usar o agente de respostas do Google predefinido, defina como default_search.
    • PROJECT_NUMBER: o número do projeto que hospeda o mecanismo de raciocínio.
    • QUERY: uma string de texto livre que contém a pergunta ou consulta de pesquisa.
    • SESSION: se você estiver continuando uma conversa de várias rodadas, este será o nome do recurso de sessão retornado na resposta da rodada anterior, por exemplo, projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID. Se não estiver continuando uma conversa, defina como -, um hífen.
    • USER_PSEUDO_ID: um identificador exclusivo usado para rastrear o visitante.
    • LOCATION_ID: o local do seu mecanismo de raciocínio, por exemplo, us-central1.
    • REASONING_ENGINE_ID: o ID da instância do Agent Engine que você criou.

Python

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

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

O exemplo a seguir usa o cliente Python do Discovery Engine (v1alpha) para chamar stream_answer_query com a invocação do agente ativada. Transmita o campo reasoning_engine para sessões de várias rodadas.

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1alpha


def run_stream_answer_query():
    PROJECT_ID = "YOUR_PROJECT_ID"
    LOCATION = "global"  # or a specific region
    COLLECTION_ID = "default_collection"
    ENGINE_ID = "YOUR_ENGINE_ID"
    # Use "default_search" for the predefined Google answer agent, or
    # "default_agent_answer" if you have configured a custom AI_MODE app.
    SERVING_CONFIG_ID = "default_search"
    USER_ID = "user-id"
    QUERY_TEXT = "YOUR_QUERY_TEXT"
    REASONING_ENGINE_ID = "YOUR_REASONING_ENGINE_ID"
    # Use "-" to start a new session, or pass the sessionId returned in
    # the previous turn's response to continue an existing session.
    SESSION_ID = "-"

    SESSION_REF = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/collections/"
        f"{COLLECTION_ID}/engines/{ENGINE_ID}/sessions/{SESSION_ID}"
    )
    SERVING_CONFIG_ENGINE = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/collections/"
        f"{COLLECTION_ID}/engines/{ENGINE_ID}/servingConfigs/{SERVING_CONFIG_ID}"
    )
    REASONING_ENGINE = (
        f"projects/{PROJECT_ID}/locations/{LOCATION}/"
        f"reasoningEngines/{REASONING_ENGINE_ID}"
    )

    client_options = ClientOptions(
        api_endpoint="discoveryengine.googleapis.com"
    )

    client = discoveryengine_v1alpha.ConversationalSearchServiceClient(
        client_options=client_options
    )

    request = discoveryengine_v1alpha.AnswerQueryRequest(
        query=discoveryengine_v1alpha.Query(text=QUERY_TEXT),
        serving_config=SERVING_CONFIG_ENGINE,
        user_pseudo_id=USER_ID,
        enable_agent_invocation=True,
        session=SESSION_REF,
        reasoning_engine=REASONING_ENGINE,
    )

    print(f"Starting StreamAnswerQuery agentic session with: {request}")
    stream = client.stream_answer_query(request)

    try:
        for response in stream:
            print(f"Received response: {response}")
    except Exception as e:
        print(f"Error during streaming: {e}")


if __name__ == "__main__":
    run_stream_answer_query()

Instalar a versão de prévia do SDK do Discovery Engine

O SDK do Discovery Engine facilita a interação com os serviços Google Cloud nos seus aplicativos. O SDK ajuda no tratamento de erros e na autenticação, além de oferecer recursos como novas tentativas automáticas, tratamento de paginação e gerenciamento operação de longa duração.

Como o recurso de recuperação com agente está em uma lista de permissões, o SDK que você precisa para trabalhar com ele é diferente das bibliotecas de cliente do Discovery Engine disponíveis para todos.

Para acessar a versão de prévia do SDK do Discovery Engine, faça o seguinte:

  1. Entre em contato com o suporte para acessar a pasta do Google Drive com a prévia do SDK.

  2. Baixe o pacote para seu idioma.

Alterações na API

Como esse recurso está em uma lista de permissões, a documentação de referência da API na página do método streaming answer não mostra todos os campos disponíveis e necessários para usar a recuperação de agente com o método stream answer. Os campos ausentes são documentados da seguinte forma.

Campos do corpo da solicitação

  • enableAgentInvocation (booleano): defina true para mudar para o processamento com agente usando a configuração de veiculação de pesquisa atual. Esse campo é opcional se você estiver especificando uma configuração de veiculação answer_agent com um app de modo de IA personalizado.

  • reasoningEngine (string): o nome do recurso do ambiente de execução do agente que hospeda as sessões do agente, formatado como projects/*/locations/*/reasoningEngines/*.

Campos de resposta

Quando a recuperação com agente está ativada, cada Answer.Reference gerado inclui:

  • queries (string repetida): a lista de consultas que o agente emitiu para produzir a referência.

Serviço de sessões

A API REST do serviço de sessão não é compatível com os métodos create ou update. No entanto, ele é compatível com os outros métodos: list, get e delete.

A API RPC do serviço de sessão não é compatível com as operações Update ou Create em recursos de sessão usados para conversas de várias rodadas. No entanto, ele oferece suporte ao outro serviço: operações List, Get e Delete em recursos de sessão usados para conversas de várias rodadas.