MCP Tools Reference: ces.googleapis.com

Ferramenta: get_conversation

Recebe detalhes da conversa especificada.

O exemplo de código abaixo mostra como usar curl para chamar a ferramenta MCP get_conversation.

Solicitação 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

Mensagem de solicitação para AgentService.GetConversation.

GetConversationRequest

Representação JSON 
{
  "name": string,
  "source": enum (Source)
}
Campos
name

string

Obrigatório. O nome do recurso da conversa a ser recuperada.
source
(deprecated)

enum (Source)

Opcional. Indique a origem da conversa. Se não for definida, todas as origens serão pesquisadas.

Origem

A origem da conversa.

Tipos enumerados
SOURCE_UNSPECIFIED Origem não especificada.
LIVE A conversa é do usuário final ao vivo.
SIMULATOR A conversa é do simulador.
EVAL A conversa é da avaliação.
AGENT_TOOL A conversa é de uma ferramenta de agente. A ferramenta de agente executa o agente em uma sessão separada, que é mantida para fins de teste e depuração.

Esquema de saída

Uma conversa representa uma interação entre um usuário final e o app CES.

Conversa

Representação 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

Identificador. O identificador exclusivo da conversa. Formato: projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}
startTime

string (Timestamp format)

Apenas saída. Carimbo de data/hora de quando a conversa foi criada.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Apenas saída. Carimbo de data/hora de quando a conversa foi concluída.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
turns[]

object (Turn)

Obrigatório. As interações na conversa.
turnCount

integer

Apenas saída. O número de turnos na conversa.
channelType
(deprecated)

enum (ChannelType)

OBSOLETO. Use input_types.
source

enum (Source)

Apenas saída. Indique a origem da conversa.
inputTypes[]

enum (InputType)

Apenas saída. Os tipos de entrada da conversa.
entryAgent

string

Apenas saída. O agente que lida inicialmente com a conversa. Se não for especificado, a conversa será processada pelo agente raiz. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Apenas saída. A implantação do app usado para processar a conversa. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
appVersion

string

Apenas saída. A versão do app usada para processar a conversa. Formato: projects/{project}/locations/{location}/apps/{app}/versions/{version}
languageCode

string

Apenas saída. O código de idioma da conversa.
messages[]
(deprecated)

object (Message)

Obsoleto. Use as curvas.

Carimbo de data/hora

Representação JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Representa os segundos do horário UTC desde a época Unix 1970-01-01T00:00:00Z. Precisa estar entre -62135596800 e 253402300799, inclusive (o que corresponde a 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z).
nanos

integer

Frações não negativas de um segundo com resolução de nanossegundos. Esse campo é a parte de nanossegundos da duração, não uma alternativa aos segundos. Os valores de segundos negativos com frações ainda precisam ter valores em nanossegundos não negativos que representam períodos posteriores. O valor precisa ser de 0 a 999.999.999.

Turn

Representação JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  },
  "userIntendedText": string
}
Campos
messages[]

object (Message)

Opcional. Lista de mensagens na rodada de conversa, incluindo entrada do usuário, respostas do agente e eventos intermediários durante o processamento.
rootSpan

object (Span)

Opcional. O período raiz do processamento da ação.
userIntendedText

string

Opcional. O texto de informações empíricas pretendido do autor da chamada simulado (Polysynth). Preenchido apenas quando as métricas de taxa de erro de palavras estão ativadas.

Mensagem

Representação JSON 
{
  "role": string,
  "chunks": [
    {
      object (Chunk)
    }
  ],
  "eventTime": string
}
Campos
role

string

Opcional. O papel na conversa, por exemplo, usuário, agente.
chunks[]

object (Chunk)

Opcional. Conteúdo da mensagem como uma série de blocos.
eventTime

string (Timestamp format)

Opcional. Carimbo de data/hora de quando a mensagem foi enviada ou recebida. Não deve ser usado se a mensagem fizer parte de um example.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

Pedaço

Representação 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ão data. Dividir dados em blocos. data pode ser apenas de um dos tipos a seguir:
text

string

Opcional. Dados de texto.
transcript

string

Opcional. Transcrição associada ao áudio.
blob

object (Blob)

Opcional. Dados de blob.
payload

object (Struct format)

Opcional. Dados de payload personalizados.
image

object (Image)

Opcional. Dados da imagem.
toolCall

object (ToolCall)

Opcional. Solicitação de execução de ferramenta.
toolResponse

object (ToolResponse)

Opcional. Resposta da execução da ferramenta.
agentTransfer

object (AgentTransfer)

