MCP Tools Reference: ces.googleapis.com

Strumento: list_conversations

Elenca le conversazioni.

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

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": "list_conversations",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schema di input

Messaggio di richiesta per AgentService.ListConversations.

ListConversationsRequest

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

string

Obbligatorio. Il nome della risorsa dell'app da cui elencare le conversazioni.
pageSize

integer

Facoltativo. Dimensioni della pagina richiesta. Il server potrebbe restituire meno elementi di quelli richiesti. Se non specificato, il server sceglierà un valore predefinito appropriato.
pageToken

string

Facoltativo. Il valore next_page_token restituito da una chiamata AgentService.ListConversations dell'elenco precedente.
filter

string

Facoltativo. Filtro da applicare quando vengono elencate le conversazioni. Per maggiori dettagli, visita la pagina https://google.aip.dev/160.
source

enum (Source)

Facoltativo. Indica l'origine della conversazione. Se non viene impostato, verrà applicato Source.Live per impostazione predefinita. Verrà ritirato a favore del campo sources.
sources[]

enum (Source)

Facoltativo. Indica le fonti delle conversazioni. Se non viene impostato, per impostazione predefinita verranno applicate tutte le origini disponibili.

Origine

L'origine della conversazione.

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

Schema di output

Messaggio di risposta per AgentService.ListConversations.

ListConversationsResponse

Rappresentazione JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Campi
conversations[]

object (Conversation)

L'elenco delle conversazioni.
nextPageToken

string

Un token che può essere inviato come ListConversationsRequest.page_token per recuperare la pagina successiva. L'assenza di questo campo indica che non sono presenti pagine successive.

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 della 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 del momento in cui la conversazione è stata completata.

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 nella conversazione.
turnCount

integer

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

enum (ChannelType)

DEPRECATO. 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 elaborare la conversazione. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
appVersion

string

Solo output. La versione dell'app utilizzata per elaborare la 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 dell'ora UTC dall'epoca di Unix 1970-01-01T00:00:00Z. Deve essere compreso tra -62135596800 e 253402300799 inclusi (che corrispondono a un intervallo compreso tra 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 parte in nanosecondi della durata, non un'alternativa ai secondi. I valori dei secondi negativi con frazioni devono comunque avere valori di nanosecondi non negativi che avanzano nel tempo. Deve essere un valore 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'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 di riferimento previsto del chiamante simulato (Polysynth). Compilato solo quando sono abilitate le metriche relative al tasso di errore delle parole.

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 sotto forma di 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. 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)

Uno struct rappresenta le variabili aggiornate nella conversazione, con i nomi delle variabili come chiavi.
defaultVariables

object (Struct format)

Una struttura rappresenta le variabili predefinite all'inizio della conversazione, con i nomi delle variabili come chiavi.

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, poiché questi valori 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

Rappresentano 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 dell'immagine.

ToolCall

Rappresentazione 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.
}
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 chiamata, 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 client di raggruppare il lavoro di un sub-agente sotto la chiamata che lo ha avviato, anziché visualizzare ogni passaggio come elemento di pari livello.
agentName

string

Solo output. Nome leggibile dell'agente che ha emesso questa chiamata, ad esempio "Contract Architect". Vuoto quando è stato emesso dall'agente principale.
targetApp

string

Solo output. L'app a cui è destinata questa chiamata, derivata dall'assistente dagli argomenti della risorsa della chiamata: un nome della risorsa dell'app, PROJECT per gli strumenti con ambito di località o vuoto per gli strumenti locali della sessione. Impostato solo nelle sessioni dell'assistente con ambito di progetto.
Campo unione tool_identifier. L'identificatore dello strumento da eseguire. Potrebbe essere uno strumento persistente o uno strumento di un set 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 set di strumenti da eseguire.

ToolsetTool

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

string

Obbligatorio. Il nome della risorsa del set di strumenti 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,
  "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.
}
Campi
id

string

Facoltativo. L'ID corrispondenza della 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 le chiavi "output" ed "error" non sono specificate, 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 chiamata, 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 client di raggruppare il lavoro di un sub-agente sotto la chiamata che lo ha avviato, anziché visualizzare ogni passaggio come elemento di pari livello.
agentName

string

Solo output. Nome leggibile dell'agente che ha emesso questa chiamata, ad esempio "Contract Architect". Vuoto quando è stato emesso dall'agente principale.
targetApp

string

Solo output. L'app scelta come target dallo strumento eseguito; rispecchia ToolCall.target_app.
Campo unione tool_identifier. L'identificatore dello strumento eseguito. Potrebbe essere uno strumento persistente o uno strumento di un set 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 set di strumenti 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 momento 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 dello span.

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 con segno dell'intervallo di tempo. Deve essere compreso tra -315.576.000.000 e +315.576.000.000 inclusi. Nota: questi limiti sono calcolati da: 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 enum con un solo valore per rappresentare il valore null 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à un round trip a un valore 0.

Enum
NULL_VALUE Valore null.

ChannelType

Il tipo di canale della conversazione.

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

Origine

L'origine della conversazione.

Enum
SOURCE_UNSPECIFIED Origine non specificata.
LIVE La conversazione è con l'utente finale in tempo reale.
SIMULATOR La conversazione proviene dal simulatore.
EVAL La conversazione proviene dalla valutazione.
AGENT_TOOL La conversazione proviene da uno strumento dell'agente. 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 Immissione 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 degli strumenti 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 una richiesta di conferma a un utente.

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

  • readOnlyHint: se true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se true, lo strumento può eseguire azioni distruttive. Se è false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se true, la chiamata ripetuta dello 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 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: ❌