Method: projects.locations.apps.sessions.runSession

세션 내에서 CES 에이전트와의 단일 턴 상호작용을 시작합니다.

HTTP 요청

POST https://ces.googleapis.com/v1/{config.session=projects/*/locations/*/apps/*/sessions/*}:runSession

URL은 gRPC 트랜스코딩 문법을 사용합니다.

경로 매개변수

매개변수
config.session

string

필수 항목입니다. 세션의 고유 식별자입니다. 형식: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "config": {
    "session": string,
    "inputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer,
      "noiseSuppressionLevel": string
    },
    "outputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer
    },
    "historicalContexts": [
      {
        "role": string,
        "chunks": [
          {
            object (Chunk)
          }
        ],
        "eventTime": string
      }
    ],
    "entryAgent": string,
    "deployment": string,
    "timeZone": string,
    "remoteDialogflowQueryParameters": {
      "webhookHeaders": {
        string: string,
        ...
      },
      "payload": {
        object
      },
      "endUserMetadata": {
        object
      }
    }
  },
  "inputs": [
    {
      object (SessionInput)
    }
  ]
}
필드
config.inputAudioConfig

object (InputAudioConfig)

선택사항입니다. 입력 오디오 처리 구성입니다.
config.outputAudioConfig

object (OutputAudioConfig)

선택사항입니다. 출력 오디오를 생성하기 위한 구성입니다.
config.historicalContexts[]

object (Message)

선택사항입니다. 사용자 입력, 에이전트 응답, 기타 메시지를 포함한 세션의 이전 컨텍스트 일반적으로 CES 에이전트가 세션을 자동으로 관리하므로 클라이언트가 이 필드를 명시적으로 채울 필요가 없습니다. 하지만 클라이언트는 원하는 경우 이전 컨텍스트를 재정의하여 특정 상태에서 세션이 시작되도록 강제할 수 있습니다.
config.entryAgent

string

선택사항입니다. 세션을 처리할 진입 상담사입니다. 지정하지 않으면 세션이 앱의 root agent에 의해 처리됩니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

선택사항입니다. 세션에 사용할 앱의 배포입니다. 형식: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

선택사항입니다. 사용자의 시간대입니다. 제공된 경우 에이전트는 날짜 및 시간 관련 변수에 이 시간대를 사용합니다. 그렇지 않으면 에이전트가 App.time_zone_settings에 지정된 시간대를 사용합니다.

형식은 IANA 시간대 데이터베이스 시간대입니다(예: 'America/Los_Angeles').
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

선택사항입니다. 세션 제어가 원격 에이전트로 트랜스퍼될 때 원격 Dialogflow 에이전트로 전송할 QueryParameters입니다.
inputs[]

object (SessionInput)

필수 항목입니다. 세션의 입력입니다.

응답 본문

SessionService.RunSession의 응답 메시지입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
필드
outputs[]

object (SessionOutput)

세션의 출력입니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

자세한 내용은 Authentication Overview에서 확인하세요.

IAM 권한

session 리소스에 대해서는 다음 IAM 권한이 필요합니다.

  • ces.sessions.runSession

자세한 내용은 IAM 문서를 참조하세요.

SessionConfig

세션의 구성입니다.

JSON 표현 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
필드
session

string

필수 항목입니다. 세션의 고유 식별자입니다. 형식: projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

선택사항입니다. 입력 오디오 처리 구성입니다.
outputAudioConfig

object (OutputAudioConfig)

선택사항입니다. 출력 오디오를 생성하기 위한 구성입니다.
historicalContexts[]

object (Message)

선택사항입니다. 사용자 입력, 에이전트 응답, 기타 메시지를 포함한 세션의 이전 컨텍스트 일반적으로 CES 에이전트가 세션을 자동으로 관리하므로 클라이언트가 이 필드를 명시적으로 채울 필요가 없습니다. 하지만 클라이언트는 원하는 경우 이전 컨텍스트를 재정의하여 특정 상태에서 세션이 시작되도록 강제할 수 있습니다.
entryAgent

string

선택사항입니다. 세션을 처리할 진입 상담사입니다. 지정하지 않으면 세션이 앱의 root agent에 의해 처리됩니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

선택사항입니다. 세션에 사용할 앱의 배포입니다. 형식: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

선택사항입니다. 사용자의 시간대입니다. 제공된 경우 에이전트는 날짜 및 시간 관련 변수에 이 시간대를 사용합니다. 그렇지 않으면 에이전트가 App.time_zone_settings에 지정된 시간대를 사용합니다.

형식은 IANA 시간대 데이터베이스 시간대입니다(예: 'America/Los_Angeles').
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

선택사항입니다. 세션 제어가 원격 에이전트로 트랜스퍼될 때 원격 Dialogflow 에이전트로 전송할 QueryParameters입니다.

