MCP Tools Reference: ces.googleapis.com

도구: get_conversation

지정된 대화의 세부정보를 가져옵니다.

다음 코드 샘플은 curl를 사용하여 get_conversation MCP 도구를 호출하는 방법을 보여줍니다.

curl 요청 
curl --location 'https://ces.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "get_conversation",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

AgentService.GetConversation에 대한 요청 메시지입니다.

GetConversationRequest

JSON 표현 
{
  "name": string,
  "source": enum (Source)
}
필드
name

string

필수 항목입니다. 검색할 대화의 리소스 이름입니다.
source
(deprecated)

enum (Source)

선택사항입니다. 대화의 출처를 나타냅니다. 설정하지 않으면 모든 소스가 검색됩니다.

소스

대화의 소스입니다.

열거형
SOURCE_UNSPECIFIED 지정되지 않은 소스입니다.
LIVE 대화가 실제 최종 사용자로부터 시작됩니다.
SIMULATOR 대화는 시뮬레이터에서 가져옵니다.
EVAL 대화는 평가에서 가져옵니다.
AGENT_TOOL 대화가 상담사 도구에서 시작되었습니다. 에이전트 도구는 별도의 세션에서 에이전트를 실행하며, 이 세션은 테스트 및 디버깅 목적으로 유지됩니다.

출력 스키마

대화는 최종 사용자와 CES 앱 간의 상호작용을 나타냅니다.

대화

JSON 표현 
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "turns": [
    {
      object (Turn)
    }
  ],
  "turnCount": integer,
  "channelType": enum (ChannelType),
  "source": enum (Source),
  "inputTypes": [
    enum (InputType)
  ],
  "entryAgent": string,
  "deployment": string,
  "appVersion": string,
  "languageCode": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
필드
name

string

식별자. 대화의 고유 식별자입니다. 형식: projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}
startTime

string (Timestamp format)

출력 전용입니다. 대화가 생성된 시점의 타임스탬프입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
endTime

string (Timestamp format)

출력 전용입니다. 대화가 완료된 시점의 타임스탬프입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
turns[]

object (Turn)

필수 항목입니다. 대화의 차례입니다.
turnCount

integer

출력 전용입니다. 대화의 차례 수입니다.
channelType
(deprecated)

enum (ChannelType)

DEPRECATED. 대신 input_types를 사용하세요.
source

enum (Source)

출력 전용입니다. 대화의 출처를 나타냅니다.
inputTypes[]

enum (InputType)

출력 전용입니다. 대화의 입력 유형입니다.
entryAgent

string

출력 전용입니다. 대화를 처음 처리하는 상담사입니다. 지정하지 않으면 루트 에이전트가 대화를 처리합니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

출력 전용입니다. 대화를 처리하는 데 사용되는 앱의 배포입니다. 형식: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
appVersion

string

출력 전용입니다. 대화를 처리하는 데 사용되는 앱 버전입니다. 형식: projects/{project}/locations/{location}/apps/{app}/versions/{version}
languageCode

string

출력 전용입니다. 대화의 언어 코드입니다.
messages[]
(deprecated)

object (Message)

지원 중단되었습니다. 대신 차례를 사용하세요.

타임스탬프

JSON 표현 
{
  "seconds": string,
  "nanos": integer
}
필드
seconds

string (int64 format)

유닉스 시간 1970-01-01T00:00:00Z 이후 경과된 UTC 시간을 초 단위로 나타냅니다. -62135596800~253402300799(양 끝값 포함) 사이여야 합니다(0001-01-01T00:00:00Z~9999-12-31T23:59:59Z에 해당).
nanos

integer

나노초 단위의 음수가 아닌 초수입니다. 이 필드는 기간의 나노초 부분이며 초를 대체하지 않습니다. 음수의 초수 값에는 시간에 반영되는 음수가 아닌 나노초 값이 있어야 합니다. 0~999,999,999(포함) 사이여야 합니다.

Turn

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

object (Message)

선택사항입니다. 처리 중 사용자 입력, 에이전트 응답, 중간 이벤트를 포함한 대화 차례의 메시지 목록입니다.
rootSpan

object (Span)

선택사항입니다. 작업 처리의 루트 스팬입니다.
userIntendedText

string

선택사항입니다. 시뮬레이션된 발신자(Polysynth)의 의도된 정답 텍스트입니다. 단어 오류율 측정항목이 사용 설정된 경우에만 채워집니다.

메시지

JSON 표현 
{
  "role": string,
  "chunks": [
    {
      object (Chunk)
    }
  ],
  "eventTime": string
}
필드
role

string

