MCP Tools Reference: ces.googleapis.com

Herramienta: get_conversation

Obtiene los detalles de la conversación especificada.

En la siguiente muestra de código, se indica cómo usar curl para llamar a la herramienta de MCP get_conversation.

Solicitud de 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
}'

Esquema de entrada

Mensaje de solicitud para AgentService.GetConversation.

GetConversationRequest

Representación JSON
{
  "name": string,
  "source": enum (Source)
}
Campos
name

string

Obligatorio. Es el nombre del recurso de la conversación que se recuperará.

source
(deprecated)

enum (Source)

Es opcional. Indica la fuente de la conversación. Si no se establece, se buscará en todas las fuentes.

Fuente

Es la fuente de la conversación.

Enums
SOURCE_UNSPECIFIED Origen sin especificar.
LIVE La conversación es del usuario final en vivo.
SIMULATOR La conversación es del simulador.
EVAL La conversación es de la evaluación.
AGENT_TOOL La conversación proviene de una herramienta de agente. La herramienta de agente ejecuta el agente en una sesión independiente, que se conserva para realizar pruebas y depuraciones.

Esquema de salida

Una conversación representa una interacción entre un usuario final y la app de CES.

Conversación

Representación 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)
    }
  ]
}
Campos
name

string

Es el identificador. Es el identificador único de la conversación. Formato: projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}

startTime

string (Timestamp format)

Solo salida. Es la marca de tiempo de cuando se creó la conversación.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

endTime

string (Timestamp format)

Solo salida. Es la marca de tiempo del momento en que se completó la conversación.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

turns[]

object (Turn)

Obligatorio. Los turnos de la conversación.

turnCount

integer

Solo salida. Es la cantidad de turnos en la conversación.

channelType
(deprecated)

enum (ChannelType)

OBSOLETO. En su lugar, usa input_types.

source

enum (Source)

Solo salida. Indica la fuente de la conversación.

inputTypes[]

enum (InputType)

Solo salida. Son los tipos de entrada de la conversación.

entryAgent

string

Solo salida. Es el agente que maneja la conversación inicialmente. Si no se especifica, el agente raíz controla la conversación. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}

deployment

string

Solo salida. Es la implementación de la app que se usa para procesar la conversación. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}

appVersion

string

Solo salida. Es la versión de la app que se usa para procesar la conversación. Formato: projects/{project}/locations/{location}/apps/{app}/versions/{version}

languageCode

string

Solo salida. Es el código de idioma de la conversación.

messages[]
(deprecated)

object (Message)

Obsoleto. En su lugar, usa turnos.

Marca de tiempo

Representación JSON
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Representa los segundos del horario UTC desde el tiempo Unix 1970-01-01T00:00:00Z. Debe estar entre -62135596800 y 253402300799 inclusive (lo que corresponde a 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z).

nanos

integer

Fracciones no negativas de un segundo a una resolución de nanosegundos. Este campo es la parte de nanosegundos de la duración, no una alternativa a los segundos. Los valores de segundos negativos con fracciones deben tener valores nanos no negativos que se cuentan hacia adelante en el tiempo. Deben ser valores de 0 a 999,999,999 inclusive.

Turno

Representación JSON
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  },
  "userIntendedText": string
}
Campos
messages[]

object (Message)

Es opcional. Es la lista de mensajes en el turno de conversación, incluidas las entradas del usuario, las respuestas del agente y los eventos intermedios durante el procesamiento.

rootSpan

object (Span)

Es opcional. Es el intervalo raíz del procesamiento de la acción.

userIntendedText

string

Es opcional. Es el texto de verdad fundamental previsto del emisor simulado (Polysynth). Solo se propaga cuando se habilitan las métricas de tasa de errores de palabras.

Mensaje

Representación JSON
{
  "role": string,
  "chunks": [
    {
      object (Chunk)
    }
  ],
  "eventTime": string
}
Campos
role

string

Es opcional. Es el rol dentro de la conversación, p.ej., usuario, agente.

chunks[]

