에이전트형 검색을 사용하여 답변 스트리밍

이 페이지에서는 에이전트 기반 검색을 소개하고 stream answers 메서드와 함께 사용하는 방법을 설명합니다.

에이전트형 검색 정보

스트림 답변 메서드와 함께 사용되는 에이전트 검색은 특정 사용 사례에서 더 나은 결과를 얻을 수 있습니다. 예를 들어 데이터 스토어가 여러 개인 앱의 다중 패스 검색을 사용 설정하거나 다양한 클래스의 질문에 대한 답변 생성을 맞춤설정할 수 있습니다.

에이전트 기반 검색을 사용하면 앱에 약간의 복잡성이 추가되지만 그 대신 결과에 대한 더 많은 제어 기능을 제공합니다.

Agent Search에는 검색엔진의 동작을 맞춤설정하는 데 사용할 수 있는 사전 정의된 에이전트가 포함되어 있습니다. 이를 통해 에이전트 검색 없이 앱 구성 UI 또는 스트리밍 답변 메서드를 통해 제공되는 것보다 더 많은 맞춤설정이 가능합니다.

에이전트 검색이 있는 혼합 검색과 에이전트 검색이 없는 혼합 검색

에이전트 검색은 특히 혼합 검색 앱에 유용합니다. 에이전트 검색이 없으면 검색에서 모든 데이터 스토어를 한 번에 쿼리하는 단일 패스 팬아웃을 사용합니다. 반면 에이전트 기반 검색은 다중 패스 검색을 지원합니다. 에이전트는 검색을 순차적으로 계획하고 실행하며 각 단계에 가장 적합한 도구를 선택합니다. 여러 에이전트 검색 데이터 저장소의 결과를 결합하고 Google 검색, Google 지도와 같은 도구를 사용할 수 있습니다.

예를 들어 전 세계 회사 정책과 지역 사무실 세부정보에 별도의 데이터 스토어가 있습니다. 사용자가 '도쿄 사무실의 규정 준수 규칙은 무엇인가요?'라고 묻습니다.

  • 에이전트 기반 검색이 없는 경우: 전체 쿼리 문자열을 사용하여 정책 스토어와 지역 사무소 스토어를 동시에 쿼리합니다. 이 경우 결과가 조각화되어 반환될 수 있습니다.

  • 에이전트 기반 검색: 에이전트가 실행을 계획합니다. 먼저 지역 스토어에서 도쿄 사무실에 관한 세부정보를 가져옵니다. 그런 다음 이 특정 컨텍스트를 사용하여 정책 스토어에서 두 번째 타겟팅 검색을 실행합니다.

    에이전트는 이러한 결과를 종합하여 일관성 있고 더 정확한 답변을 생성합니다.

에이전트형 검색을 사용하면 혼합 검색 앱에서 멀티턴 검색 쿼리 (후속 질문)를 실행할 수도 있습니다. 에이전트 기반 검색이 없으면 다중 턴 검색은 단일 데이터 스토어 앱에서만 작동합니다. 여러 턴에 걸쳐 대화 컨텍스트를 유지하려면 원하는 경우 에이전트형 검색을 Agent Platform 세션과 페어링하세요.

맞춤 쿼리 분류

answer 및 streaming answer 메서드는 ADVERSARIAL_QUERY 및 NON_ANSWER_SEEKING_QUERY의 두 가지 질문 분류 유형을 제공합니다.

에이전트 기반 검색을 사용하면 비즈니스 워크플로에 맞는 추가 분류 유형을 정의할 수 있습니다. 시스템은 분류기를 사용하여 사용자의 의도를 파악하고 요청을 적절한 에이전트 구성으로 라우팅합니다.

예를 들어 쿼리에서 쿼리의 의도가 주문을 추적하는 것이며 TRACK_ORDER 분류를 지정했다고 가정해 보겠습니다. 모든 데이터 스토어에서 일반 검색을 실행하는 대신 시스템은 배송 상태를 가져오는 데 필요한 도구와 데이터가 장착된 전문 에이전트를 로드합니다.

에이전트 검색을 사용 설정하고 사용하는 방법

