MCP Tools Reference: ces.googleapis.com

Strumento: list_agents

Elenca gli agenti nell'app specificata.

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

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

Schema di input

Messaggio di richiesta per AgentService.ListAgents.

ListAgentsRequest

Rappresentazione JSON 
{
  "parent": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string,
  "orderBy": string
}
Campi
parent

string

Obbligatorio. Il nome della risorsa dell'app da cui elencare gli agenti.
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 precedente chiamata AgentService.ListAgents dell'elenco.
filter

string

Facoltativo. Filtro da applicare durante l'elenco degli agenti. Per maggiori dettagli, visita la pagina https://google.aip.dev/160.
orderBy

string

Facoltativo. Campo in base al quale ordinare. Sono supportati solo "name" e "create_time". Per maggiori dettagli, visita la pagina https://google.aip.dev/132#ordering.

Schema di output

Messaggio di risposta per AgentService.ListAgents.

ListAgentsResponse

Rappresentazione JSON 
{
  "agents": [
    {
      object (Agent)
    }
  ],
  "nextPageToken": string
}
Campi
agents[]

object (Agent)

L'elenco degli agenti.
nextPageToken

string

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

Agente

Rappresentazione JSON 
{
  "name": string,
  "displayName": string,
  "description": string,
  "modelSettings": {
    object (ModelSettings)
  },
  "instruction": string,
  "tools": [
    string
  ],
  "childAgents": [
    string
  ],
  "beforeAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "guardrails": [
    string
  ],
  "etag": string,
  "toolsets": [
    {
      object (AgentToolset)
    }
  ],
  "generatedSummary": string,
  "transferRules": [
    {
      object (TransferRule)
    }
  ],
  "validationErrors": [
    string
  ],

  // Union field agent_type can be only one of the following:
  "llmAgent": {
    object (LlmAgent)
  },
  "remoteDialogflowAgent": {
    object (RemoteDialogflowAgent)
  }
  // End of list of possible types for union field agent_type.
}
Campi
name

string

Identificatore. L'identificatore univoco dell'agente. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Obbligatorio. Nome visualizzato dell'agente.
description

string

Facoltativo. Descrizione dell'agente leggibile.
modelSettings

object (ModelSettings)

Facoltativo. Configurazioni per il modello LLM.
instruction

string

Facoltativo. Istruzioni per il modello LLM per guidare il comportamento dell'agente.
tools[]

string

Facoltativo. Elenco degli strumenti disponibili per l'agente. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

Facoltativo. Elenco degli agenti secondari nell'albero degli agenti. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

Facoltativo. Le funzioni di callback da eseguire prima di chiamare l'agente. Le callback fornite vengono eseguite in sequenza nell'ordine esatto in cui sono elencate. Se un callback restituisce una risposta sostituita, l'esecuzione si interrompe e tutti i callback rimanenti vengono ignorati.
afterAgentCallbacks[]

object (Callback)

Facoltativo. I callback da eseguire dopo la chiamata all'agente. Le callback fornite vengono eseguite in sequenza nell'ordine esatto in cui sono elencate. Se un callback restituisce una risposta sostituita, l'esecuzione si interrompe e tutti i callback rimanenti vengono ignorati.
beforeModelCallbacks[]

object (Callback)

Facoltativo. I callback da eseguire prima di chiamare il modello. Se vengono effettuate più chiamate al modello, il callback verrà eseguito più volte. Le callback fornite vengono eseguite in sequenza nell'ordine esatto in cui sono elencate. Se un callback restituisce una risposta sostituita, l'esecuzione si interrompe e tutti i callback rimanenti vengono ignorati.
afterModelCallbacks[]

object (Callback)

Facoltativo. I callback da eseguire dopo la chiamata al modello. Se vengono effettuate più chiamate al modello, il callback verrà eseguito più volte. Le callback fornite vengono eseguite in sequenza nell'ordine esatto in cui sono elencate. Se un callback restituisce una risposta sostituita, l'esecuzione si interrompe e tutti i callback rimanenti vengono ignorati.
beforeToolCallbacks[]

object (Callback)

Facoltativo. Le funzioni di callback da eseguire prima di richiamare lo strumento. Se ci sono più chiamate di strumenti, il callback verrà eseguito più volte. Le callback fornite vengono eseguite in sequenza nell'ordine esatto in cui sono elencate. Se un callback restituisce una risposta sostituita, l'esecuzione si interrompe e tutti i callback rimanenti vengono ignorati.
afterToolCallbacks[]

object (Callback)