object (Chunk)

Es opcional. Es el contenido del mensaje como una serie de fragmentos.

eventTime

string (Timestamp format)

Es opcional. Es la marca de tiempo del momento en que se envió o recibió el mensaje. No se debe usar si el mensaje forma parte de un example.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

Bandinsecto

Representación 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.
}
Campos
Campo de unión data. Datos de fragmentos data puede ser solo uno de los parámetros siguientes:
text

string

Es opcional. Datos de texto.

transcript

string

Es opcional. Es la transcripción asociada al audio.

blob

object (Blob)

Es opcional. Datos de BLOB.

payload

object (Struct format)

Es opcional. Datos de carga útil personalizados.

image

object (Image)

Es opcional. Son los datos de la imagen.

toolCall

object (ToolCall)

Es opcional. Es la solicitud de ejecución de la herramienta.

toolResponse

object (ToolResponse)

Es opcional. Es la respuesta de la ejecución de la herramienta.

agentTransfer

object (AgentTransfer)

Es opcional. Evento de transferencia de agente.

updatedVariables

object (Struct format)

Un struct representa las variables que se actualizaron en la conversación, con clave por nombres de variables.

defaultVariables

object (Struct format)

Un struct representa las variables predeterminadas al inicio de la conversación, con clave por nombres de variables.

BLOB

Representación JSON
{
  "mimeType": string,
  "data": string
}
Campos
mimeType

string

Obligatorio. Es el tipo de MIME estándar de IANA de los datos de origen.

data

string (bytes format)

Obligatorio. Son los bytes sin procesar del BLOB.

Es una cadena codificada en Base64.

Struct

Representación JSON
{
  "fields": {
    string: value,
    ...
  }
}
Campos
fields

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

Es un mapa sin ordenar de valores con tipo dinámico.

Un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

Representación JSON
{
  "key": string,
  "value": value
}
Campos
key

string

value

value (Value format)

Valor

Representación 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.
}
Campos
Campo de unión kind. Es el tipo de valor. kind puede ser solo uno de los parámetros siguientes:
nullValue

null

Representa un null JSON.

numberValue

number

Representa un número JSON. No debe ser NaN, Infinity ni -Infinity, ya que no se admiten en JSON. Tampoco puede representar valores Int64 grandes, ya que el formato JSON, por lo general, no los admite en su tipo de número.

stringValue

string

Representa una cadena JSON.

boolValue

boolean

Representa un booleano JSON (literal true o false en JSON).

structValue

object (Struct format)

Representa un objeto JSON.

listValue

array (ListValue format)

Representa un array JSON.

ListValue

Representación JSON
{
  "values": [
    value
  ]
}
Campos
values[]

value (Value format)

Es un campo repetido de valores con tipo dinámico.

Imagen

Representación JSON
{
  "mimeType": string,
  "data": string,
  "altText": string
}
Campos
mimeType

string

Obligatorio. Es el tipo de MIME estándar de IANA de los datos de origen. Los tipos de imágenes compatibles incluyen los siguientes: * image/png * image/jpeg * image/webp

data

string (bytes format)

Obligatorio. Son los bytes sin procesar de la imagen.

Es una cadena codificada en Base64.

altText

string

Es opcional. Es el texto alternativo de la imagen.

ToolCall

Representación 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.
}
Campos
id

string

Es opcional. Es el identificador único de la llamada a la herramienta. Si se completa, el cliente debe devolver el resultado de la ejecución con el ID para coincidencias en ToolResponse.

displayName

string

Solo salida. Es el nombre visible de la herramienta.

args

object (Struct format)

Es opcional. Son los parámetros y valores de entrada de la herramienta en formato de objeto JSON.

parentToolCallId

string

Solo salida. Es el ID de la llamada a la herramienta que causó esta, cuando la emitió un agente secundario que trabaja en nombre de una llamada superior. Está vacío para las llamadas de nivel superior. Permite que un cliente agrupe el trabajo de un agente secundario en la llamada que lo inició, en lugar de renderizar cada paso como un elemento hermano.

