참고: 이 문서 모음은 Gemini Enterprise의 Standard, Plus, Frontline 버전을 위한 것입니다. Business 에디션 문서는 Gemini Enterprise - Business 에디션 고객센터를 참고하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

StreamAssist API로 특정 상담사 호출

등록된 특정 에이전트를 호출하려면 streamAssist REST API 요청 또는 클라이언트 라이브러리 호출에서 선택적 agentsSpec 필드를 제공합니다. AgentsSpec API는 요청을 처리하는 데 사용되는 에이전트의 사양을 정의합니다. 어시스턴트는 쿼리를 해당 에이전트로 직접 라우팅하고 턴 전반에 걸쳐 세션 컨텍스트를 보존합니다.

요약 정보

사양	세부정보
API 메서드	`projects.locations.collections.engines.assistants.streamAssist`
엔드포인트 버전	에이전트 ID를 검색하기 위한 `v1alpha`, `streamAssist`를 호출하기 위한 `v1`
키 매개변수	`agentsSpec.agentSpecs[].agentId`
지원되는 에이전트 유형	Core 어시스턴트, Deep Research, Agent Designer 채팅 에이전트 (이전의 로우 코드)
필수 IAM 권한	`discoveryengine.assistants.assist`
필수 OAuth 범위	`https://www.googleapis.com/auth/cloud-platform`

시작하기 전에

Google Cloud 프로젝트에서 Discovery Engine API (discoveryengine.googleapis.com)를 사용 설정합니다.
주 구성원 (사용자 계정 또는 서비스 계정)에 Discovery Engine 편집자 (roles/discoveryengine.editor) 또는 Gemini Enterprise 관리자 (roles/discoveryengine.agentspaceAdmin)와 같이 discoveryengine.assistants.assist IAM 권한을 부여하는 역할이 있는지 확인합니다.
Gemini Enterprise 앱 (엔진)이 생성되었고 등록된 에이전트가 하나 이상 포함되어 있는지 확인합니다.
애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 인증하는 경우 클라이언트가 할당량 프로젝트 헤더 -H "X-Goog-User-Project: PROJECT_ID"를 전송하는지 확인합니다.

앱 ID 및 위치 찾기

streamAssist URL에는 엔진 ID와 위치 (global, us 또는 eu)가 필요합니다. 앱의 표시 이름만 알고 있는 경우 프로젝트에서 엔진을 나열하여 기본 ID를 찾습니다.

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

응답에서 엔진 name 형식은 projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}입니다. ENGINE_ID 세그먼트는 호출에 필요한 APP_ID입니다.

에이전트 ID 찾기

agentId는 Discovery Engine API에서 에이전트의 전체 리소스 이름의 마지막 세그먼트입니다.

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{AGENT_ID}

등록된 에이전트는 친숙한 표시 이름이 아닌 긴 숫자 ID (예: 15492003793394502655)를 사용합니다. 요청에서 이 최종 {AGENT_ID} 숫자 문자열만 제공합니다.

앱에 등록된 에이전트를 나열하고 숫자 ID를 검색하려면 v1alpha 엔드포인트에서 agents 컬렉션을 호출합니다.

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

반환된 각 에이전트 리소스에는 다음 필드가 포함됩니다.

name: {AGENT_ID}로 끝나는 전체 리소스 경로입니다.
displayName: Google Cloud 콘솔에 표시되는 사람이 읽을 수 있는 이름입니다.
state: 운영 상태 (예: ENABLED 또는 PRIVATE)입니다.
에이전트 유형 (예: a2aAgentDefinition 또는 lowCodeAgentDefinition)을 나타내는 정의 객체입니다.

전체 에이전트 리소스 스키마는 agents REST API 참조를 확인하세요.

에이전트에 쿼리 보내기

특정 에이전트에 쿼리를 보내려면 적절한 agentsSpec으로 요청을 구성하고 REST 또는 클라이언트 라이브러리를 사용하여 실행해야 합니다.

