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 generativa adiciona complexidade aos seus apps, mas, em troca, oferece mais controle sobre os resultados.

Agent Search 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 de agentes

A recuperação com agente é particularmente útil para apps de pesquisa combinada. Sem a recuperação generativa, 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 do Agent Search 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 multiturno (perguntas de acompanhamento) em apps de pesquisa combinada. Sem a recuperação por agente, a pesquisa multiturno 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 de Agentes com uma sessão da Agent Platform (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, na 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 no Agent Search, 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 do modo IA:ao criar um app do Agent Search, você define um tipo diferente de configuração de veiculação, a configuraçã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 Agent Search.

Antes de começar

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

• Configurar um mecanismo de raciocínio multiturno para sessões

• Opcional: configurar um app personalizado no modo de IA

Configurar um mecanismo de raciocínio para sessões multiturno

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

Ao fazer uma solicitação streamAnswer, transmita o nome do recurso do Agent Runtime como o campo reasoningEngine na solicitação streamAnswer.

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

2. Crie uma instância do ambiente de execução do agente (também chamado de mecanismo de inferência) 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 inferência 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. Com essa permissão, o back-end de respostas de streaming pode criar, ler e anexar 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: crie, exclua ou atualize sessões do Agent Runtime por minuto.

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

   Para mais informações, consulte Cotas do mecanismo de agente da Gemini Enterprise Agent Platform.

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 intenções DEFAULT_ANSWER_SEEKING e DO_NOT_ANSWER. É possível criar um app personalizado do Modo 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 de agente ativada. Semelhante à saída sem recuperação com agente, 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.

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 dos 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 usar 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 com agente com o método de resposta de stream. Os campos ausentes são documentados da seguinte forma.

Campos do corpo da solicitação

• enableAgentInvocation (booleano): defina true para mudar para o processamento de agentes com a configuração de serviç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 Agent Runtime 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 multiturno. No entanto, ele oferece suporte ao outro serviço: operações List, Get e Delete em recursos de sessão usados para conversas multiturno.