agentName

string

Solo salida. Nombre legible por humanos del agente que emitió esta llamada, p.ej., "Arquitecto de contratos". Está vacío cuando lo emite el agente raíz.

targetApp

string

Solo salida. La app a la que se dirige esta llamada, derivada por el asistente a partir de los argumentos de recursos de la llamada: un nombre de recurso de app, PROJECT para las herramientas con alcance de ubicación o vacío para las herramientas locales de la sesión. Se establece solo en las sesiones de asistente con alcance de proyecto.

Campo de unión tool_identifier. Es el identificador de la herramienta que se ejecutará. Puede ser una herramienta persistente o una herramienta de un conjunto de herramientas. tool_identifier puede ser solo uno de los parámetros siguientes:
tool

string

Es opcional. Es el nombre de la herramienta que se ejecutará. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}

toolsetTool

object (ToolsetTool)

Es opcional. Es la herramienta del conjunto de herramientas que se ejecutará.

ToolsetTool

Representación JSON
{
  "toolset": string,
  "toolId": string
}
Campos
toolset

string

Obligatorio. Es el nombre del recurso del conjunto de herramientas del que se deriva esta herramienta. Formato: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}

toolId

string

Es opcional. Es el ID de la herramienta para filtrar las herramientas de las que se recuperará el esquema.

ToolResponse

Representación 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.
}
Campos
id

string

Es opcional. Es el ID para coincidencias del tool call al que corresponde la respuesta.

displayName

string

Solo salida. Es el nombre visible de la herramienta.

response

object (Struct format)

Obligatorio. Es el resultado de la ejecución de la herramienta en formato de objeto JSON. Usa la clave "output" para especificar la respuesta de la herramienta y la clave "error" para especificar los detalles del error (si los hay). Si no se especifican las claves "output" y "error", toda la "response" se trata como el resultado de la ejecución de la herramienta.

parentToolCallId

string

Solo salida. Es el ID de la llamada a la herramienta que causó esta, cuando la emitió un agente secundario que trabaja en nombre de una llamada superior. Está vacío para las llamadas de nivel superior. Permite que un cliente agrupe el trabajo de un agente secundario en la llamada que lo inició, en lugar de renderizar cada paso como un elemento hermano.

agentName

string

Solo salida. Nombre legible por humanos del agente que emitió esta llamada, p.ej., "Arquitecto de contratos". Está vacío cuando lo emite el agente raíz.

targetApp

string

Solo salida. Es la app a la que se orientó la herramienta ejecutada; refleja ToolCall.target_app.

Campo de unión tool_identifier. Es el identificador de la herramienta que se ejecutó. Puede ser una herramienta persistente o una herramienta de un conjunto de herramientas. tool_identifier puede ser solo uno de los parámetros siguientes:
tool

string

Es opcional. Es el nombre de la herramienta que se ejecutará. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}

toolsetTool

object (ToolsetTool)

Es opcional. Es la herramienta del conjunto de herramientas que se ejecutó.

AgentTransfer

Representación JSON
{
  "targetAgent": string,
  "displayName": string
}
Campos
targetAgent

string

Obligatorio. Es el agente al que se transfiere la conversación. El agente se encargará de la conversación a partir de este punto. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}

displayName

string

Solo salida. Es el nombre visible del agente.

Intervalo

Representación JSON
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "duration": string,
  "attributes": {
    object
  },
  "childSpans": [
    {
      object (Span)
    }
  ]
}
Campos
name

string

Solo salida. Es el nombre del intervalo.

startTime

string (Timestamp format)

Solo salida. Es la hora de inicio del intervalo.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

endTime

string (Timestamp format)

Solo salida. Es la hora de finalización del intervalo.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

duration

string (Duration format)

Solo salida. La duración del intervalo.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

attributes

object (Struct format)

Solo salida. Son los atributos de par clave-valor asociados con el intervalo.

childSpans[]

object (Span)

Solo salida. Son los intervalos secundarios que están anidados en este intervalo.