선택사항입니다. 대화 내 역할(예: 사용자, 에이전트)입니다.
chunks[]

object (Chunk)

선택사항입니다. 메시지 콘텐츠를 일련의 청크로 나타냅니다.
eventTime

string (Timestamp format)

선택사항입니다. 메일이 전송되거나 수신된 시점의 타임스탬프입니다. 메시지가 example의 일부인 경우 사용해서는 안 됩니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

Chunk

JSON 표현 
{

  // Union field data can be only one of the following:
  "text": string,
  "transcript": string,
  "blob": {
    object (Blob)
  },
  "payload": {
    object
  },
  "image": {
    object (Image)
  },
  "toolCall": {
    object (ToolCall)
  },
  "toolResponse": {
    object (ToolResponse)
  },
  "agentTransfer": {
    object (AgentTransfer)
  },
  "updatedVariables": {
    object
  },
  "defaultVariables": {
    object
  }
  // End of list of possible types for union field data.
}
필드
통합 필드 data. 청크 데이터입니다. data은 다음 중 하나여야 합니다.
text

string

선택사항입니다. 텍스트 데이터.
transcript

string

선택사항입니다. 오디오와 연결된 스크립트입니다.
blob

object (Blob)

선택사항입니다. Blob 데이터
payload

object (Struct format)

선택사항입니다. 커스텀 페이로드 데이터입니다.
image

object (Image)

선택사항입니다. 이미지 데이터입니다.
toolCall

object (ToolCall)

선택사항입니다. 도구 실행 요청입니다.
toolResponse

object (ToolResponse)

선택사항입니다. 도구 실행 응답입니다.
agentTransfer

object (AgentTransfer)

선택사항입니다. 상담사 트랜스퍼 이벤트
updatedVariables

object (Struct format)

대화에서 업데이트된 변수를 나타내는 구조체로, 변수 이름으로 키가 지정됩니다.
defaultVariables

object (Struct format)

구조체는 대화 시작 시 변수 이름으로 키가 지정된 기본 변수를 나타냅니다.

blob

JSON 표현 
{
  "mimeType": string,
  "data": string
}
필드
mimeType

string

필수 항목입니다. 소스 데이터의 IANA 표준 MIME 유형입니다.
data

string (bytes format)

필수 항목입니다. blob의 원시 바이트입니다.

base64 인코딩 문자열입니다.

구조체

JSON 표현 
{
  "fields": {
    string: value,
    ...
  }
}
필드
fields

map (key: string, value: value (Value format))

동적으로 입력된 값의 정렬되지 않은 맵입니다.

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

FieldsEntry

JSON 표현 
{
  "key": string,
  "value": value
}
필드
key

string
value

value (Value format)

값

JSON 표현 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
필드
통합 필드 kind. 값의 종류입니다. kind은 다음 중 하나여야 합니다.
nullValue

null

JSON null을 나타냅니다.
numberValue

number

JSON 숫자를 나타냅니다. JSON에서 지원되지 않으므로 NaN, Infinity 또는 -Infinity가 아니어야 합니다. 또한 JSON 형식은 일반적으로 숫자 유형에서 큰 Int64 값을 지원하지 않으므로 이를 표현할 수 없습니다.
stringValue

string

JSON 문자열을 나타냅니다.
boolValue

boolean

JSON 불리언(JSON의 true 또는 false 리터럴)을 나타냅니다.
structValue

object (Struct format)

JSON 객체를 나타냅니다.
listValue

array (ListValue format)

JSON 배열을 나타냅니다.

ListValue

JSON 표현 
{
  "values": [
    value
  ]
}
필드
values[]

value (Value format)

동적으로 입력된 값의 반복 필드입니다.

이미지

JSON 표현 
{
  "mimeType": string,
  "data": string,
  "altText": string
}
필드
mimeType

string

필수 항목입니다. 소스 데이터의 IANA 표준 MIME 유형입니다. 지원되는 이미지 유형은 다음과 같습니다. * image/png * image/jpeg * image/webp
data

string (bytes format)

필수 항목입니다. 이미지의 원시 바이트입니다.

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

string

선택사항입니다. 이미지의 대체 텍스트입니다.

ToolCall

JSON 표현 
{
  "id": string,
  "displayName": string,
  "args": {
    object
  },
  "parentToolCallId": string,
  "agentName": string,
  "targetApp": string,

  // Union field tool_identifier can be only one of the following:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of list of possible types for union field tool_identifier.
}
필드
id

string

선택사항입니다. 도구 호출의 고유 식별자입니다. 채워진 경우 클라이언트는 ToolResponse에서 일치하는 ID를 가진 실행 결과를 반환해야 합니다.
displayName

