MCP Tools Reference: ces.googleapis.com

Strumento: get_conversation

Recupera i dettagli della conversazione specificata.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP get_conversation.

Richiesta 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
}'

Schema di input

Messaggio di richiesta per AgentService.GetConversation.

GetConversationRequest

Rappresentazione JSON 
{
  "name": string,
  "source": enum (Source)
}
Campi
name

string

Obbligatorio. Il nome della risorsa della conversazione da recuperare.
source
(deprecated)

enum (Source)

Facoltativo. Indica l'origine della conversazione. Se non è impostato, verrà eseguita la ricerca in tutte le origini.

Origine

L'origine della conversazione.

Enum
SOURCE_UNSPECIFIED Origine non specificata.
LIVE La conversazione è dell'utente finale live.
SIMULATOR La conversazione proviene dal simulatore.
EVAL La conversazione proviene dalla valutazione.
AGENT_TOOL La conversazione proviene da uno strumento per agenti. Lo strumento agente esegue l'agente in una sessione separata, che viene mantenuta per scopi di test e debug.

Schema di output

Una conversazione rappresenta un'interazione tra un utente finale e l'app CES.

Conversazione

Rappresentazione 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)
    }
  ]
}
Campi
name

string

Identificatore. L'identificatore univoco della conversazione. Formato: projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}
startTime

string (Timestamp format)

Solo output. Timestamp di creazione della conversazione.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Solo output. Timestamp di completamento della conversazione.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
turns[]

object (Turn)

Obbligatorio. I turni della conversazione.
turnCount

integer

Solo output. Il numero di turni nella conversazione.
channelType
(deprecated)

enum (ChannelType)

OBSOLETO. Utilizza invece input_types.
source

enum (Source)

Solo output. Indica l'origine della conversazione.
inputTypes[]

enum (InputType)

Solo output. I tipi di input della conversazione.
entryAgent

string

Solo output. L'agente che gestisce inizialmente la conversazione. Se non specificato, la conversazione viene gestita dall'agente principale. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Solo output. Il deployment dell'app utilizzata per l'elaborazione della conversazione. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
appVersion

string

Solo output. La versione dell'app utilizzata per l'elaborazione della conversazione. Formato: projects/{project}/locations/{location}/apps/{app}/versions/{version}
languageCode

string

Solo output. Il codice lingua della conversazione.
messages[]
(deprecated)

object (Message)

Deprecato. Utilizza invece le svolte.

Timestamp

Rappresentazione JSON 
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Rappresenta i secondi di tempo UTC dall'epoca di Unix 1970-01-01T00:00:00Z. Deve essere compreso tra -62135596800 e 253402300799 inclusi (che corrisponde a 0001-01-01T00:00:00Z e 9999-12-31T23:59:59Z).
nanos

integer

Frazioni di secondo non negative con risoluzione in nanosecondi. Questo campo è la porzione di nanosecondi della durata, non un'alternativa ai secondi. I valori negativi dei secondi con frazioni devono comunque avere valori di nanosecondi non negativi che contano in avanti nel tempo. Il valore deve essere compreso tra 0 e 999.999.999 inclusi.

Accendi

Rappresentazione JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  },
  "userIntendedText": string
}
Campi
messages[]

object (Message)

Facoltativo. Elenco dei messaggi nel turno di conversazione, inclusi l'input utente, le risposte dell'agente e gli eventi intermedi durante l'elaborazione.
rootSpan

object (Span)

Facoltativo. Lo span radice dell'elaborazione dell'azione.
userIntendedText

string

Facoltativo. Il testo basato su dati empirici reali previsto del chiamante simulato (Polysynth). Viene compilato solo quando sono attivate le metriche del tasso di errore di parola.

Messaggio

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

string

Facoltativo. Il ruolo all'interno della conversazione, ad esempio utente, agente.
chunks[]

object (Chunk)

Facoltativo. Contenuto del messaggio come una serie di blocchi.
eventTime

string (Timestamp format)

Facoltativo. Timestamp di invio o ricezione del messaggio. Non deve essere utilizzato se il messaggio fa parte di un example.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

Chunk

Rappresentazione 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.
}
Campi
Campo unione data. Dividi i dati in blocchi. data può essere solo uno dei seguenti tipi:
text

string

Facoltativo. Dati di testo.
transcript

string

Facoltativo. Trascrizione associata all'audio.
blob

object (Blob)

Facoltativo. Dati blob.
payload

object (Struct format)

Facoltativo. Dati di payload personalizzati.
image

object (Image)

Facoltativo. Dati immagine.
toolCall

object (ToolCall)

Facoltativo. Richiesta di esecuzione dello strumento.
toolResponse

object (ToolResponse)

Facoltativo. Risposta dell'esecuzione dello strumento.
agentTransfer

object (AgentTransfer)

Facoltativo. Evento di trasferimento dell'agente.
updatedVariables

object (Struct format)

Una struct rappresenta le variabili aggiornate nella conversazione, identificate dai nomi delle variabili.
defaultVariables

