MCP Tools Reference: ces.googleapis.com

Tool: list_conversations

Lists conversations.

The following sample demonstrate how to use curl to invoke the list_conversations MCP tool.

Curl Request 
                  
curl --location 'https://ces.[REGION].rep.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_conversations",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for AgentService.ListConversations.

ListConversationsRequest

JSON representation 
{
  "parent": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string,
  "source": enum (Source),
  "sources": [
    enum (Source)
  ]
}
Fields
parent

string

Required. The resource name of the app to list conversations from.
pageSize

integer

Optional. Requested page size. Server may return fewer items than requested. If unspecified, server will pick an appropriate default.
pageToken

string

Optional. The next_page_token value returned from a previous list AgentService.ListConversations call.
filter

string

Optional. Filter to be applied when listing the conversations. See https://google.aip.dev/160 for more details.
source

enum (Source)

Optional. Indicate the source of the conversation. If not set, Source.Live will be applied by default. Will be deprecated in favor of sources field.
sources[]

enum (Source)

Optional. Indicate the sources of the conversations. If not set, all available sources will be applied by default.

Output Schema

Response message for AgentService.ListConversations.

ListConversationsResponse

JSON representation 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Fields
conversations[]

object (Conversation)

The list of conversations.
nextPageToken

string

A token that can be sent as ListConversationsRequest.page_token to retrieve the next page. Absence of this field indicates there are no subsequent pages.

Conversation

JSON representation 
{
  "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)
    }
  ]
}
Fields
name

string

Identifier. The unique identifier of the conversation. Format: projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}
startTime

string (Timestamp format)

Output only. Timestamp when the conversation was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Output only. Timestamp when the conversation was completed.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
turns[]

object (Turn)

Required. The turns in the conversation.
turnCount

integer

Output only. The number of turns in the conversation.
channelType
(deprecated)

enum (ChannelType)

DEPRECATED. Please use input_types instead.
source

enum (Source)

Output only. Indicate the source of the conversation.
inputTypes[]

enum (InputType)

Output only. The input types of the conversation.
entryAgent

string

Output only. The agent that initially handles the conversation. If not specified, the conversation is handled by the root agent. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Output only. The deployment of the app used for processing the conversation. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
appVersion

string

Output only. The version of the app used for processing the conversation. Format: projects/{project}/locations/{location}/apps/{app}/versions/{version}
languageCode

string

Output only. The language code of the conversation.
messages[]
(deprecated)

object (Message)

Deprecated. Use turns instead.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

Turn

JSON representation 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Fields
messages[]

object (Message)

Optional. List of messages in the conversation turn, including user input, agent responses and intermediate events during the processing.
rootSpan

object (Span)

Optional. The root span of the action processing.

Message

JSON representation 
{
  "role": string,
  "chunks": [
    {
      object (Chunk)
    }
  ],
  "eventTime": string
}
Fields
role

string

Optional. The role within the conversation, e.g., user, agent.
chunks[]

object (Chunk)

Optional. Content of the message as a series of chunks.
eventTime

string (Timestamp format)

Optional. Timestamp when the message was sent or received. Should not be used if the message is part of an example.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

Chunk

JSON representation 
{

  // 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.
}
Fields
Union field data. Chunk data. data can be only one of the following:
text

string

Optional. Text data.
transcript

string

Optional. Transcript associated with the audio.
blob

object (Blob)

Optional. Blob data.
payload

object (Struct format)

Optional. Custom payload data.
image

object (Image)

Optional. Image data.
toolCall

object (ToolCall)

Optional. Tool execution request.
toolResponse

object (ToolResponse)

Optional. Tool execution response.
agentTransfer

object (AgentTransfer)

Optional. Agent transfer event.
updatedVariables

object (Struct format)

A struct represents variables that were updated in the conversation, keyed by variable names.
defaultVariables

object (Struct format)

A struct represents default variables at the start of the conversation, keyed by variable names.

Blob

JSON representation 
{
  "mimeType": string,
  "data": string
}
Fields
mimeType

string

Required. The IANA standard MIME type of the source data.
data

string (bytes format)

Required. Raw bytes of the blob.

A base64-encoded string.

Struct

JSON representation 
{
  "fields": {
    string: value,
    ...
  }
}
Fields
fields

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

Unordered map of dynamically typed values.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

JSON representation 
{
  "key": string,
  "value": value
}
Fields
key

string
value

value (Value format)

Value

JSON representation 
{

  // 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.
}
Fields
Union field kind. The kind of value. kind can be only one of the following:
nullValue

null

Represents a null value.
numberValue

number

Represents a double value.
stringValue

string

Represents a string value.
boolValue

boolean

Represents a boolean value.
structValue

object (Struct format)

Represents a structured value.
listValue

array (ListValue format)

Represents a repeated Value.

ListValue

JSON representation 
{
  "values": [
    value
  ]
}
Fields
values[]

value (Value format)

Repeated field of dynamically typed values.

Image

JSON representation 
{
  "mimeType": string,
  "data": string
}
Fields
mimeType

string

Required. The IANA standard MIME type of the source data. Supported image types includes: * image/png * image/jpeg * image/webp
data

string (bytes format)

Required. Raw bytes of the image.

A base64-encoded string.

ToolCall

JSON representation 
{
  "id": string,
  "displayName": string,
  "args": {
    object
  },

  // 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.
}
Fields
id

string

Optional. The unique identifier of the tool call. If populated, the client should return the execution result with the matching ID in ToolResponse.
displayName

string

Output only. Display name of the tool.
args

object (Struct format)

Optional. The input parameters and values for the tool in JSON object format.
Union field tool_identifier. The identifier of the tool to execute. It could be either a persisted tool or a tool from a toolset. tool_identifier can be only one of the following:
tool

string

Optional. The name of the tool to execute. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Optional. The toolset tool to execute.

ToolsetTool

JSON representation 
{
  "toolset": string,
  "toolId": string
}
Fields
toolset

string

Required. The resource name of the Toolset from which this tool is derived. Format: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolId

string

Optional. The tool ID to filter the tools to retrieve the schema for.

ToolResponse

JSON representation 
{
  "id": string,
  "displayName": string,
  "response": {
    object
  },

  // 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.
}
Fields
id

string

Optional. The matching ID of the tool call the response is for.
displayName

string

Output only. Display name of the tool.
response

object (Struct format)

Required. The tool execution result in JSON object format. Use "output" key to specify tool response and "error" key to specify error details (if any). If "output" and "error" keys are not specified, then whole "response" is treated as tool execution result.
Union field tool_identifier. The identifier of the tool that got executed. It could be either a persisted tool or a tool from a toolset. tool_identifier can be only one of the following:
tool

string

Optional. The name of the tool to execute. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Optional. The toolset tool that got executed.

AgentTransfer

JSON representation 
{
  "targetAgent": string,
  "displayName": string
}
Fields
targetAgent

string

Required. The agent to which the conversation is being transferred. The agent will handle the conversation from this point forward. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Output only. Display name of the agent.

Span

JSON representation 
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "duration": string,
  "attributes": {
    object
  },
  "childSpans": [
    {
      object (Span)
    }
  ]
}
Fields
name

string

Output only. The name of the span.
startTime

string (Timestamp format)

Output only. The start time of the span.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Output only. The end time of the span.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

Output only. The duration of the span.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
attributes

object (Struct format)

Output only. Key-value attributes associated with the span.
childSpans[]

object (Span)

Output only. The child spans that are nested under this span.

Duration

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
nanos

integer

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

Tool Annotations

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