에이전트 기반 검색을 사용 설정하는 방법에는 두 가지가 있습니다.

  • 사전 정의된 Google 답변 에이전트: 에이전트 검색에 검색 앱이 이미 있는 경우 앱에 쿼리를 보낼 때 API 요청에서 enable_agent_invocation=true를 설정하여 에이전트형 검색을 사용 설정할 수 있습니다. 이 경우 기존 검색 서빙 구성을 유지합니다.

  • 맞춤 AI 모드 앱: 에이전트 검색 앱을 만들 때 default_agent_answer 서빙 구성이라는 다른 유형의 서빙 구성을 정의합니다. '앱'과 '엔진'이 에이전트 검색에서 서로 바꿔서 사용되므로 맞춤 AI 모드 엔진이라고도 합니다.

시작하기 전에

에이전트 기반 검색을 사용하려면 다음을 수행하세요.

다중 턴 세션을 위한 추론 엔진 설정

여러 턴에 걸쳐 대화 컨텍스트를 유지하려면 Gemini Enterprise Agent Platform 엔진 (추론 엔진이라고도 함)에서 에이전트 런타임을 만들어야 합니다.

streamAnswer 요청을 할 때는 Agent Runtime의 리소스 이름을 streamAnswer 요청의 reasoningEngine 필드로 전달합니다.

  1. Google Cloud 프로젝트에서 에이전트 플랫폼을 사용 설정합니다.

  2. Agent Engine REST API (또는 에이전트 개발 키트)를 사용하여 에이전트 런타임 인스턴스 (추론 엔진이라고도 함)를 만듭니다. 인스턴스는 streamAnswer 메서드에서 사용하는 세션을 호스팅합니다.

    인스턴스 리소스 이름의 형식은 다음과 같습니다.

    projects/PROJECT_NUMBER/locations/LOCATION_ID/reasoningEngines/REASONING_ENGINE_ID

  3. Discovery Engine 서비스 계정에 roles/aiplatform.reasoningEngineServiceAgent 역할을 부여하여 Discovery Engine 서비스 에이전트가 추론 엔진에 액세스할 수 있도록 합니다.

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

    여기서 PROJECT_NUMBER는 추론 엔진을 호스팅하는 프로젝트의 번호입니다. 이 권한을 사용하면 스트리밍 답변 백엔드에서 사용자 대신 세션에 이벤트를 만들고, 읽고, 추가할 수 있습니다.

  4. 관련 할당량을 검토합니다. Agent Runtime에서 지원하는 세션은 Agent Platform API의 할당량을 사용합니다. 관심 있는 할당량은 다음과 같습니다.

    • aiplatform.googleapis.com/session_write_requests - 분당 에이전트 런타임 세션을 생성, 삭제 또는 업데이트합니다.

    • aiplatform.googleapis.com/session_event_append_requests - 분당 Agent Runtime 세션에 이벤트를 추가합니다.

    자세한 내용은 Gemini Enterprise Agent Platform Agent Engine 할당량을 참고하세요.

  5. streamAnswer 요청에서 reasoningEngine 필드로 전달해야 하므로 에이전트 런타임 리소스 이름을 기록해 둡니다.

선택사항: 맞춤 AI 모드 앱 설정

기본적으로 에이전트 검색은 사전 정의된 Google 답변 에이전트를 사용합니다. 이 클래스는 쿼리를 의도 DEFAULT_ANSWER_SEEKING 및 DO_NOT_ANSWER로 분류합니다. 도구를 맞춤설정하거나 새로운 클래스의 쿼리 인텐트 지원을 추가하려면 맞춤 AI 모드 앱을 만들면 됩니다. 각 맞춤 의도 (또는 프레임)는 에이전트가 쿼리를 인텐트로 분류하는 조건과 에이전트가 이를 처리하는 데 사용하는 지침 및 도구를 선언합니다.

  1. engine_config.answer_agent 블록을 사용하여 engines.create REST 메서드를 통해 엔진을 만듭니다.

    구성의 구조는 다음과 같습니다.

    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. 엔진을 만든 후 default_agent_answer 서빙 구성을 통해 요청을 라우팅합니다.

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

  3. 맞춤 AI 모드 앱을 설계하거나 등록하는 데 도움이 필요한 경우 지원팀에 문의하세요.

에이전트형 검색을 사용하여 답변 스트리밍

다음 명령어는 에이전트 기반 검색이 사용 설정된 상태에서 streaming answer 메서드를 호출하는 방법을 보여줍니다. 에이전트형 검색이 없는 출력과 마찬가지로 이 호출은 생성된 답변을 일련의 JSON 응답 형식으로 스트리밍합니다.