object (Struct format)

Una struct rappresenta le variabili predefinite all'inizio della conversazione, identificate dai nomi delle variabili.

Blob

Rappresentazione JSON 
{
  "mimeType": string,
  "data": string
}
Campi
mimeType

string

Obbligatorio. Il tipo MIME standard IANA dei dati di origine.
data

string (bytes format)

Obbligatorio. Byte non elaborati del blob.

Una stringa con codifica in base64.

Struct

Rappresentazione JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campi
fields

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

Mappa non ordinata di valori con tipo dinamico.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

Rappresentazione JSON 
{
  "key": string,
  "value": value
}
Campi
key

string
value

value (Value format)

Valore

Rappresentazione 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.
}
Campi
Campo unione kind. Il tipo di valore. kind può essere solo uno dei seguenti tipi:
nullValue

null

Rappresenta un null JSON.
numberValue

number

Rappresenta un numero JSON. Non deve essere NaN, Infinity o -Infinity, in quanto non sono supportati in JSON. Inoltre, non può rappresentare valori Int64 di grandi dimensioni, poiché il formato JSON in genere non li supporta nel tipo di numero.
stringValue

string

Rappresenta una stringa JSON.
boolValue

boolean

Rappresenta un valore booleano JSON (valore letterale true o false in JSON).
structValue

object (Struct format)

Rappresenta un oggetto JSON.
listValue

array (ListValue format)

Rappresenta un array JSON.

ListValue

Rappresentazione JSON 
{
  "values": [
    value
  ]
}
Campi
values[]

value (Value format)

Campo ripetuto di valori con tipo dinamico.

Immagine

Rappresentazione JSON 
{
  "mimeType": string,
  "data": string,
  "altText": string
}
Campi
mimeType

string

Obbligatorio. Il tipo MIME standard IANA dei dati di origine. I tipi di immagini supportati includono: * image/png * image/jpeg * image/webp
data

string (bytes format)

Obbligatorio. Byte non elaborati dell'immagine.

Una stringa con codifica in base64.
altText

string

Facoltativo. Il testo alternativo per l'immagine.

ToolCall

Rappresentazione JSON 
{
  "id": string,
  "displayName": string,
  "args": {
    object
  },
  "parentToolCallId": string,
  "agentName": 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.
}
Campi
id

string

Facoltativo. L'identificatore univoco della chiamata allo strumento. Se compilato, il client deve restituire il risultato dell'esecuzione con l'ID corrispondenza in ToolResponse.
displayName

string

Solo output. Nome visualizzato dello strumento.
args

object (Struct format)

Facoltativo. I parametri e i valori di input per lo strumento in formato oggetto JSON.
parentToolCallId

string

Solo output. L'ID della chiamata allo strumento che ha causato questa, quando è stata emessa da un sub-agente che lavora per conto di una chiamata principale. Vuoto per le chiamate di primo livello. Consente a un cliente di raggruppare il lavoro di un subagente nella chiamata che lo ha avviato, anziché visualizzare ogni passaggio come elemento di pari livello.
agentName

string

Solo output. Nome leggibile dell'agente che ha effettuato questa chiamata, ad es. "Contract Architect". Vuoto quando è stato emesso dall'agente principale.
Campo unione tool_identifier. L'identificatore dello strumento da eseguire. Può trattarsi di uno strumento persistente o di uno strumento di un insieme di strumenti. tool_identifier può essere solo uno dei seguenti tipi:
tool

string

Facoltativo. Il nome dello strumento da eseguire. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Facoltativo. Lo strumento del toolset da eseguire.

ToolsetTool

Rappresentazione JSON 
{
  "toolset": string,
  "toolId": string
}
Campi
toolset

string

Obbligatorio. Il nome della risorsa del Toolset da cui deriva questo strumento. Formato: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolId

string

Facoltativo. L'ID dello strumento per filtrare gli strumenti per cui recuperare lo schema.

ToolResponse

Rappresentazione JSON 
{
  "id": string,
  "displayName": string,
  "response": {
    object
  },
  "parentToolCallId": string,
  "agentName": 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.
}
Campi
id

string

Facoltativo. L'ID corrispondenza di tool call a cui si riferisce la risposta.
displayName

string

Solo output. Nome visualizzato dello strumento.
response

object (Struct format)

Obbligatorio. Il risultato dell'esecuzione dello strumento in formato oggetto JSON. Utilizza la chiave "output" per specificare la risposta dello strumento e la chiave "error" per specificare i dettagli dell'errore (se presenti). Se non vengono specificate le chiavi "output" ed "error", l'intera "response" viene trattata come risultato dell'esecuzione dello strumento.
parentToolCallId

string

Solo output. L'ID della chiamata allo strumento che ha causato questa, quando è stata emessa da un sub-agente che lavora per conto di una chiamata principale. Vuoto per le chiamate di primo livello. Consente a un cliente di raggruppare il lavoro di un subagente nella chiamata che lo ha avviato, anziché visualizzare ogni passaggio come elemento di pari livello.
agentName

