- HTTP 요청
- 경로 매개변수
- 요청 본문
- 응답 본문
- 승인 범위
- IAM 권한
- AssistantConfirmationResponse
- StreamChatAiAssistantRequest.ClientCapability
- OperationCompletedEvent
- ArtifactChunk
- ArtifactChunk.State
- OptionQuestionsChunk
- OptionQuestionsChunk.Question
- OptionQuestionsChunk.Option
- AssistantConfirmationRequest
- AssistantConfirmationRequest.Target
- TurnResumeSnapshot
- TurnHandoffEvent
- TurnHandoffEvent.Reason
- TurnCompletedEvent
- TurnCompletedEvent.Reason
- TurnMetadata
- TurnMetadata.ContractStreamingPhase
지정된 어시스턴트 세션에 대해 AI 어시스턴트인 Arc를 스트리밍 방식으로 실행합니다.
HTTP 요청
POST https://ces.googleapis.com/v1beta/{name=projects/*/locations/*/apps/*/assistantSessions/*}:streamChatAiAssistant
URL은 gRPC 트랜스코딩 문법을 사용합니다.
경로 매개변수
| 매개변수 | |
|---|---|
name |
필수 항목입니다. 어시스턴트를 실행하는 데 사용할 어시스턴트 세션입니다. 형식: |
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
| JSON 표현 |
|---|
{ "message": string, "attachedGcsUris": [ string ], "contextToken": string, "confirmationResponse": { object ( |
| 필드 | |
|---|---|
message |
(선택사항) 어시스턴트 에이전트에 보낼 메시지입니다. |
attachedGcsUris[] |
(선택사항) 이 차례에 사용자가 업로드한 파일의 Cloud Storage URI입니다. 예: 'gs://cxas-transient-uploads/uuid/prd.pdf' |
contextToken |
(선택사항) |
confirmationResponse |
(선택사항) 대기 중인 |
clientCapabilities[] |
(선택사항) 이 클라이언트가 렌더링할 수 있는 응답 기능입니다. 서버는 기능이 선언된 경우에만 기능이 필요한 이벤트(예: |
operationCompletedEvent |
(선택사항) 클라이언트 관리 장기 실행 작업이 완료될 때까지 기다리는 동안 일시중지된 어시스턴트 세션을 재개합니다. |
resumeFromSequenceNumber |
(선택사항) 진행 중이거나 완료된 차례에서 이벤트를 재개하고 재생하는 선택적 커서입니다. |
attachOnly |
(선택사항) 새 메시지를 제출하지 않고 기존 진행 중인 대화에 연결하는 선택적 플래그입니다. |
응답 본문
SessionService.StreamChatAiAssistant의 응답 메시지입니다.
성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.
| JSON 표현 |
|---|
{ "eventId": string, "eventTime": string, "uiEvent": { object ( |
| 필드 | |
|---|---|
eventId |
이벤트의 고유 식별자입니다. |
eventTime |
이벤트가 발생한 시점의 타임스탬프입니다. 생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 |
uiEvent |
(선택사항) UI 이벤트 페이로드입니다. |
turnMetadata |
(선택사항) 대화 수준 메타데이터 및 의도 분류 |
sequenceNumber |
(선택사항) 이 세션 차례의 단조 증가 시퀀스 번호입니다. |
turnInProgress |
(선택사항) 차례가 백그라운드에서 계속 실행 중인지 여부를 나타냅니다. |
| 이벤트 페이로드입니다. 다음은 상호 배타적인 필드 목록입니다. 응답에서 최대 하나의 필드가 설정됩니다. | |
textChunk |
텍스트 토큰(Gemini 대답을 단어별로 스트리밍하는 경우) |
status |
간단한 상태 업데이트입니다. |
thoughtChunk |
사고 텍스트 청크(응답을 생성하기 전 에이전트의 추론) |
toolCall |
도구 호출 실행 이벤트입니다. |
toolResponse |
도구 호출 응답 이벤트입니다. |
artifactChunk |
생성된 문서 아티팩트 이벤트(실시간 미리보기 델타 + 최종 Cloud Storage 포인터) |
optionQuestionsChunk |
모델 차례에서 파싱된 구조화된 명확성 옵션입니다. 콘솔은 이를 원시 텍스트 대신 선택 가능한 옵션 목록으로 렌더링합니다. |
confirmationRequest |
에이전트가 일시중지된 차단 확인입니다. 이후 요청의 |
sessionCheckpoint |
사용자 의도 및 롤링 요약이 포함된 세션 체크포인트/압축 요약 이벤트입니다. |
resumeSnapshot |
진행 중인 차례의 압축된 재생으로, 실시간 이벤트 전에 모든 연결 또는 재개의 첫 번째 이벤트로 전송됩니다. 클라이언트는 이 차례에 로컬로 렌더링된 상태를 스냅샷의 콘텐츠로 대체합니다. |
handoff |
클라이언트에게 resumeFromSequenceNumber를 사용하여 자동으로 다시 연결하도록 지시합니다. 이 스트림을 제공하는 태스크가 사라지고 다른 곳에서 차례가 계속됩니다. 오류가 아닙니다. 이 이벤트 이후 스트림이 정상적으로 완료됩니다. |
turnCompleted |
차례가 종료되었습니다. 클라이언트가 스트림 종료에서 추론하는 대신 명시적 신호로 차례를 종료할 수 있도록 원래 스트림과 연결되거나 재개된 모든 스트림에서 모든 차례의 마지막 이벤트로 전송됩니다. |
| 상호 배타적 필드의 끝입니다. | |
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/ces
자세한 내용은 Authentication Overview에서 확인하세요.
IAM 권한
name 리소스에 대해서는 다음 IAM 권한이 필요합니다.
ces.assistantSessions.get
자세한 내용은 IAM 문서를 참조하세요.
AssistantConfirmationResponse
AssistantConfirmationRequest에 대한 사용자의 답변으로, 일시중지된 에이전트를 재개하기 위해 다음 SessionService.StreamChatAiAssistant 호출에서 전송됩니다.
| JSON 표현 |
|---|
{ "confirmationId": string, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "confirmed": boolean, "answerText": string // End of mutually exclusive fields. } |
| 필드 | |
|---|---|
confirmationId |
|
| 사용자의 답변입니다. 다음은 상호 배타적인 필드 목록입니다. 응답에서 최대 하나의 필드가 설정됩니다. | |
confirmed |
이진 답변: true는 일시중지된 작업을 승인하고 false는 거부합니다. |
answerText |
선택한 옵션의 submitText 또는 자유 형식 사용자 텍스트입니다. 일시중지된 작업이 취소되고 텍스트가 상담사에게 전달되어 처리됩니다. |
| 상호 배타적 필드의 끝입니다. | |
StreamChatAiAssistantRequest.ClientCapability
클라이언트가 선언할 수 있는 응답 기능입니다.
| 열거형 | |
|---|---|
CLIENT_CAPABILITY_UNSPECIFIED |
지정되지 않은 기능입니다. 무시됩니다. |
CONFIRMATION_CARDS |
클라이언트는 AssistantConfirmationRequest 카드를 렌더링하고 confirmationResponse를 통해 답변합니다. |
CLIENT_MANAGED_LRO |
클라이언트는 작업을 폴링하고 operationCompletedEvent를 전송하여 차례를 재개함으로써 대역 외 장기 실행 작업을 관리합니다. 선언되지 않으면 서버가 LRO 폴링을 관리하고 대화를 인라인으로 완료합니다. |
PROJECT_SCOPE |
클라이언트는 프로젝트 범위 이벤트를 렌더링합니다. 카드 typedPayload개, 도구 호출 및 응답 targetApp개, 확인 요청 targets개, 차례 완료 touchedApps개입니다. |
OperationCompletedEvent
비동기 장기 실행 작업(LRO)이 완료된 후 어시스턴트 세션을 재개하기 위해 클라이언트 또는 백그라운드 작업자가 전송하는 이벤트입니다.
| JSON 표현 |
|---|
{
"operationName": string,
"targetResourceName": string,
"operationType": string,
"status": string,
"deduplicationToken": string,
"error": {
object ( |
| 필드 | |
|---|---|
operationName |
작업 리소스 이름입니다(예: |
targetResourceName |
작업의 대상이 되거나 작업에 의해 생성되는 기본 리소스입니다(예: 평가 실행 ID, 앱 ID, 데이터 세트 ID). |
operationType |
작업 유형 또는 도구 이름입니다(예: 'run_evaluation', 'copy_app', 'export_app'). |
status |
작업 실행 상태입니다(예: 'SUCCEEDED', 'FAILED', 'CANCELLED'). |
deduplicationToken |
동시 브라우저 탭에서 중복된 차례 실행을 방지하기 위한 선택적 중복 삭제 토큰(예: UUID)입니다. |
error |
작업이 실패한 경우의 표준 오류 상태입니다(선택사항). |
metadata |
선택사항인 구조화된 결과 메타데이터(예: pass_rate, total_examples, export_uri)입니다. |
ArtifactChunk
어시스턴트가 생성하는 문서 아티팩트(예: 마크다운 TDD)의 스트리밍된 프래그먼트입니다. 문서가 작성되는 동안 콘텐츠 델타가 스트리밍되므로 클라이언트가 실시간 미리보기를 렌더링할 수 있습니다. 파일이 유지되면 FINALIZED 청크가 Cloud Storage URI를 전달합니다.
| JSON 표현 |
|---|
{
"artifactId": string,
"displayName": string,
"mimeType": string,
"contentDelta": string,
"gcsUri": string,
"state": enum ( |
| 필드 | |
|---|---|
artifactId |
아티팩트의 식별자이며 스트림 내 한 아티팩트의 모든 청크에서 안정적입니다. |
displayName |
사용자에게 표시되는 파일 이름입니다(예: 'hotel_booking_tdd.md'). STARTED에서 설정되고 FINALIZED에서 반복됩니다. |
mimeType |
아티팩트 콘텐츠의 IANA 미디어 유형입니다(예: 'text/markdown'). |
contentDelta |
증분 아티팩트 콘텐츠 DELTA 청크에 설정됩니다. |
gcsUri |
아티팩트가 유지된 Cloud Storage 객체입니다. FINALIZED 청크에 설정됩니다. |
state |
이 청크의 수명 주기 위치입니다. |
targetApp |
출력 전용입니다. 이 아티팩트가 생성된 앱입니다(앱용으로 생성된 경우). 형식: |
ArtifactChunk.State
아티팩트 스트림 내에서 이 청크의 수명 주기 위치입니다.
| 열거형 | |
|---|---|
STATE_UNSPECIFIED |
사용되지 않는 기본값입니다. |
STARTED |
어시스턴트가 아티팩트 생성을 시작했습니다. |
DELTA |
콘텐츠 증분입니다. contentDelta가 설정됩니다. |
FINALIZED |
아티팩트가 유지되었습니다. gcsUri가 설정되었습니다. |
FAILED |
생성 또는 지속성 실패: 아티팩트가 저장되지 않았습니다. |
CLOSED |
문서 스트리밍이 완료되었습니다. 콘텐츠가 contentDelta 청크를 통해 완전히 전송되었습니다. 지속성은 계속 유지될 수 있습니다. 아티팩트가 저장되면 gcsUri가 포함된 FINALIZED 청크가 전송됩니다. |
OptionQuestionsChunk
어시스턴트가 사용자에게 선택하도록 요청하는 구조화된 설명 옵션으로, 모델의 차례에서 서버 측으로 변환됩니다(옵션 블록은 스트리밍되고 유지되는 텍스트에서 제거됨). 콘솔은 작성기 위에 도킹된 키보드 탐색 가능 옵션 목록을 렌더링합니다.
| JSON 표현 |
|---|
{
"questions": [
{
object ( |
| 필드 | |
|---|---|
questions[] |
이번 차례에 질문한 내용입니다. 항목이 두 개 이상이면 콘솔의 'N개 중 1개' 페이저가 실행됩니다. |
OptionQuestionsChunk.Question
옵션이 있는 질문 1개
| JSON 표현 |
|---|
{
"question": string,
"options": [
{
object ( |
| 필드 | |
|---|---|
question |
질문 헤더 텍스트입니다. |
options[] |
선택 가능한 옵션(표시 순서)입니다. |
OptionQuestionsChunk.Option
선택 가능한 단일 옵션입니다.
| JSON 표현 |
|---|
{ "title": string, "details": string, "submitText": string } |
| 필드 | |
|---|---|
title |
짧은 일반 텍스트 옵션 제목(마크다운 없음, 번호 매기기 없음) |
details |
보조 텍스트로 표시되는 선택적 장단점 세부정보입니다. |
submitText |
옵션을 선택할 때 전송할 메시지 텍스트입니다(선택사항). 비어 있으면 기본값은 |
AssistantConfirmationRequest
상담사 작업을 진행하기 전에 어시스턴트가 답변해야 하는 차단 질문 또는 확인입니다. 요청 에이전트는 일시중지되고 이후 StreamChatAiAssistantRequest.confirmation_response에 답변이 도착할 때만 재개됩니다.
| JSON 표현 |
|---|
{ "confirmationId": string, "context": string, "positiveLabel": string, "negativeLabel": string, "questions": [ { object ( |
| 필드 | |
|---|---|
confirmationId |
이 요청을 응답과 연결하는 식별자입니다. 클라이언트에 불투명합니다. 응답 요청에 그대로 반영되어야 합니다. |
context |
확인 중인 내용을 설명하는 컨텍스트입니다(예: 에이전트가 수행하려는 작업 또는 답변이 필요한 질문). 마크다운이 아닌 일반 텍스트로 렌더링됩니다. |
positiveLabel |
바이너리 확인의 승인 작업 라벨입니다(예: '게시'). |
negativeLabel |
바이너리 확인의 거부 작업 라벨입니다(예: '아직 아님'). |
questions[] |
확인의 객관식 양식입니다. 채워지면 카드는 선택 가능한 옵션 목록을 렌더링하고 선택한 옵션의 submitText(또는 자유 형식 사용자 텍스트)가 |
tool |
에이전트가 일시중지한 도구 호출의 이름입니다(예: 'update_app'). 카드 헤더에 사용됩니다. 순수한 질문의 경우 설정 해제합니다. |
agentName |
카드 헤더에 확인을 요청한 에이전트의 표시 라벨(예: |
expireTime |
이 확인에 더 이상 응답할 수 없는 시간입니다. 만료된 카드는 비활성 상태로 렌더링되고 서버는 다음 차례에 확인을 거부하므로 일시중지된 상담사가 무기한 대기하지 않습니다. 생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 |
targets[] |
확인된 작업이 변경하는 모든 항목입니다. 콘솔에서 '앱 2개 업데이트'와 앱당 배지 1개를 렌더링할 수 있습니다. 기존 단일 타겟 카드의 경우 비어 있습니다. |
AssistantConfirmationRequest.Target
확인된 작업으로 변경될 리소스 1개
| JSON 표현 |
|---|
{ "resource": string, "displayName": string, "action": string, "targetApp": string } |
| 필드 | |
|---|---|
resource |
변경될 리소스입니다(전체 리소스 이름). |
displayName |
카드에 표시되는 리소스 또는 앱의 표시 이름입니다. |
action |
작업(예: |
targetApp |
리소스가 속한 앱입니다. 앱 만들기와 같은 위치 범위 작업의 경우 비어 있습니다. 형식: |
TurnResumeSnapshot
진행 중인 차례의 압축된 다시보기: 지금까지 차례의 표시되는 출력을 렌더링하는 데 필요한 모든 항목과 실시간 이벤트가 계속되는 위치입니다.
| JSON 표현 |
|---|
{
"turnId": string,
"resolvedSequenceNumber": string,
"events": [
{
object ( |
| 필드 | |
|---|---|
turnId |
연결되는 대화를 식별합니다. |
resolvedSequenceNumber |
이 스냅샷이 나타내는 위치입니다. 실시간 이벤트는 이보다 엄격하게 큰 sequenceNumber로 이어집니다. 클라이언트가 요청한 resumeFromSequenceNumber보다 낮은 경우 플러시된 진행률은 클라이언트가 이미 렌더링한 것보다 지연됩니다. 클라이언트는 스냅샷을 적용하기 전에 이 위치를 초과하는 이 차례의 렌더링된 콘텐츠를 삭제해야 합니다. |
events[] |
라이브 스트리밍과 동일한 이벤트 형태를 사용하여 대화의 표시되는 출력을 렌더링 순서대로 재구성하는 압축된 이벤트입니다. |
orphanDeadlineTime |
연결된 클라이언트가 없는 경우 차례가 종료되는 시점입니다. 생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 |
TurnHandoffEvent
이 태스크가 대화 중간에 스트림 제공을 중지하기 전에 발생합니다(예: 서버 다시 시작). 차례의 상태가 유지됩니다. resumeFromSequenceNumber를 전달하는 재연결은 다른 작업에서 이를 계속합니다.
| JSON 표현 |
|---|
{
"turnId": string,
"reason": enum ( |
| 필드 | |
|---|---|
turnId |
재개할 차례를 식별합니다. |
reason |
스트림이 핸드오프되는 이유입니다. |
TurnHandoffEvent.Reason
스트림이 핸드오프되는 이유입니다.
| 열거형 | |
|---|---|
REASON_UNSPECIFIED |
지정되지 않음. |
SERVER_RESTART |
서빙 태스크가 종료됩니다(출시 푸시 또는 일정 변경). |
TurnCompletedEvent
차례의 터미널 이벤트입니다(StreamChatAiAssistantResponse.turn_completed 참고).
| JSON 표현 |
|---|
{
"turnId": string,
"reason": enum ( |
| 필드 | |
|---|---|
turnId |
종료된 턴의 식별자입니다. TurnResumeSnapshot.turn_id 및 ActiveTurnInfo.turn_id와 일치합니다. |
reason |
차례가 종료된 이유입니다. |
finalSequenceNumber |
차례에서 생성된 마지막 이벤트의 시퀀스 넘버입니다. 커서가 더 낮은 클라이언트는 콘텐츠를 놓쳤으므로 세션을 새로고침해야 콘텐츠를 볼 수 있습니다. |
touchedApps[] |
이번에 타겟팅되거나 변경된 앱이므로 Console에서 해당 앱의 스토어를 정확하게 새로고침할 수 있습니다. 프로젝트 범위 세션만 해당합니다. 형식: |
TurnCompletedEvent.Reason
차례가 종료된 이유. 따라서 늦게 연결된 클라이언트는 빈 스트림에서 추측하는 대신 결과를 표현할 수 있습니다.
| 열거형 | |
|---|---|
REASON_UNSPECIFIED |
지정되지 않음. |
COMPLETED |
차례가 완료될 때까지 실행되었습니다. 세션은 커밋된 출력을 보유합니다. |
ABANDONED |
더 이상 작업을 진행하는 태스크가 없었습니다. 커밋된 부분으로 봉인되어 계속할 수 없습니다. |
RESUME_UNAVAILABLE |
이 서버는 세션에 대한 연결 또는 재개를 제공하지 않으므로 아무것도 추적되지 않았습니다. 대신 클라이언트가 세션을 새로고침해야 합니다. |
TurnMetadata
대화 수준 메타데이터 및 의도 분류
| JSON 표현 |
|---|
{
"contractRelated": boolean,
"contractFinalized": boolean,
"contractStreamingPhase": enum ( |
| 필드 | |
|---|---|
contractRelated |
이 어시스턴트 차례가 계약 관련(예: 계약 초안 작성, 조정, 추출 또는 수정)인지 여부를 나타냅니다. |
contractFinalized |
계약 초안이 게시된(버전이 활성화된) 차례의 최종 아티팩트 이벤트에 설정됩니다. 이 초안의 명확화 흐름을 위한 터미널: contractProgress는 권위 있고 완전합니다. |
contractStreamingPhase |
계약 아티팩트 펜스가 스트리밍되는 동안 내보낸 진행 중인 진행률 추정치와 revision-turn-start 이벤트에만 설정됩니다. 정식 페이로드에서 설정 해제됩니다. |
contractDraftComplete |
모든 자리표시자가 확인된 계약 초안의 터미널 이벤트에 설정됩니다(contractProgress는 100%). 초안이 게시되었는지 여부는 관계없습니다. 클라이언트는 계약 진행 상황 표시를 완료하고 닫습니다. 게시는 contractFinalized에 의해 별도로 보고됩니다. |
TurnMetadata.ContractStreamingPhase
계약 진행 상황 페이로드의 스트리밍 단계입니다.
| 열거형 | |
|---|---|
CONTRACT_STREAMING_PHASE_UNSPECIFIED |
페이로드는 신뢰할 수 있습니다(완전한 계약 문서, 지속된 스냅샷 또는 초안 전 상태에서 계산됨). 클라이언트는 이전에 수신한 진행 상황을 이 진행 상황으로 대체해야 합니다. |
DRAFTING |
초기 계약 초안이 스트리밍 중입니다. contractProgress는 진행 중인 추정치입니다. 하나의 아티팩트 경계 내에서 감소하지 않고, 권위 있는 범위 아래로 제한되며, pillarBreakdowns는 totalItemCount == 0을 전달하여 추정된 필러 상태를 표시합니다. |
REVISING |
기존 계약의 수정 버전이 스트리밍 중입니다(예: 주석 제출 후). DRAFTING과 동일한 추정치 시맨틱스입니다. |