추론 엔진을 설정한 경우 reasoningEngine 필드에 리소스 이름을 포함하여 턴 간에 세션을 유지합니다.

REST

스트리밍된 생성된 답변으로 검색하고 결과를 얻으려면 다음을 수행합니다.

  1. 다음 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"
      }'

    다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
    • APP_ID: 쿼리할 Agent Search 앱의 ID입니다.
    • SERVING_CONFIG_ID: 맞춤 AI 모드 앱을 사용하려면 default_agent_answer로 설정합니다. 사전 정의된 Google 답변 에이전트를 사용하려면 이 값을 default_search로 설정합니다.
    • PROJECT_NUMBER: 추론 엔진을 호스팅하는 프로젝트의 번호입니다.
    • QUERY: 질문 또는 검색어를 포함하는 자유 텍스트 문자열입니다.
    • SESSION: 멀티턴 대화를 계속하는 경우 이전 턴의 응답에서 반환된 세션 리소스 이름입니다(예: projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID). 대화를 이어가지 않는 경우 하이픈인 -으로 설정합니다.
    • USER_PSEUDO_ID: 방문자를 추적하는 데 사용되는 고유 식별자입니다.
    • LOCATION_ID: 추론 엔진의 위치입니다(예: us-central1).
    • REASONING_ENGINE_ID: 생성한 Agent Engine 인스턴스의 ID입니다.

Python

자세한 내용은 Agent Search Python API 참고 문서를 확인하세요.

Agent Search에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

다음 샘플에서는 Discovery Engine Python 클라이언트 (v1alpha)를 사용하여 에이전트 호출이 사용 설정된 stream_answer_query을 호출합니다. 다중 턴 세션의 경우 reasoning_engine 필드를 전달합니다.

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()

디스커버리 엔진 SDK의 미리보기 버전 가져오기

Discovery Engine SDK를 사용하면 애플리케이션에서 Google Cloud서비스와 더 쉽게 상호작용할 수 있습니다. SDK는 오류 처리 및 인증을 지원하고 자동 재시도, 페이지로 나누기 처리, 장기 실행 작업 관리와 같은 기능을 제공합니다.

에이전트 검색 기능은 허용 목록에 있으므로 이 기능과 함께 작동해야 하는 SDK는 일반적으로 제공되는 Discovery Engine 클라이언트 라이브러리와 다릅니다.

Discovery Engine SDK의 미리보기 버전을 가져오려면 다음 단계를 따르세요.

  1. 미리보기 SDK Google Drive 폴더에 액세스하려면 지원팀에 문의하세요.

  2. 사용 중인 언어의 패키지를 다운로드합니다.

API 변경사항

이 기능은 허용 목록에 있으므로 스트리밍 답변 메서드 페이지의 API 참조 문서에는 스트림 답변 메서드로 에이전트형 검색을 사용하는 데 필요한 모든 필드가 표시되지 않습니다. 누락된 필드는 다음과 같이 문서화됩니다.

요청 본문 필드

  • enableAgentInvocation (불리언) - 기존 검색 서빙 구성으로 에이전트 처리로 전환하려면 true로 설정합니다. 맞춤 AI 모드 앱으로 answer_agent 서빙 구성을 지정하는 경우 이 필드는 선택사항입니다.

  • reasoningEngine (문자열) - 에이전트 세션을 호스팅하는 에이전트 런타임의 리소스 이름입니다. projects/*/locations/*/reasoningEngines/* 형식입니다.

응답 필드

에이전트 기반 검색이 사용 설정되면 생성된 각 Answer.Reference에는 다음이 포함됩니다.

  • queries (반복 문자열) - 참조를 생성하기 위해 에이전트가 실행한 쿼리 목록입니다.

세션 서비스

세션 서비스 REST API는 create 또는 update 메서드를 지원하지 않습니다. 하지만 list, get, delete 메서드는 지원합니다.

세션 서비스 RPC API는 멀티턴 대화에 사용되는 세션 리소스에 대한 Update 또는 Create 작업을 지원하지 않습니다. 하지만 다중 턴 대화에 사용되는 세션 리소스에 대한 List, Get, Delete 작업과 같은 다른 서비스는 지원합니다.