string

Solo output. Nome leggibile dell'agente che ha effettuato questa chiamata, ad es. "Contract Architect". Vuoto quando è stato emesso dall'agente principale.
Campo unione tool_identifier. L'identificatore dello strumento eseguito. Può trattarsi di uno strumento persistente o di uno strumento di un insieme di strumenti. tool_identifier può essere solo uno dei seguenti tipi:
tool

string

Facoltativo. Il nome dello strumento da eseguire. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

Facoltativo. Lo strumento del toolset che è stato eseguito.

AgentTransfer

Rappresentazione JSON 
{
  "targetAgent": string,
  "displayName": string
}
Campi
targetAgent

string

Obbligatorio. L'agente a cui viene trasferita la conversazione. L'agente gestirà la conversazione da questo punto in poi. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Solo output. Nome visualizzato dell'agente.

Intervallo

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

string

Solo output. Il nome dello span.
startTime

string (Timestamp format)

Solo output. L'ora di inizio dello span.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Solo output. L'ora di fine dell'intervallo.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

Solo output. La durata dell'intervallo.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
attributes

object (Struct format)

Solo output. Attributi coppia chiave-valore associati allo span.
childSpans[]

object (Span)

Solo output. Gli intervalli secondari nidificati in questo intervallo.

Durata

Rappresentazione JSON 
{
  "seconds": string,
  "nanos": integer
}
Campi
seconds

string (int64 format)

Secondi firmati dell'intervallo di tempo. Deve essere compreso tra -315.576.000.000 e +315.576.000.000 inclusi. Nota: questi limiti vengono calcolati in base a: 60 sec/min * 60 min/ora * 24 ore/giorno * 365,25 giorni/anno * 10.000 anni
nanos

integer

Frazioni di secondo con segno con risoluzione in nanosecondi dell'intervallo di tempo. Le durate inferiori a un secondo sono rappresentate con un campo seconds pari a 0 e un campo nanos positivo o negativo. Per durate di un secondo o più, un valore diverso da zero per il campo nanos deve avere lo stesso segno del campo seconds. Deve essere compreso tra -999.999.999 e +999.999.999 inclusi.

NullValue

Rappresenta un null JSON.

NullValue è un sentinel che utilizza un'enumerazione con un solo valore per rappresentare il valore nullo per l'unione di tipi Value.

Un campo di tipo NullValue con un valore diverso da 0 è considerato non valido. La maggior parte dei serializzatori ProtoJSON emetterà un Value con un null_value impostato come null JSON indipendentemente dal valore intero, quindi eseguirà l'andata e il ritorno a un valore 0.

Enum
NULL_VALUE Valore nullo.

ChannelType

Il tipo di canale della conversazione.

Enum
CHANNEL_TYPE_UNSPECIFIED Tipo di canale non specificato.
TEXT La conversazione contiene solo messaggi di testo tra l'utente finale e l'agente.
AUDIO La conversazione contiene messaggi audio tra l'utente finale e l'agente.
MULTIMODAL I messaggi multimodali (ad es. immagini) della conversazione tra l'utente finale e l'agente.

Origine

L'origine della conversazione.

Enum
SOURCE_UNSPECIFIED Origine non specificata.
LIVE La conversazione è dell'utente finale live.
SIMULATOR La conversazione proviene dal simulatore.
EVAL La conversazione proviene dalla valutazione.
AGENT_TOOL La conversazione proviene da uno strumento per agenti. Lo strumento agente esegue l'agente in una sessione separata, che viene mantenuta per scopi di test e debug.

InputType

Tipo di messaggio di input.

Enum
INPUT_TYPE_UNSPECIFIED Tipo di input non specificato.
INPUT_TYPE_TEXT Inserimento testo.
INPUT_TYPE_EVENT Input dell'evento.
INPUT_TYPE_AUDIO Input audio.
INPUT_TYPE_IMAGE Input di immagini.
INPUT_TYPE_BLOB Input blob.
INPUT_TYPE_TOOL_RESPONSE Input di risposta dello strumento della funzione client.
INPUT_TYPE_VARIABLES Input delle variabili.

Annotazioni dello strumento

Le annotazioni dello strumento vengono inviate ai client MCP per descrivere il rischio di base di un determinato strumento. La maggior parte dei client considera questi suggerimenti non attendibili, ma possono essere utilizzati per decidere quando inviare un prompt di conferma a un utente.

Oltre alla stringa del titolo, sono definiti i seguenti suggerimenti booleani:

  • readOnlyHint: se è true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se è true, lo strumento può eseguire azioni distruttive. Se il valore è false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se è true, chiamare ripetutamente lo strumento con gli stessi argomenti non avrà alcun effetto aggiuntivo sul suo ambiente. Valore predefinito: false.
  • openWorldHint: se è true, lo strumento può interagire con un "open world" di entità esterne. Se è false, lo strumento può interagire solo con le entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria non lo sarebbe.

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