요청 본문 구조

쿼리를 특정 에이전트로 라우팅하려면 POST 요청 본문에 선택적 agentsSpec 객체를 포함합니다.

{
  "query": {
    "text": "QUERY_TEXT"
  },
  "session": "SESSION_RESOURCE_NAME",
  "agentsSpec": {
    "agentSpecs": [
      {
        "agentId": "AGENT_ID"
      }
    ]
  }
}

필드 참조

agentsSpec (객체, 선택사항): 요청을 처리하는 데 사용되는 에이전트의 사양입니다.
agentsSpec.agentSpecs[] (배열, 선택사항): 에이전트 사양 목록입니다. 이 배열에 여러 에이전트를 지정할 수 있습니다.
agentsSpec.agentSpecs[].agentId (문자열, 사양 내에서 필수): 등록된 에이전트 리소스를 식별하는 ID입니다. 최대 길이 63자(영문 기준)로 RFC-1034를 준수해야 합니다.

전체 요청 스키마는 streamAssist REST API 참조를 확인하세요.

streamAssist 호출

REST

다음 curl 명령어는 REST API를 사용하여 특정 에이전트에 쿼리를 보냅니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "query": {
      "text": "List all contact cards."
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

다음 자리표시자를 바꿉니다.

LOCATION: 호스트 이름과 리소스 경로 (global, us 또는 eu) 모두의 멀티 리전입니다. 앱이 global 위치에 있는 경우 호스트 이름 (discoveryengine.googleapis.com)에서 위치 프리픽스를 생략합니다.
PROJECT_ID: 프로젝트 ID입니다. Google Cloud
APP_ID: Gemini Enterprise 엔진 ID (앱 ID 및 위치 찾기에서 검색됨)입니다.
AGENT_ID: 숫자 에이전트 ID (에이전트 ID 찾기에서 검색됨)입니다.

Python

이 Python 예시에서는 google-cloud-discoveryengine 클라이언트 라이브러리를 사용하여 streamAssist를 호출합니다.

# Install library: pip install google-cloud-discoveryengine
from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Replace placeholder values with your project and agent details.
project_id = "PROJECT_ID"
location = "LOCATION"          # For example: "us", "eu", or "global"
engine_id = "APP_ID"
agent_id = "AGENT_ID"          # The numeric agent ID
query_text = "List all contact cards."

client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)
client = discoveryengine.AssistantServiceClient(client_options=client_options)

assistant_path = client.assistant_path(
    project=project_id,
    location=location,
    collection="default_collection",
    engine=engine_id,
    assistant="default_assistant",
)

request = discoveryengine.StreamAssistRequest(
    name=assistant_path,
    query=discoveryengine.Query(text=query_text),
    agents_spec=discoveryengine.StreamAssistRequest.AgentsSpec(
        agent_specs=[
            discoveryengine.StreamAssistRequest.AgentsSpec.AgentSpec(
                agent_id=agent_id,
            )
        ]
    ),
)

for response in client.stream_assist(request=request):
    for reply in response.answer.replies:
        # Filter out model reasoning fragments (thought: true)
        if hasattr(reply, "grounded_content") and reply.grounded_content.content:
            print(reply.grounded_content.content.text, end="", flush=True)

print()

스트리밍 응답 이해

streamAssist 엔드포인트는 REST를 통해 JSON 청크 스트림 또는 클라이언트 라이브러리의 응답 객체 반복자를 반환합니다.

