참고: 이 문서 모음은 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`
엔드포인트 버전	`v1alpha`: 에이전트 ID 검색, `v1`: `streamAssist` 호출
키 파라미터	`agentsSpec.agentSpecs[].agentId`
지원되는 에이전트 유형	Core Assistant, Deep Research, Workflow Builder 채팅 에이전트 (이전의 로우 코드), Workflow Builder 워크플로(워크플로 호출 참조)
필수 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, workflowAgentDefinition)을 나타내는 정의 객체입니다.

전체 에이전트 리소스 스키마는 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입니다. RFC-1034를 준수해야 하며 최대 길이는 63자(영문 기준)입니다.

전체 요청 스키마는 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: Google Cloud 프로젝트 ID입니다.
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가 격리된 새 세션을 자동으로 생성합니다.

워크플로 호출

Workflow Builder 워크플로를 실행하려면 agentsSpec.agentSpecs[].agentId에 워크플로 ID를 포함하여 동일한 요청을 전송합니다. 각 호출은 워크플로의 수동 실행을 시작합니다.

실행되는 버전: 워크플로가 게시된 경우 호출은 게시된 버전을 실행합니다. Workflow Builder에 저장되었지만 아직 게시되지 않은 변경사항은 게시하기 전까지 API 호출자에게 영향을 미치지 않습니다. 워크플로가 게시된 적이 없으면 호출은 초안을 실행합니다.
호출할 수 있는 사용자: 워크플로의 소유자와 관리자가 호출할 수 있습니다. 다른 사용자는 게시된 워크플로가 공유된 후 이를 호출할 수 있습니다. 소유자 또는 관리자만 게시된 적이 없는 워크플로를 호출할 수 있습니다. 다른 호출자는 HTTP 403를 수신합니다.
트리거: 워크플로에는 수동 트리거가 정확히 하나 있어야 합니다. 수동 트리거를 다른 트리거와 결합하거나 수동 트리거가 두 개 이상 있는 워크플로의 경우 호출이 실패합니다.
입력: streamAssist를 통해 수동 트리거의 입력 변수를 설정할 수 없습니다. 수동 트리거에 필수 입력이 있는 경우 입력에 기본값이 있더라도 실행이 실패합니다. 선택적 입력이 비어 있고 기본값이 적용되지 않습니다. 쿼리 텍스트는 워크플로의 LLM 노드로 전달되므로 여기에 데이터를 포함할 수 있지만 입력 변수를 채우지는 않습니다.

제한사항

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"`를 추가합니다.
`HTTP 403`(`Only the agent owner or an admin can run a draft of this agent.` 포함)	워크플로가 게시된 적이 없으며 호출자가 소유자 또는 관리자가 아닙니다.	Workflow Builder에서 워크플로를 게시하고 발신자와 공유합니다.
`HTTP 403`(`User does not have permission to access the Agent.` 포함)	워크플로는 발신자와 공유되지 않습니다.	발신자와 워크플로를 공유합니다.
워크플로가 이전 버전처럼 작동함	이 호출은 Workflow Builder에서 게시되지 않은 변경사항이 아닌 게시된 버전을 실행합니다.	워크플로를 게시합니다.
워크플로 호출이 `answer.state` `FAILED` 및 `INTERNAL` 오류로 종료됨	워크플로에 수동 트리거와 다른 트리거가 있거나 수동 트리거가 두 개 이상 있습니다.	수동 트리거를 하나만 유지합니다.