Opcional. Evento de transferência do agente.
updatedVariables

object (Struct format)

Uma estrutura representa as variáveis que foram atualizadas na conversa, identificadas pelos nomes das variáveis.
defaultVariables

object (Struct format)

Uma struct representa variáveis padrão no início da conversa, identificadas por nomes de variáveis.

Blob

Representação JSON 
{
  "mimeType": string,
  "data": string
}
Campos
mimeType

string

Obrigatório. O tipo MIME padrão da IANA dos dados de origem.
data

string (bytes format)

Obrigatório. Bytes brutos do blob.

Uma string codificada em base64.

Struct

Representação JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campos
fields

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

Mapa não ordenado de valores digitados dinamicamente.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

Representação JSON 
{
  "key": string,
  "value": value
}
Campos
key

string
value

value (Value format)

Valor

Representação 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ão kind. O tipo de valor. kind pode ser apenas de um dos tipos a seguir:
nullValue

null

Representa um null JSON.
numberValue

number

Representa um número JSON. Não pode ser NaN, Infinity ou -Infinity, porque eles não são compatíveis com JSON. Isso também não pode representar valores Int64 grandes, já que o formato JSON geralmente não os aceita no tipo de número.
stringValue

string

Representa uma string JSON.
boolValue

boolean

Representa um booleano JSON (literal true ou false em JSON).
structValue

object (Struct format)

Representa um objeto JSON.
listValue

array (ListValue format)

Representa uma matriz JSON.

ListValue

Representação JSON 
{
  "values": [
    value
  ]
}
Campos
values[]

value (Value format)

Campo repetido de valores digitados dinamicamente.

Imagem

Representação JSON 
{
  "mimeType": string,
  "data": string,
  "altText": string
}
Campos
mimeType

string

Obrigatório. O tipo MIME padrão da IANA dos dados de origem. Os tipos de imagem compatíveis incluem: * image/png * image/jpeg * image/webp
data

string (bytes format)

Obrigatório. Bytes brutos da imagem.

Uma string codificada em base64.
altText

string

Opcional. O texto alternativo da imagem.

ToolCall

Representação 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

Opcional. O identificador exclusivo da chamada de ferramenta. Se preenchido, o cliente vai retornar o resultado da execução com o código correspondente em ToolResponse.
displayName

string

Apenas saída. Nome de exibição da ferramenta.
args

object (Struct format)

Opcional. Os parâmetros de entrada e os valores da ferramenta no formato de objeto JSON.
parentToolCallId

string

Apenas saída. O ID da chamada de ferramenta que causou esta, quando foi emitida por um subagente trabalhando em nome de uma chamada pai. Vazio para chamadas de nível superior. Permite que um cliente agrupe o trabalho de um subagente na chamada que o iniciou, em vez de renderizar cada etapa como um irmão.
agentName

string

Apenas saída. Nome legível por humanos do agente que emitiu essa chamada, por exemplo, "Arquiteto de contratos". Vazio quando o agente raiz o emitiu.
targetApp

string

Apenas saída. O app que essa chamada segmenta, derivado pelo assistente dos argumentos de recurso da chamada: um nome de recurso de app, PROJECT para ferramentas com escopo de local ou vazio para ferramentas locais de sessão. Defina apenas em sessões do assistente com escopo de projeto.
Campo de união tool_identifier. O identificador da ferramenta a ser executada. Pode ser uma ferramenta persistente ou de um conjunto de ferramentas. tool_identifier pode ser apenas de um dos tipos a seguir:
tool

string

Opcional. O nome da ferramenta a ser executada. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Opcional. A ferramenta do conjunto de ferramentas a ser executada.

ToolsetTool

Representação JSON 
{
  "toolset": string,
  "toolId": string
}
Campos
toolset

string

Obrigatório. O nome do recurso do conjunto de ferramentas de onde essa ferramenta é derivada. Formato: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolId

string

Opcional. O ID da ferramenta para filtrar as ferramentas e recuperar o esquema.

ToolResponse

Representação 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

Opcional. O código correspondente do tool call a que a resposta se refere.
displayName

string

Apenas saída. Nome de exibição da ferramenta.
response

object (Struct format)

Obrigatório. O resultado da execução da ferramenta no formato de objeto JSON. Use a chave "output" para especificar a resposta da ferramenta e a chave "error" para especificar os detalhes do erro (se houver). Se as chaves "output" e "error" não forem especificadas, toda a "response" será tratada como resultado da execução da ferramenta.
parentToolCallId

string