InputAudioConfig

InputAudioConfig는 CES 에이전트가 수신되는 오디오 데이터를 해석하는 방법을 구성합니다.

JSON 표현 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
필드
audioEncoding

enum (AudioEncoding)

필수 항목입니다. 입력 오디오 데이터의 인코딩입니다.
sampleRateHertz

integer

필수 항목입니다. 입력 오디오 데이터의 샘플링 레이트 (Hz)입니다.
noiseSuppressionLevel

string

선택사항입니다. 입력 오디오에서 주변 소음 제거를 사용 설정할지 여부입니다. 사용 가능한 값은 'low', 'moderate', 'high', 'very_high'입니다.

AudioEncoding

AudioEncoding은 오디오 데이터의 인코딩 형식을 지정합니다.

열거형
AUDIO_ENCODING_UNSPECIFIED 지정되지 않은 오디오 인코딩입니다.
LINEAR16 16비트 선형 PCM 오디오 인코딩입니다.
MULAW G.711 PCMU/mu-law를 사용하여 14비트 오디오 샘플을 압축하는 8비트 샘플입니다.
ALAW G.711 PCMU/A-law를 사용하여 14비트 오디오 샘플을 압축하는 8비트 샘플입니다.

OutputAudioConfig

OutputAudioConfig는 CES 에이전트가 나가는 오디오 응답을 합성하는 방식을 구성합니다.

JSON 표현 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
필드
audioEncoding

enum (AudioEncoding)

필수 항목입니다. 출력 오디오 데이터의 인코딩입니다.
sampleRateHertz

integer

필수 항목입니다. 출력 오디오 데이터의 샘플링 레이트 (Hz)입니다.

SessionConfig.RemoteDialogflowQueryParameters

세션 제어가 원격 에이전트로 트랜스퍼될 때 원격 Dialogflow 에이전트로 전송할 QueryParameters입니다.

JSON 표현 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
필드
webhookHeaders

map (key: string, value: string)

선택사항입니다. QueryParameters에서 webhookHeaders로 전송될 HTTP 헤더입니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
payload

object (Struct format)

선택사항입니다. QueryParameters로 전송할 페이로드입니다.
endUserMetadata

object (Struct format)

선택사항입니다. QueryParameters에 전송할 최종 사용자 메타데이터입니다.

SessionInput

세션의 입력입니다.

JSON 표현 
{
  "willContinue": boolean,

  // Union field input_type can be only one of the following:
  "text": string,
  "dtmf": string,
  "audio": string,
  "toolResponses": {
    object (ToolResponses)
  },
  "image": {
    object (Image)
  },
  "blob": {
    object (Blob)
  },
  "variables": {
    object
  },
  "event": {
    object (Event)
  }
  // End of list of possible types for union field input_type.
}
필드
willContinue

boolean

선택사항입니다. 현재 메시지가 양방향 스트리밍 세션에서 더 큰 입력의 프래그먼트인지 나타내는 플래그입니다.

true로 설정하면 에이전트는 willContinue이 false인 후속 메시지를 수신할 때까지 또는 시스템이 오디오 입력에서 엔드포인트를 감지할 때까지 처리를 지연합니다.

참고: 이 필드는 오디오 및 DTMF 입력에는 적용되지 않습니다. 엔드포인팅 신호에 따라 항상 자동으로 처리되기 때문입니다.
통합 필드 input_type. 입력의 유형입니다. input_type은 다음 중 하나여야 합니다.
text

string

선택사항입니다. 최종 사용자의 텍스트 데이터입니다.
dtmf

string

선택사항입니다. 최종 사용자의 DTMF 숫자입니다.
audio

string (bytes format)

선택사항입니다. 최종 사용자의 오디오 데이터입니다.

base64 인코딩 문자열입니다.
toolResponses

object (ToolResponses)

선택사항입니다. 클라이언트의 도구 호출 실행 결과입니다.
image

object (Image)

선택사항입니다. 최종 사용자의 이미지 데이터입니다.
blob

object (Blob)

선택사항입니다. 최종 사용자의 BLOB 데이터입니다.
variables

object (Struct format)

선택사항입니다. 세션의 컨텍스트 변수입니다. 이름으로 키가 지정됩니다. 앱에서 선언된 변수만 CES 에이전트에서 사용됩니다.

인식되지 않는 변수는 [Dialogflow 에이전트][Agent.RemoteDialogflowAgent] 에 추가 세션 매개변수로 계속 전송됩니다.
event

object (Event)

선택사항입니다. 이벤트 입력입니다.

ToolResponses

클라이언트에서 요청한 도구 호출의 실행 결과입니다.

JSON 표현 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
필드
toolResponses[]

object (ToolResponse)

선택사항입니다. 도구 실행 결과 목록입니다.

이벤트

이벤트 입력입니다.

