- HTTP 요청
- 경로 매개변수
- 요청 본문
- 응답 본문
- 승인 범위
- IAM 권한
- AnswerGenerationMode
- AssistSkippingMode
- BrowserContext
- 탭
- EncryptionMetadata
- AgentsConfig
- NoCodeAgentsConfig
- AgentsSpec
- AgentSpec
- MentionMode
- ToolsSpec
- VertexAiSearchSpec
- WebGroundingSpec
- ImageGenerationSpec
- VideoGenerationSpec
- MapsGroundingSpec
- GenerationSpec
- ActionSpec
- SessionInfo
- StatusUpdate
- ToolResult
- InvokedSkill
- ConnectorAuthError
스트리밍 방식으로 사용자의 쿼리를 지원합니다.
HTTP 요청
POST https://discoveryengine.googleapis.com/v1alpha/{name=projects/*/locations/*/collections/*/engines/*/assistants/*}:streamAssist URL은 gRPC 트랜스코딩 구문을 사용합니다.
경로 매개변수
| 매개변수 | |
|---|---|
name |
(필수 항목) |
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
| JSON 표현 |
|---|
{ "query": { object ( |
| 필드 | |
|---|---|
query |
(선택사항) 현재 사용자 쿼리입니다. 빈 쿼리는 |
answerGenerationMode |
(선택사항) 답변 생성 모드입니다. 지정하지 않으면 기본값은 |
session |
(선택사항) 요청에 사용할 세션입니다. 지정된 경우 어시스턴트는 세션 기록에 액세스할 수 있으며 질문과 답변이 여기에 저장됩니다.
형식: |
isSessionLess |
(선택사항) 요청이 세션이 없는지 여부를 지정합니다. true인 경우 세션 없이 요청이 실행됩니다. 세션이 생성되지 않으며 true이고 |
assistSkippingMode |
(선택사항) 어시스턴트가 질문에 답변하지 않는 케이스를 결정합니다. 답변이 건너뛰어지면 이유가 |
fileIds[] |
(선택사항) 요청에 답변하는 데 사용할 파일의 ID입니다. 파일을 업로드하면 ID가 |
browserContext |
(선택사항) 사용자가 보고 있는 페이지에 관한 컨텍스트(예: Gemini Enterprise Chrome 측면 패널) |
userMetadata |
(선택사항) 쿼리를 시작하는 사용자에 관한 정보입니다. |
languageCode |
(선택사항) 지원 중단되었습니다. 대신 |
googleSearchGroundingEnabled |
(선택사항) 지원 중단되었습니다. 이 필드를 사용하지 마세요. |
webGroundingEnabled |
(선택사항) 지원 중단되었습니다. 이 필드를 사용하지 마세요. |
dataStoreSpecs[] |
(선택사항) 지원 중단됨: 대신 이 필드를 설정하지 않으면 |
agentsConfig |
(선택사항) 요청을 처리하는 데 사용되는 에이전트의 구성입니다. |
agentsSpec |
(선택사항) 요청을 처리하는 데 사용되는 에이전트의 사양입니다. |
assistGenerationConfig |
(선택사항) 지원 중단되었습니다. 대신 |
cannedQuery |
(선택사항) 이 요청의
형식: |
toolsSpec |
(선택사항) 요청을 처리하는 데 사용되는 도구의 사양입니다. |
generationSpec |
(선택사항) 요청의 생성 구성 사양입니다. |
actionSpec |
(선택사항) 요청의 작업 사양입니다. |
응답 본문
AssistantService.StreamAssist 메서드에 대한 응답입니다.
성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.
| JSON 표현 |
|---|
{ "answer": { object ( |
| 필드 | |
|---|---|
answer |
사용자의 질문에 대한 어시스턴트의 최종 답변 일부를 포함하는 assistants.assist answer 리소스 객체 현재 응답이 이전에 전송된
상태가 |
sessionInfo |
세션 정보 대답 스트림의 최종 StreamAssistResponse에만 포함됩니다. |
statusUpdates[] |
선택적 진행 상황 업데이트입니다. |
assistToken |
현재 요청과 응답 스트림을 식별하는 전역 고유 ID입니다. 의견 및 지원에 사용됩니다. |
toolResult[] |
도구 호출 결과입니다. |
finalResultToolInvocationId |
이 필드가 있으면 결과를 최종 답변으로 사용하는 도구 호출의 ID가 포함됩니다. |
invocationTools[] |
호출된 도구의 도구 이름입니다. |
invokedSkills[] |
턴 중에 실행된 스킬입니다. |
connectorAuthErrors[] |
요청 중에 발생한 커넥터별 인증 오류입니다. 하나 이상의 커넥터가 인증에 실패했지만 요청이 나머지 커넥터로 진행된 경우에 표시됩니다. |
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/discoveryengine.assist.readwritehttps://www.googleapis.com/auth/discoveryengine.readwritehttps://www.googleapis.com/auth/discoveryengine.serving.readwrite
자세한 내용은 Authentication Overview에서 확인하세요.
IAM 권한
name 리소스에 대해서는 다음 IAM 권한이 필요합니다.
discoveryengine.assistants.assist
자세한 내용은 IAM 문서를 참조하세요.
AnswerGenerationMode
사용 가능한 답변 생성 모드입니다.
| 열거형 | |
|---|---|
ANSWER_GENERATION_MODE_UNSPECIFIED |
지정되지 않은 답변 생성 모드입니다. |
NORMAL |
일반 대답 생성 모드입니다. 검색 및 통화 액션을 몇 개 트리거할 수 있습니다. |
RESEARCH |
조사 답변 생성 모드입니다. 질문을 심층 분석하여 질문과 관련된 다양한 주제에 대해 많은 검색을 트리거합니다. |
AGENT |
에이전트 직접 답변 생성 모드입니다. agentsConfig에 정의된 에이전트를 사용하여 답변을 생성합니다. |
AssistSkippingMode
지원 요청에 사용할 수 있는 건너뛰기 동작입니다.
| 열거형 | |
|---|---|
ASSIST_SKIPPING_MODE_UNSPECIFIED |
기본값 쿼리에서 지원을 요청하지 않는 경우 답변을 건너뛸 수 있습니다. |
REQUEST_ASSIST |
어시스턴트 답변 요청 여전히 정책 검사에 실패한 쿼리는 답변을 건너뛸 수 있습니다. |
BrowserContext
사용자가 보고 있는 페이지에 관한 컨텍스트(예: Gemini Enterprise Chrome 측면 패널) 참조하는 파일은 클라이언트에 의해 암호화되며 모델 입력으로 요청에 첨부되지 않습니다. 소비자는 encryptionMetadata를 사용하여 파일을 읽습니다.
| JSON 표현 |
|---|
{ "activeTab": { object ( |
| 필드 | |
|---|---|
activeTab |
(선택사항) 사용자가 현재 보고 있는 탭입니다. 각 파일 ID는 세션에 미리 업로드된 파일을 참조합니다 (ID는 |
encryptionMetadata |
(선택사항) 이 브라우저 컨텍스트에서 참조하는 파일이 암호화되는 방식입니다. 하나의 키 세트가 개별 탭이 아닌 전체 요청을 처리합니다. |
Tab
컨텍스트가 요청에 연결된 브라우저 탭입니다.
| JSON 표현 |
|---|
{ "uri": string, "title": string, "selectedText": string, "screenshotFileId": string, "annotatedPageContentFileId": string } |
| 필드 | |
|---|---|
uri |
(선택사항) 탭에 표시되는 페이지의 URI입니다. http(s) URL이 아닐 수도 있습니다. 탭에 |
title |
(선택사항) 탭에 표시되는 페이지의 제목입니다. |
selectedText |
(선택사항) 사용자가 페이지에서 선택한 텍스트입니다(있는 경우). |
screenshotFileId |
(선택사항) 업로드된 표시 페이지 스크린샷의 ID입니다. |
annotatedPageContentFileId |
(선택사항) 업로드된 페이지 콘텐츠의 ID입니다. 사전 렌더링된 텍스트가 아닌 직렬화된 주석이 달린 페이지 콘텐츠 (APC) 캡처입니다. |
EncryptionMetadata
브라우저 컨텍스트 파일이 클라이언트에 의해 암호화된 방식입니다.
| JSON 표현 |
|---|
{ "encrypted": boolean, "keyset": string } |
| 필드 | |
|---|---|
encrypted |
(선택사항) 브라우저 컨텍스트 파일이 암호화되었는지 여부입니다. |
keyset |
(선택사항) 브라우저 컨텍스트 파일을 복호화하는 데 사용되는 AEAD 기본 요소를 사용하여 직렬화된 Tink 키 세트입니다. 요청 수명 동안만 표시되며 로깅되지 않습니다. base64 인코딩 문자열입니다. |
AgentsConfig
요청을 처리하는 데 사용되는 에이전트의 구성입니다.
| JSON 표현 |
|---|
{ // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "noCodeAgentsConfig": { object ( |
| 필드 | |
|---|---|
| 다양한 유형의 에이전트 구성 다음은 상호 배타적인 필드의 목록입니다. 응답에는 다음 필드 중 최대 하나가 설정됩니다. | |
noCodeAgentsConfig |
(선택사항) 지원 중단됨: 노 코드 Agentspace 에이전트의 구성입니다. 설정된 경우 assistants.assist 요청은 구성에 따라 처리됩니다. 대신 |
assistantAgentConfigId |
(선택사항) |
agent |
사용할 에이전트의 이름입니다. 형식: |
inlineAgent |
사용할 |
vertexAiAgentId |
(선택사항) |
| 상호 배타적 필드의 끝입니다. | |
NoCodeAgentsConfig
지원 중단됨: 노 코드 Agentspace 에이전트의 구성입니다. 대신 agent를 사용하세요.
| JSON 표현 |
|---|
{ "agent": string } |
| 필드 | |
|---|---|
agent |
(선택사항) 사용할 에이전트의 이름입니다. |
AgentsSpec
요청을 처리하는 데 사용되는 에이전트의 사양입니다.
| JSON 표현 |
|---|
{ "agentSpecs": [ { object ( |
| 필드 | |
|---|---|
agentSpecs[] |
(선택사항) 요청을 처리하는 데 사용되는 에이전트의 사양입니다. |
mentionMode |
(선택사항) |
AgentSpec
에이전트 사양입니다.
| JSON 표현 |
|---|
{ "agentId": string, "inputVariables": { object } } |
| 필드 | |
|---|---|
agentId |
필수 항목입니다. 요청을 처리하는 상담사 리소스를 식별하는 ID입니다. 이 필드는 RFC-1034를 준수해야 하며 길이 제한은 63자(영문 기준)입니다. |
inputVariables |
(선택사항) WorkflowAgent의 호출 시간에 제공된 입력 변수입니다. 키는 선언된 입력 변수 이름이고 값은 사용자 또는 호출자가 제공한 값입니다. 다운스트림 노드에 전역 입력으로 노출됩니다. |
MentionMode
agentSpecs에서 언급된 에이전트를 호출하는 방법
| 열거형 | |
|---|---|
MENTION_MODE_UNSPECIFIED |
기본값은 DIRECT입니다. |
DIRECT |
멘션된 에이전트가 턴을 실행하는 최상위 에이전트가 됩니다. agentSpecs에는 하나의 항목만 허용됩니다. |
TOOL |
각 AgentSpec는 합성된 오케스트레이터 아래에 도구로 연결됩니다. 다중 멘션 MVP: 워크플로 에이전트만 해당, 최신 게시 버전; version / revisionId을 설정하지 마세요. |
TOOL_WORKFLOW_DIRECT |
단일 워크플로 상담사가 자체 채팅 서페이스로 표시됩니다. AgentSpec가 하나여야 합니다. version = "draft" (상담사 표) 또는 revisionId (특정 AgentRevision)를 설정합니다. 워크플로에 ManualTrigger가 있어야 합니다. |
ToolsSpec
요청을 처리하는 데 사용되는 도구의 사양입니다.
| JSON 표현 |
|---|
{ "toolRegistry": string, "vertexAiSearchSpec": { object ( |
| 필드 | |
|---|---|
toolRegistry |
(선택사항) 사용할 도구 레지스트리의 이름입니다. 형식: |
vertexAiSearchSpec |
(선택사항) Vertex AI Search 도구의 사양입니다. |
webGroundingSpec |
(선택사항) 웹 그라운딩 도구의 사양입니다. 필드가 있으면 웹 검색을 사용한 그라운딩을 사용 설정합니다. |
imageGenerationSpec |
(선택사항) 이미지 생성 도구의 사양입니다. |
videoGenerationSpec |
(선택사항) 동영상 생성 도구의 사양입니다. |
mapsGroundingSpec |
(선택사항) Google 지도 그라운딩 도구의 사양입니다. 필드가 있으면 Google 지도 기반 그라운딩을 사용 설정합니다. |
VertexAiSearchSpec
Vertex AI Search 도구의 사양입니다.
| JSON 표현 |
|---|
{
"disabled": boolean,
"dataStoreSpecs": [
{
object ( |
| 필드 | |
|---|---|
disabled |
(선택사항) 지원 중단되었습니다. 이 필드를 사용하지 마세요. Vertex AI Search 도구가 사용 중지되었는지 여부입니다. 기본값은 false이며 도구는 기본적으로 사용 설정되어 있습니다. |
dataStoreSpecs[] |
(선택사항) 검색 호출에서 필터링할 |
filter |
(선택사항) 필터 구문은 필터링되는 문서의 필드 하나 이상에서 조건자를 구성하기 위한 표현식 언어로 구성됩니다. 필터 표현식은 대소문자를 구분합니다. 이 필드를 인식할 수 없으면 Vertex AI Search의 필터링은 LHS 필터 키를 Vertex AI Search 백엔드에 정의된 키 속성에 매핑하여 실행됩니다. 이 매핑은 고객이 스키마에 정의합니다. 예를 들어 미디어 고객의 스키마에는 'name' 필드가 있을 수 있습니다. 이 경우 필터는 filter --> name:'ANY("king kong")'입니다. 구문 및 필터 연산자를 비롯한 필터링에 대한 자세한 내용은 필터를 참고하세요. |
WebGroundingSpec
이 유형에는 필드가 없습니다.
웹 그라운딩 도구의 사양입니다.
ImageGenerationSpec
이 유형에는 필드가 없습니다.
이미지 생성 도구의 사양입니다.
VideoGenerationSpec
이 유형에는 필드가 없습니다.
동영상 생성 도구의 사양입니다.
MapsGroundingSpec
이 유형에는 필드가 없습니다.
Google 지도 그라운딩 도구의 사양입니다.
GenerationSpec
요청에 대한 어시스턴트 생성 사양입니다. 이렇게 하면 엔진 수준에서 기본 생성 구성을 재정의할 수 있습니다.
| JSON 표현 |
|---|
{ "modelId": string } |
| 필드 | |
|---|---|
modelId |
(선택사항) 생성형 모델에 사용되는 Vertex AI modelId입니다. 설정하지 않으면 기본 어시스턴트 모델이 사용됩니다. |
ActionSpec
요청의 작업 사양입니다.
| JSON 표현 |
|---|
{ "actionDisabled": boolean } |
| 필드 | |
|---|---|
actionDisabled |
(선택사항) true인 경우 요청에 대해 작업이 제공되지 않습니다. 이 기능은 엔터프라이즈 버전에서만 작동합니다. |
SessionInfo
세션에 관한 정보입니다.
| JSON 표현 |
|---|
{ "session": string, "queryId": string } |
| 필드 | |
|---|---|
session |
새로 생성되거나 계속된 세션의 이름입니다. 형식은 |
queryId |
이 지원 API 호출에 해당하는 쿼리 ID입니다. 하나의 세션에는 고유한 쿼리 ID가 있는 여러 턴이 있을 수 있습니다. assistants.assist API 호출에서 세션 이름과 이 쿼리 ID를 지정하면 이 검색 호출의 검색 결과 컨텍스트에서 지원 요청이 발생합니다. |
StatusUpdate
지원 통화 진행 상황에 관한 업데이트입니다.
| JSON 표현 |
|---|
{ "updateText": string, "invocationId": string } |
| 필드 | |
|---|---|
updateText |
자유 형식 텍스트 상태 업데이트입니다(예: '혜택에 관한 HR 문서에서 내부 검색 시작', '웹 검색에서 '달 착륙' 검색 결과 12개 표시'). |
invocationId |
업데이트를 생성하는 호출의 고유 식별자입니다. |
ToolResult
도구 호출의 (부분) 결과입니다.
| JSON 표현 |
|---|
{
"toolInvocationId": string,
"result": {
object ( |
| 필드 | |
|---|---|
toolInvocationId |
결과를 생성하는 도구 호출의 고유 식별자입니다. |
result |
결과의 일부 콘텐츠입니다. |
InvokedSkill
지원 통화 중에 사용된 스킬을 나타냅니다.
| JSON 표현 |
|---|
{ "name": string, "displayName": string } |
| 필드 | |
|---|---|
name |
스킬의 리소스 이름입니다. |
displayName |
스킬의 표시 이름입니다. |
ConnectorAuthError
특정 데이터 커넥터의 인증 오류를 설명합니다.
| JSON 표현 |
|---|
{ "dataConnector": string, "errorMessage": string } |
| 필드 | |
|---|---|
dataConnector |
인증에 실패한 데이터 커넥터의 리소스 이름입니다. |
errorMessage |
인증 실패를 설명하는 사람이 읽을 수 있는 오류 메시지입니다. |