string

출력 전용입니다. 도구의 표시 이름입니다.
args

object (Struct format)

선택사항입니다. JSON 객체 형식의 도구 입력 파라미터와 값입니다.
parentToolCallId

string

출력 전용입니다. 상위 호출을 대신하여 작업하는 하위 에이전트가 실행한 경우 이 호출을 발생시킨 도구 호출의 ID입니다. 최상위 호출의 경우 비어 있습니다. 클라이언트가 모든 단계를 동위 요소로 렌더링하는 대신 하위 에이전트의 작업을 시작한 호출 아래에 그룹화할 수 있습니다.
agentName

string

출력 전용입니다. 이 호출을 실행한 에이전트의 인간이 읽을 수 있는 이름입니다(예: '계약 설계자'). 루트 에이전트가 발급한 경우 비어 있습니다.
targetApp

string

출력 전용입니다. 이 호출이 타겟팅하는 앱으로, 어시스턴트가 호출의 리소스 인수에서 파생합니다. 위치 범위 도구의 경우 앱 리소스 이름 PROJECT이고 세션 로컬 도구의 경우 비어 있습니다. 프로젝트 범위 어시스턴트 세션에서만 설정됩니다.
통합 필드 tool_identifier. 실행할 도구의 식별자입니다. 지속 도구 또는 도구 모음의 도구일 수 있습니다. tool_identifier은 다음 중 하나여야 합니다.
tool

string

선택사항입니다. 실행할 도구의 이름입니다. 형식: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

선택사항입니다. 실행할 도구 세트 도구입니다.

ToolsetTool

JSON 표현 
{
  "toolset": string,
  "toolId": string
}
필드
toolset

string

필수 항목입니다. 이 도구가 파생된 도구 모음의 리소스 이름입니다. 형식: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolId

string

선택사항입니다. 스키마를 검색할 도구를 필터링하는 도구 ID입니다.

ToolResponse

JSON 표현 
{
  "id": string,
  "displayName": string,
  "response": {
    object
  },
  "parentToolCallId": string,
  "agentName": string,
  "targetApp": string,

  // Union field tool_identifier can be only one of the following:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of list of possible types for union field tool_identifier.
}
필드
id

string

선택사항입니다. 응답이 적용되는 tool call의 일치 ID입니다.
displayName

string

출력 전용입니다. 도구의 표시 이름입니다.
response

object (Struct format)

필수 항목입니다. JSON 객체 형식의 도구 실행 결과입니다. 'output' 키를 사용하여 도구 응답을 지정하고 'error' 키를 사용하여 오류 세부정보(있는 경우)를 지정합니다. 'output' 및 'error' 키가 지정되지 않으면 전체 'response'가 도구 실행 결과로 처리됩니다.
parentToolCallId

string

출력 전용입니다. 상위 호출을 대신하여 작업하는 하위 에이전트가 실행한 경우 이 호출을 발생시킨 도구 호출의 ID입니다. 최상위 호출의 경우 비어 있습니다. 클라이언트가 모든 단계를 동위 요소로 렌더링하는 대신 하위 에이전트의 작업을 시작한 호출 아래에 그룹화할 수 있습니다.
agentName

string

출력 전용입니다. 이 호출을 실행한 에이전트의 인간이 읽을 수 있는 이름입니다(예: '계약 설계자'). 루트 에이전트가 발급한 경우 비어 있습니다.
targetApp

string

출력 전용입니다. 실행된 도구가 타겟팅한 앱입니다. ToolCall.target_app를 미러링합니다.
통합 필드 tool_identifier. 실행된 도구의 식별자입니다. 지속 도구 또는 도구 모음의 도구일 수 있습니다. tool_identifier은 다음 중 하나여야 합니다.
tool

string

선택사항입니다. 실행할 도구의 이름입니다. 형식: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

선택사항입니다. 실행된 도구 세트 도구입니다.

AgentTransfer

JSON 표현 
{
  "targetAgent": string,
  "displayName": string
}
필드
targetAgent

string

필수 항목입니다. 대화가 전달되는 상담사입니다. 이 시점부터 상담사가 대화를 처리합니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

출력 전용입니다. 에이전트의 표시 이름입니다.

스팬

JSON 표현 
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "duration": string,
  "attributes": {
    object
  },
  "childSpans": [
    {
      object (Span)
    }
  ]
}
필드
name

string

출력 전용입니다. 스팬의 이름입니다.
startTime

string (Timestamp format)

출력 전용입니다. 스팬의 시작 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
endTime

string (Timestamp format)