JSON 표현 
{
  "event": string
}
필드
event

string

필수 항목입니다. 이벤트 이름입니다.

SessionOutput

세션의 출력입니다.

JSON 표현 
{
  "turnIndex": integer,
  "turnCompleted": boolean,
  "diagnosticInfo": {
    object (SessionOutput.DiagnosticInfo)
  },

  // Union field output_type can be only one of the following:
  "text": string,
  "audio": string,
  "toolCalls": {
    object (ToolCalls)
  },
  "citations": {
    object (Citations)
  },
  "googleSearchSuggestions": {
    object (GoogleSearchSuggestions)
  },
  "endSession": {
    object (EndSession)
  },
  "payload": {
    object
  }
  // End of list of possible types for union field output_type.
}
필드
turnIndex

integer

이 출력이 속한 대화 턴의 순서를 나타냅니다(1부터 시작).
turnCompleted

boolean

true인 경우 CES 에이전트가 현재 대화 턴의 끝을 감지했으며 이 턴에 대한 추가 출력을 제공하지 않습니다.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

선택사항입니다. 진단 정보에는 입력을 처리하는 동안의 실행 세부정보가 포함됩니다. 각 턴의 마지막 SessionOutput (turnCompleted=true 포함)에서만 채워집니다.
통합 필드 output_type. 출력 유형입니다. output_type은 다음 중 하나여야 합니다.
text

string

CES 에이전트의 출력 텍스트입니다.
audio

string (bytes format)

CES 에이전트의 오디오를 출력합니다.

base64 인코딩 문자열입니다.
toolCalls

object (ToolCalls)

클라이언트가 도구를 실행하도록 요청합니다.
citations

object (Citations)

에이전트가 생성한 텍스트의 소스 정보를 제공하는 인용입니다.
googleSearchSuggestions

object (GoogleSearchSuggestions)

GoogleSearchTool 호출의 결과로 Google 검색에서 반환된 제안입니다.
endSession

object (EndSession)

세션이 종료되었음을 나타냅니다.
payload

object (Struct format)

CES 에이전트의 구조화된 출력이 포함된 맞춤 페이로드

ToolCalls

클라이언트가 도구를 실행하고 세션을 계속하기 전에 실행 결과를 반환하도록 요청합니다.

JSON 표현 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
필드
toolCalls[]

object (ToolCall)

선택사항입니다. 실행할 도구 호출 목록입니다.

인용

에이전트 응답과 연결된 인용입니다.

JSON 표현 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
필드
citedChunks[]

object (Citations.CitedChunk)

인용된 정보 목록입니다.

Citations.CitedChunk

인용된 정보입니다.

JSON 표현 
{
  "uri": string,
  "title": string,
  "text": string
}
필드
uri

string

인용에 사용된 URI입니다.
title

string

인용된 문서의 제목입니다.
text

string

인용에 사용된 텍스트입니다.

GoogleSearchSuggestions

Google Search Tool의 추천 검색어

JSON 표현 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
필드
htmls[]

string

추천 검색어에 대한 규정을 준수하는 HTML 및 CSS 스타일입니다. 제공된 HTML 및 CSS는 기기 설정에 따라 자동으로 조정되어 @media(prefers-color-scheme)로 표시된 밝거나 어두운 모드로 표시됩니다.
webSearchQueries[]

object (WebSearchQuery)

Google 검색을 수행하는 데 사용된 쿼리 목록과 검색 추천을 구성하는 검색 결과 URI입니다.

WebSearchQuery

단일 웹 검색어와 연결된 검색 URI를 나타냅니다.

JSON 표현 
{
  "query": string,
  "uri": string
}
필드
query

string

검색어 텍스트입니다.
uri

string

질문에 대한 Google 검색 결과 페이지의 URI입니다.

EndSession

성공적인 완료 (예: 사용자가 '안녕'이라고 말함) 또는 오류로 인해 세션이 종료되었음을 나타냅니다. ) 또는 상담사 에스컬레이션입니다.

상담사는 세션이 종료된 후 추가 입력을 처리하지 않으며 클라이언트는 상담사로부터 나머지 응답을 모두 수신한 후 절반만 닫고 연결을 해제해야 합니다.

JSON 표현 
{
  "metadata": {
    object
  }
}
필드
metadata

object (Struct format)

선택사항입니다. 세션 종료 이유와 같은 세션 종료 신호에 관한 추가 정보를 제공합니다.

SessionOutput.DiagnosticInfo

처리 중 실행 세부정보를 포함합니다.

JSON 표현 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
필드
messages[]

object (Message)

처리 중에 발생한 메시지 목록입니다.
rootSpan

object (Span)

전체 요청 처리의 트레이스입니다. 루트 스팬으로 표시됩니다. 이 스팬에는 특정 작업의 중첩된 하위 스팬이 포함될 수 있습니다.