Apenas saída. O ID da chamada de ferramenta que causou esta, quando foi emitida por um subagente trabalhando em nome de uma chamada pai. Vazio para chamadas de nível superior. Permite que um cliente agrupe o trabalho de um subagente na chamada que o iniciou, em vez de renderizar cada etapa como um irmão.
agentName

string

Apenas saída. Nome legível por humanos do agente que emitiu essa chamada, por exemplo, "Arquiteto de contratos". Vazio quando o agente raiz o emitiu.
targetApp

string

Apenas saída. O app que a ferramenta executada segmentou; espelha ToolCall.target_app.
Campo de união tool_identifier. O identificador da ferramenta que foi executada. Pode ser uma ferramenta persistente ou de um conjunto de ferramentas. tool_identifier pode ser apenas de um dos tipos a seguir:
tool

string

Opcional. O nome da ferramenta a ser executada. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Opcional. A ferramenta do conjunto que foi executada.

AgentTransfer

Representação JSON 
{
  "targetAgent": string,
  "displayName": string
}
Campos
targetAgent

string

Obrigatório. O agente para quem a conversa está sendo transferida. O agente vai assumir a conversa a partir desse momento. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Apenas saída. Nome de exibição do agente.

Período

Representação JSON 
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "duration": string,
  "attributes": {
    object
  },
  "childSpans": [
    {
      object (Span)
    }
  ]
}
Campos
name

string

Apenas saída. O nome do período.
startTime

string (Timestamp format)

Apenas saída. O horário de início do período.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Apenas saída. O horário de término do período.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

Apenas saída. A duração do período.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
attributes

object (Struct format)

Apenas saída. Atributos de chave-valor associados ao período.
childSpans[]

object (Span)

Apenas saída. Os períodos filhos que estão aninhados neste período.

Duração

Representação JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Segundos assinados do período. Precisa ser de -315.576.000.000 a +315.576.000.000, inclusive. Observação: esses limites são calculados da seguinte forma: 60 s/min * 60 min/h * 24 h/dia * 365,25 dias/ano * 10.000 anos
nanos

integer

Frações assinadas de um segundo com resolução de nanossegundos do período. As durações menores que um segundo são representadas com um campo seconds de 0 e um campo nanos positivo ou negativo. Para durações de um segundo ou mais, um valor diferente de zero para o campo nanos precisa ter o mesmo sinal que o campo seconds. O valor precisa ser de -999.999.999 a +999.999.999.

NullValue

Representa um null JSON.

NullValue é um sentinela, que usa um tipo enumerado com apenas um valor para representar o valor nulo da união de tipos Value.

Um campo do tipo NullValue com qualquer valor diferente de 0 é considerado inválido. A maioria dos serializadores ProtoJSON emite um Value com um null_value definido como um null JSON, independentemente do valor inteiro, e, portanto, faz uma ida e volta para um valor 0.

Tipos enumerados
NULL_VALUE Valor nulo.

ChannelType

O tipo de canal da conversa.

Tipos enumerados
CHANNEL_TYPE_UNSPECIFIED Tipo de canal não especificado.
TEXT A conversa contém apenas mensagens de texto entre o usuário final e o agente.
AUDIO A conversa contém mensagens de áudio entre o usuário final e o agente.
MULTIMODAL As mensagens multimodais da conversa (por exemplo, imagem) entre o usuário final e o agente.

Origem

A origem da conversa.

Tipos enumerados
SOURCE_UNSPECIFIED Origem não especificada.
LIVE A conversa é do usuário final ao vivo.
SIMULATOR A conversa é do simulador.
EVAL A conversa é da avaliação.
AGENT_TOOL A conversa é de uma ferramenta de agente. A ferramenta de agente executa o agente em uma sessão separada, que é mantida para fins de teste e depuração.

InputType

Tipo da mensagem de entrada.

Tipos enumerados
INPUT_TYPE_UNSPECIFIED Tipo de entrada não especificado.
INPUT_TYPE_TEXT Entrada de texto.
INPUT_TYPE_EVENT Entrada de evento.
INPUT_TYPE_AUDIO Entrada de áudio.
INPUT_TYPE_IMAGE Entrada de imagem.
INPUT_TYPE_BLOB Entrada de blob.
INPUT_TYPE_TOOL_RESPONSE Entrada de resposta da ferramenta de função do cliente.
INPUT_TYPE_VARIABLES Entrada de variáveis.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando uma solicitação de confirmação pode ser enviada a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

  • readOnlyHint: se for verdadeiro, a ferramenta não vai modificar o ambiente. Padrão: false.
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. Padrão: false.
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de jogos de mundo aberto: ❌