출력 전용입니다. 스팬의 종료 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
duration

string (Duration format)

출력 전용입니다. 스팬의 지속 시간입니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
attributes

object (Struct format)

출력 전용입니다. 스팬과 연결된 키-값 속성입니다.
childSpans[]

object (Span)

출력 전용입니다. 이 스팬 아래에 중첩된 하위 스팬입니다.

소요 시간

JSON 표현 
{
  "seconds": string,
  "nanos": integer
}
필드
seconds

string (int64 format)

기간의 부호 있는 초입니다. -315,576,000,000~+315,576,000,000(포함) 사이여야 합니다. 참고: 이 경계는 60초/분 * 60분/시간 * 24시간/일 * 365.25일/년 * 10,000년으로 계산됩니다.
nanos

integer

기간의 나노초 단위로 부호가 있는 초수입니다. 1초 미만의 기간은 0 seconds 필드와 양수 또는 음수 nanos 필드로 표시됩니다. 1초 이상의 기간의 경우 nanos 필드의 0이 아닌 값은 seconds 필드와 동일한 부호여야 합니다. -999,999,999~+999,999,999(끝값 포함) 사이여야 합니다.

NullValue

JSON null을 나타냅니다.

NullValue는 센티널로, 값이 하나만 있는 enum을 사용하여 Value 유형 공용체의 null 값을 나타냅니다.

0 이외의 값이 있는 NullValue 유형의 필드는 잘못된 것으로 간주됩니다. 대부분의 ProtoJSON 직렬 변환기는 정수 값과 관계없이 JSON null로 설정된 null_value가 있는 Value를 내보내므로 0 값으로 왕복합니다.

열거형
NULL_VALUE null 값입니다.

ChannelType

대화의 채널 유형입니다.

열거형
CHANNEL_TYPE_UNSPECIFIED 지정되지 않은 채널 유형입니다.
TEXT 대화에는 최종 사용자와 에이전트 간의 문자 메시지만 포함됩니다.
AUDIO 대화에는 최종 사용자와 에이전트 간의 음성 메시지가 포함됩니다.
MULTIMODAL 최종 사용자와 에이전트 간의 대화 멀티모달 메시지(예: 이미지)입니다.

소스

대화의 소스입니다.

열거형
SOURCE_UNSPECIFIED 지정되지 않은 소스입니다.
LIVE 대화가 실제 최종 사용자로부터 시작됩니다.
SIMULATOR 대화는 시뮬레이터에서 가져옵니다.
EVAL 대화는 평가에서 가져옵니다.
AGENT_TOOL 대화가 상담사 도구에서 시작되었습니다. 에이전트 도구는 별도의 세션에서 에이전트를 실행하며, 이 세션은 테스트 및 디버깅 목적으로 유지됩니다.

InputType

입력 메시지의 유형입니다.

열거형
INPUT_TYPE_UNSPECIFIED 지정되지 않은 입력 유형입니다.
INPUT_TYPE_TEXT 텍스트 입력.
INPUT_TYPE_EVENT 이벤트 입력입니다.
INPUT_TYPE_AUDIO 오디오 입력
INPUT_TYPE_IMAGE 이미지 입력입니다.
INPUT_TYPE_BLOB Blob 입력입니다.
INPUT_TYPE_TOOL_RESPONSE 클라이언트 함수 도구 응답 입력입니다.
INPUT_TYPE_VARIABLES 변수 입력

도구 주석

도구 주석은 특정 도구의 기본 위험을 설명하기 위해 MCP 클라이언트에 전송됩니다. 대부분의 클라이언트는 이러한 힌트를 신뢰할 수 없는 것으로 취급하지만, 사용자에게 확인 메시지를 보낼 시점을 결정하는 데 사용할 수 있습니다.

제목 문자열과 함께 다음 불리언 힌트가 정의됩니다.

  • readOnlyHint: true인 경우 도구가 환경을 수정하지 않습니다. 기본값: false.
  • destructiveHint: true인 경우 도구에서 파괴적인 작업을 수행할 수 있습니다. false이면 도구는 추가 작업만 수행할 수 있습니다. 기본값은 true입니다.
  • idempotentHint: true인 경우 동일한 인수로 도구를 반복적으로 호출해도 환경에 추가적인 영향을 미치지 않습니다. 기본값: false.
  • openWorldHint: true인 경우 도구는 외부 항목의 '오픈 월드'와 상호작용할 수 있습니다. false이면 도구는 내부 항목과만 상호작용할 수 있습니다. 예를 들어 웹 검색 도구는 오픈 월드이지만 메모리 도구는 오픈 월드가 아닙니다.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