Duración

Representación JSON
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Segundos con signo del intervalo de tiempo. Debe ser un valor entre -315,576,000,000 y +315,576,000,000 inclusive. Nota: Estos límites se calculan de la siguiente manera: 60 s/min * 60 min/h * 24 h/día * 365.25 días/año * 10,000 años

nanos

integer

Fracciones con signo de un segundo con una resolución de nanosegundos del intervalo de tiempo. Las duraciones de menos de un segundo se representan con un campo seconds de 0 y un campo nanos positivo o negativo. En el caso de las duraciones de un segundo o más, un valor distinto de cero para el campo nanos debe tener el mismo signo que el campo seconds. Deben ser valores de -999,999,999 a +999,999,999 inclusive.

NullValue

Representa un null JSON.

NullValue es un centinela que usa una enumeración con un solo valor para representar el valor nulo de la unión de tipos Value.

Un campo de tipo NullValue con cualquier valor que no sea 0 se considera no válido. La mayoría de los serializadores de ProtoJSON emitirán un Value con un null_value establecido como un null de JSON, independientemente del valor entero, por lo que se realizará un recorrido de ida y vuelta a un valor 0.

Enums
NULL_VALUE Valor nulo.

ChannelType

Es el tipo de canal de la conversación.

Enums
CHANNEL_TYPE_UNSPECIFIED Es un tipo de canal no especificado.
TEXT La conversación solo contiene mensajes de texto entre el usuario final y el agente.
AUDIO La conversación contiene mensajes de audio entre el usuario final y el agente.
MULTIMODAL Son los mensajes multimodales de la conversación (p.ej., imágenes) entre el usuario final y el agente.

Fuente

Es la fuente de la conversación.

Enums
SOURCE_UNSPECIFIED Origen sin especificar.
LIVE La conversación es del usuario final en vivo.
SIMULATOR La conversación es del simulador.
EVAL La conversación es de la evaluación.
AGENT_TOOL La conversación proviene de una herramienta de agente. La herramienta de agente ejecuta el agente en una sesión independiente, que se conserva para realizar pruebas y depuraciones.

InputType

Es el tipo de mensaje de entrada.

Enums
INPUT_TYPE_UNSPECIFIED Es un tipo de entrada sin especificar.
INPUT_TYPE_TEXT Entrada de texto.
INPUT_TYPE_EVENT Entrada del evento.
INPUT_TYPE_AUDIO Entrada de audio.
INPUT_TYPE_IMAGE Entrada de imagen.
INPUT_TYPE_BLOB Entrada de BLOB.
INPUT_TYPE_TOOL_RESPONSE Entrada de respuesta de la herramienta de función del cliente.
INPUT_TYPE_VARIABLES Entrada de variables.

Anotaciones de herramientas

Las anotaciones de herramientas se envían a los clientes de MCP para describir el riesgo básico de una herramienta determinada. La mayoría de los clientes tratan estas sugerencias como no confiables, pero se pueden usar para decidir cuándo se puede enviar un mensaje de confirmación a un usuario.

Junto con la cadena de título, las siguientes sugerencias booleanas se definen de la siguiente manera:

  • readOnlyHint: Si es verdadero, la herramienta no modifica su entorno. Valor predeterminado: false.
  • destructiveHint: Si es verdadero, la herramienta puede realizar acciones destructivas. Si es falso, la herramienta solo puede realizar acciones aditivas. Valor predeterminado: true.
  • idempotentHint: Si es verdadero, llamar a la herramienta de forma repetida con los mismos argumentos no tendrá ningún efecto adicional en su entorno. Valor predeterminado: false.
  • openWorldHint: Si es verdadero, la herramienta puede interactuar con un "mundo abierto" de entidades externas. Si es falso, la herramienta solo puede interactuar con entidades internas. Por ejemplo, una herramienta de búsqueda web sería de mundo abierto, mientras que una herramienta de memoria no lo sería.

Sugerencia de destructivo: ❌ | Sugerencia de idempotente: ✅ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