답 텍스트: 증분 응답 텍스트가 answer.replies[].groundedContent.content.text에 도착합니다. 수신 순서대로 이러한 텍스트 프래그먼트를 연결하여 전체 답변을 재구성합니다.
추론 프래그먼트: "thought": true로 표시된 프래그먼트는 모델의 내부 추론 프로세스를 나타냅니다. 최종 출력을 최종 사용자에게 표시할 때 이러한 프래그먼트를 필터링합니다.
실행 상태: answer.state 필드는 IN_PROGRESS에서 최종 상태로 진행됩니다.
- SUCCEEDED: 요청이 완료되고 답변이 생성되었습니다.
- SKIPPED: 쿼리가 무시되거나 우회되었습니다. 자세한 내용은 assistSkippedReasons (예: 간단한 인사말의 경우 NON_ASSIST_SEEKING_QUERY_IGNORED)를 검사합니다.
- FAILED: 호출에서 실행 오류가 발생했습니다.
세션 연속성: 터미널 청크에는 sessionInfo.session (세션 리소스 이름) 및 assistToken이 포함됩니다.

동일한 세션에서 대화 계속하기

턴 전반에 걸쳐 컨텍스트를 유지하려면 후속 요청에서 sessionInfo의 session 문자열을 전달합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "session": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
    "query": {
      "text": "Who is John Doe?"
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

session 필드를 생략하거나 세션 ID로 -를 지정하면 API에서 자동으로 새 격리된 세션을 생성합니다.

제한사항

streamAssist로 에이전트를 호출할 때는 다음 제한사항이 적용됩니다.

지원되지 않는 에이전트 유형:
- 워크플로 에이전트는 지원되지 않습니다.
- Gemini Enterprise 앱에 등록된 A2A 또는 ADK 에이전트는 streamAssist를 통해 지원되지 않습니다. 등록 엔드포인트를 사용하여 A2A 에이전트를 직접 호출하려면 등록 A2A 엔드포인트를 사용하여 에이전트 호출을 참고하세요.
변경 작업: streamAssist API는 대화형 쿼리 및 커넥터를 통한 읽기 전용 검색에 최적화되어 있습니다. 변경 가능한 도구 및 작업 (예: 이메일 작성, 캘린더 일정 만들기 또는 채팅 메시지 전송)의 프로그래매틱 실행은 streamAssist를 통해 지원되지 않습니다. 변경 작업을 실행하는 에이전트 워크플로를 호출하려고 하면 내부적으로 오류가 발생하거나 그라운딩되지 않은 실행 루프가 발생할 수 있습니다.

문제 해결

일반적인 streamAssist 호출 오류를 해결하려면 다음 표를 사용하세요.

증상	가능한 원인	해결 방법
에이전트 나열 시 HTTP 404	`v1` 또는 `v1beta` 엔드포인트에서 `agents`를 호출합니다.	대신 `v1alpha` 엔드포인트에 목록 요청을 보냅니다.
응답이 일반적인 것으로 표시됨에도 불구하고 `agentsSpec`을 설정했습니다.	잘못된 숫자 `agentId` 또는 쿼리가 너무 일반적이어서 도메인 동작을 트리거할 수 없습니다.	`v1alpha` 에이전트 목록에서 정확한 숫자 ID를 확인하고, 도메인별 쿼리를 보내고, 응답 텍스트에서 에이전트별 단어를 확인합니다.
오류가 반환되지 않았지만 대상 에이전트가 실행되지 않음	잘못된 형식의 `agentId`로 인해 기본 오케스트레이션으로 내부적으로 대체되었습니다.	`agentId`가 숫자만으로 구성되어 있고 등록 목록의 ID와 정확히 일치하는지 확인합니다.
응답 상태가 `SKIPPED`를 반환함	입력이 어시스턴트가 필요하지 않은 쿼리 (예: 간단한 인사말)로 평가되었습니다.	실질적인 작업 쿼리를 보내고 응답 페이로드에서 `assistSkippedReasons`를 검사합니다.
`HTTP 401` 또는 `HTTP 403 Permission Denied`	OAuth 범위 누락, IAM 역할 부족 또는 할당량 프로젝트 헤더 누락.	호출자에게 `discoveryengine.assistants.assist`가 있는지 확인하고, OAuth 범위에 `cloud-platform`이 포함되어 있는지 확인하고, ADC를 사용하는 경우 `-H "X-Goog-User-Project: PROJECT_ID"`를 추가합니다.