Facoltativo. I callback da eseguire dopo l'invocazione dello strumento. Se ci sono più chiamate di strumenti, il callback verrà eseguito più volte. Le callback fornite vengono eseguite in sequenza nell'ordine esatto in cui sono elencate. Se un callback restituisce una risposta sostituita, l'esecuzione si interrompe e tutti i callback rimanenti vengono ignorati.
createTime

string (Timestamp format)

Solo output. Timestamp di creazione dell'agente.

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".
updateTime

string (Timestamp format)

Solo output. Timestamp dell'ultimo aggiornamento dell'agente.

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".
guardrails[]

string

Facoltativo. Elenco delle barriere protettive per l'agente. Formato: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

Etag utilizzato per garantire che l'oggetto non sia stato modificato durante un'operazione di lettura, modifica e scrittura. Se l'etag è vuoto, l'aggiornamento sovrascriverà eventuali modifiche simultanee.
toolsets[]

object (AgentToolset)

Facoltativo. Elenco dei toolset per l'agente.
generatedSummary

string

Solo output. Se l'agente viene generato dall'assistente LLM, questo campo contiene un riepilogo descrittivo della generazione.
transferRules[]

object (TransferRule)

Facoltativo. Regole di trasferimento dell'agente. Se corrispondono più regole, verrà utilizzata la prima nell'elenco.
validationErrors[]

string

Solo output. Errori o configurazioni errate nell'agente che potrebbero influire sulla qualità dell'agente.
Campo unione agent_type. Il tipo di agente. agent_type può essere solo uno dei seguenti tipi:
llmAgent

object (LlmAgent)

Facoltativo. Il tipo di agente predefinito.
remoteDialogflowAgent

object (RemoteDialogflowAgent)

Facoltativo. L'agente Dialogflow remoto da utilizzare per l'esecuzione dell'agente. Se questo campo è impostato, tutte le altre proprietà a livello di agente verranno ignorate.

Nota: se l'agente Dialogflow si trova in un progetto diverso dall'app, devi concedere roles/dialogflow.client al service agent CES service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com.

RemoteDialogflowAgent

Rappresentazione JSON 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean,
  "languageCodeVariable": string
}
Campi
agent

string

Obbligatorio. Il nome risorsa dell'agente Dialogflow. Formato: projects/{project}/locations/{location}/agents/{agent}
flowId

string

Facoltativo. L'ID del flusso nell'agente Dialogflow.
environmentId

string

Facoltativo. L'ID ambiente dell'agente Dialogflow da utilizzare per l'esecuzione dell'agente. Se non specificato, verrà utilizzato l'ambiente bozza.
inputVariableMapping

map (key: string, value: string)

Facoltativo. Il mapping dei nomi delle variabili dell'app ai nomi dei parametri di sessione di Dialogflow da inviare all'agente Dialogflow come input.

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

map (key: string, value: string)

Facoltativo. La mappatura dei nomi dei parametri di sessione di Dialogflow ai nomi delle variabili dell'app da inviare di nuovo all'agente CES al termine dell'esecuzione dell'agente Dialogflow.

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

boolean

Facoltativo. Indica se rispettare le impostazioni di interruzione a livello di messaggio configurate nell'agente Dialogflow.

  • Se è false, tutti i messaggi di risposta dell'agente Dialogflow seguono le impostazioni di interruzione a livello di app.
  • Se è true: solo i messaggi di risposta con allow_playback_interruption impostato su true saranno interrompibili, tutti gli altri messaggi seguono le impostazioni di interruzione a livello di app.
languageCodeVariable

string

Facoltativo. Il nome della variabile che contiene il codice della lingua da utilizzare per la sessione Dialogflow. Se non specificato, verrà utilizzato il codice di lingua predefinito dell'agente Dialogflow.

InputVariableMappingEntry

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

string
value

string

OutputVariableMappingEntry

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

string
value

string

ModelSettings

Rappresentazione JSON 
{
  "model": string,

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
Campi
model

string

Facoltativo. Il modello LLM che l'agente deve utilizzare. Se non è impostato, l'agente erediterà il modello dall'agente principale.

Campo unione _temperature.

_temperature può essere solo uno dei seguenti tipi:
temperature

number

Facoltativo. Se impostata, questa temperatura verrà utilizzata per il modello LLM. La temperatura controlla la casualità delle risposte del modello. Le temperature più basse producono risposte più prevedibili. Le temperature più alte producono risposte più creative.

Callback

Rappresentazione JSON 
{
  "description": string,
  "disabled": boolean,
  "proactiveExecutionEnabled": boolean,

  // Union field callback can be only one of the following:
  "pythonCode": string
  // End of list of possible types for union field callback.
}
Campi
description

string

Facoltativo. Descrizione leggibile del callback.
disabled

boolean

Facoltativo. Indica se il callback è disattivato. I callback disattivati vengono ignorati dall'agente.
proactiveExecutionEnabled

boolean

Facoltativo. Se abilitata, la richiamata verrà eseguita anche sugli output intermedi del modello. Questa impostazione ha effetto solo dopo il callback del modello. ATTIVA CON CAUTELA. In genere, il callback del modello deve essere eseguito solo dopo aver ricevuto tutte le risposte del modello. L'attivazione dell'esecuzione proattiva può avere implicazioni negative sul costo e sulla latenza dell'esecuzione e deve essere attivata solo in rare situazioni.
Campo unione callback. Il callback da eseguire. callback può essere solo uno dei seguenti tipi:
pythonCode

string

Obbligatorio. Il codice Python da eseguire per il callback.

Timestamp

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

string (int64 format)

Rappresenta i secondi di tempo UTC trascorsi dall'epoca di Unix 1970-01-01T00:00:00Z. Deve essere compreso tra -62135596800 e 253402300799 inclusi (corrispondenti 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 parte in nanosecondi della durata, non un'alternativa ai secondi. I valori negativi dei secondi con frazioni devono comunque avere valori di nanosecondi non negativi che vengono conteggiati in avanti nel tempo. Deve essere compreso tra 0 e 999.999.999 inclusi.

AgentToolset

Rappresentazione JSON 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
Campi
toolset

string

Obbligatorio. Il nome della risorsa del toolset. Formato: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

Facoltativo. Gli ID degli strumenti per filtrare il set di strumenti.

TransferRule

Rappresentazione JSON 
{
  "childAgent": string,
  "direction": enum (Direction),

  // Union field rule_type can be only one of the following:
  "deterministicTransfer": {
    object (DeterministicTransfer)
  },
  "disablePlannerTransfer": {
    object (DisablePlannerTransfer)
  }
  // End of list of possible types for union field rule_type.
}
Campi
childAgent

string

Obbligatorio. Il nome della risorsa dell'agente secondario a cui si applica la regola. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (Direction)

Obbligatorio. La direzione del trasferimento.
Campo unione rule_type. Il tipo di regola. rule_type può essere solo uno dei seguenti tipi:
deterministicTransfer

object (DeterministicTransfer)

Facoltativo. Una regola che viene trasferita immediatamente all'agente di destinazione quando la condizione è soddisfatta.
disablePlannerTransfer

object (DisablePlannerTransfer)

Facoltativo. Regola che impedisce al pianificatore di trasferire la chiamata all'agente di destinazione.

DeterministicTransfer

Rappresentazione JSON 
{

  // Union field condition_type can be only one of the following:
  "expressionCondition": {
    object (ExpressionCondition)
  },
  "pythonCodeCondition": {
    object (PythonCodeCondition)
  }
  // End of list of possible types for union field condition_type.
}
Campi
Campo unione condition_type. La condizione da valutare. condition_type può essere solo uno dei seguenti tipi:
expressionCondition

object (ExpressionCondition)

Facoltativo. Una regola che valuta una condizione di stato della sessione. Se la condizione restituisce il valore true, il trasferimento viene eseguito.
pythonCodeCondition

object (PythonCodeCondition)

Facoltativo. Una regola che utilizza il blocco di codice Python per valutare le condizioni. Se la condizione restituisce il valore true, il trasferimento viene eseguito.

ExpressionCondition

Rappresentazione JSON 
{
  "expression": string
}
Campi
expression

string

Obbligatorio. La rappresentazione di stringa della condizione cloud.api.Expression.

PythonCodeCondition

Rappresentazione JSON 
{
  "pythonCode": string
}
Campi
pythonCode

string

Obbligatorio. Il codice Python da eseguire.

DisablePlannerTransfer

Rappresentazione JSON 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
Campi
expressionCondition

object (ExpressionCondition)

Obbligatorio. Se la condizione restituisce true, il pianificatore non potrà essere trasferito all'agente di destinazione.

Direzione

La direzione del trasferimento.

Enum
DIRECTION_UNSPECIFIED Direzione non specificata.
PARENT_TO_CHILD Trasferimento dall'agente principale all'agente secondario.
CHILD_TO_PARENT Trasferimento dall'agente secondario all'agente principale.

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 a un utente una richiesta di conferma.

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 no.

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