Method: projects.locations.apps.sessions.runSession

Avvia un'interazione di un solo turno con l'agente CES all'interno di una sessione.

Richiesta HTTP

POST https://ces.googleapis.com/v1beta/{config.session=projects/*/locations/*/apps/*/sessions/*}:runSession

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
config.session

string

Obbligatorio. L'identificatore univoco della sessione. Formato: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "config": {
    "session": string,
    "inputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer,
      "noiseSuppressionLevel": string
    },
    "outputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer
    },
    "historicalContexts": [
      {
        "role": string,
        "chunks": [
          {
            object (Chunk)
          }
        ],
        "eventTime": string
      }
    ],
    "entryAgent": string,
    "deployment": string,
    "timeZone": string,
    "useToolFakes": boolean,
    "remoteDialogflowQueryParameters": {
      "webhookHeaders": {
        string: string,
        ...
      },
      "payload": {
        object
      },
      "endUserMetadata": {
        object
      }
    }
  },
  "inputs": [
    {
      object (SessionInput)
    }
  ]
}
Campi
config.inputAudioConfig

object (InputAudioConfig)

Facoltativo. Configurazione per l'elaborazione dell'audio di input.
config.outputAudioConfig

object (OutputAudioConfig)

Facoltativo. Configurazione per la generazione dell'audio di output.
config.historicalContexts[]

object (Message)

Facoltativo. Il contesto storico della sessione, inclusi gli input dell'utente, le risposte dell'agente e altri messaggi. In genere, l'agente CES gestisce automaticamente la sessione, quindi il cliente non deve compilare esplicitamente questo campo. Tuttavia, il client può facoltativamente ignorare i contesti storici per forzare l'avvio della sessione da un determinato stato.
config.entryAgent

string

Facoltativo. L'agente di ingresso per gestire la sessione. Se non specificata, la sessione verrà gestita da root agent dell'app. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Facoltativo. Il deployment dell'app da utilizzare per la sessione. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Facoltativo. Il fuso orario dell'utente. Se fornito, l'agente utilizzerà il fuso orario per le variabili relative a data e ora. In caso contrario, l'agente utilizzerà il fuso orario specificato in App.time_zone_settings.

Il formato è il fuso orario del database dei fusi orari IANA, ad esempio "America/Los_Angeles".
config.useToolFakes

boolean

Facoltativo. Indica se utilizzare tool falsi per la sessione. Se questo campo è impostato, l'agente tenterà di utilizzare i tool fake anziché chiamare i tool reali.
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Facoltativo. QueryParameters da inviare all'agente Dialogflow remoto quando il controllo della sessione viene trasferito all'agente remoto.
inputs[]

object (SessionInput)

Obbligatorio. Input per la sessione.

Corpo della risposta

Messaggio di risposta per SessionService.RunSession.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Campi
outputs[]

object (SessionOutput)

Output della sessione.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

Per saperne di più, consulta la Authentication Overview.

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa session:

  • ces.sessions.runSession

Per saperne di più, consulta la documentazione di IAM.

SessionConfig

La configurazione della sessione.

Rappresentazione JSON 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "useToolFakes": boolean,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
Campi
session

string

Obbligatorio. L'identificatore univoco della sessione. Formato: projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

Facoltativo. Configurazione per l'elaborazione dell'audio di input.
outputAudioConfig

object (OutputAudioConfig)

Facoltativo. Configurazione per la generazione dell'audio di output.
historicalContexts[]

object (Message)

Facoltativo. Il contesto storico della sessione, inclusi gli input dell'utente, le risposte dell'agente e altri messaggi. In genere, l'agente CES gestisce automaticamente la sessione, quindi il cliente non deve compilare esplicitamente questo campo. Tuttavia, il client può facoltativamente ignorare i contesti storici per forzare l'avvio della sessione da un determinato stato.
entryAgent

string

Facoltativo. L'agente di ingresso per gestire la sessione. Se non specificata, la sessione verrà gestita da root agent dell'app. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Facoltativo. Il deployment dell'app da utilizzare per la sessione. Formato: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

Facoltativo. Il fuso orario dell'utente. Se fornito, l'agente utilizzerà il fuso orario per le variabili relative a data e ora. In caso contrario, l'agente utilizzerà il fuso orario specificato in App.time_zone_settings.

Il formato è il fuso orario del database dei fusi orari IANA, ad esempio "America/Los_Angeles".
useToolFakes

boolean

Facoltativo. Indica se utilizzare tool falsi per la sessione. Se questo campo è impostato, l'agente tenterà di utilizzare i tool fake anziché chiamare i tool reali.
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Facoltativo. QueryParameters da inviare all'agente Dialogflow remoto quando il controllo della sessione viene trasferito all'agente remoto.

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters da inviare all'agente Dialogflow remoto quando il controllo della sessione viene trasferito all'agente remoto.

Rappresentazione JSON 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
Campi
webhookHeaders

map (key: string, value: string)

Facoltativo. Le intestazioni HTTP da inviare come webhookHeaders in QueryParameters.

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

object (Struct format)

Facoltativo. Il payload da inviare in QueryParameters.
endUserMetadata

object (Struct format)

Facoltativo. I metadati dell'utente finale da inviare in QueryParameters.

SessionOutput

Output della sessione.

Rappresentazione JSON 
{
  "turnIndex": integer,
  "turnCompleted": boolean,
  "diagnosticInfo": {
    object (SessionOutput.DiagnosticInfo)
  },

  // Union field output_type can be only one of the following:
  "text": string,
  "audio": string,
  "toolCalls": {
    object (ToolCalls)
  },
  "citations": {
    object (Citations)
  },
  "googleSearchSuggestions": {
    object (GoogleSearchSuggestions)
  },
  "endSession": {
    object (EndSession)
  },
  "payload": {
    object
  }
  // End of list of possible types for union field output_type.
}
Campi
turnIndex

integer

Indica l'ordine sequenziale del turno di conversazione a cui appartiene questo output, a partire da 1.
turnCompleted

boolean

Se il valore è true, l'agente CES ha rilevato la fine del turno di conversazione corrente e non fornirà ulteriori output per questo turno.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Facoltativo. Le informazioni diagnostiche contengono i dettagli di esecuzione durante l'elaborazione dell'input. Viene compilato solo nell'ultimo SessionOutput (con turnCompleted=true) per ogni turno.
Campo unione output_type. Il tipo di output. output_type può essere solo uno dei seguenti tipi:
text

string

Testo di output dell'agente CES.
audio

string (bytes format)

Output audio dell'agente CES.

Una stringa con codifica in base64.
toolCalls

object (ToolCalls)

Richiedi al cliente di eseguire gli strumenti.
citations

object (Citations)

Citazioni che forniscono le informazioni sulla fonte del testo generato dall'agente.
googleSearchSuggestions

object (GoogleSearchSuggestions)

I suggerimenti restituiti dalla Ricerca Google in seguito all'invocazione di GoogleSearchTool.
endSession

object (EndSession)

Indica che la sessione è terminata.
payload

object (Struct format)

Payload personalizzato con output strutturato dell'agente CES.

ToolCalls

Richiesta al client di eseguire gli strumenti e restituire i risultati dell'esecuzione prima di continuare la sessione.

Rappresentazione JSON 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Campi
toolCalls[]

object (ToolCall)

Facoltativo. L'elenco delle chiamate agli strumenti da eseguire.

Citazioni

Citazioni associate alla risposta dell'agente.

Rappresentazione JSON 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Campi
citedChunks[]

object (Citations.CitedChunk)

Elenco delle informazioni citate.

Citations.CitedChunk

Informazione citata.

Rappresentazione JSON 
{
  "uri": string,
  "title": string,
  "text": string
}
Campi
uri

string

URI utilizzato per la citazione.
title

string

Il titolo del documento citato.
text

string

Testo utilizzato per la citazione.

GoogleSearchSuggestions

Suggerimenti di ricerca da Google Search Tool.

Rappresentazione JSON 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Campi
htmls[]

string

Stili HTML e CSS conformi per i suggerimenti di ricerca. I codici HTML e CSS forniti si adattano automaticamente alle impostazioni del dispositivo, visualizzando la modalità Luce o Buio indicata da @media(prefers-color-scheme).
webSearchQueries[]

object (WebSearchQuery)

Elenco delle query utilizzate per eseguire la ricerca Google insieme agli URI dei risultati di ricerca che formano i suggerimenti di ricerca.

WebSearchQuery

Rappresenta una singola query di ricerca web e il relativo URI di ricerca.

Rappresentazione JSON 
{
  "query": string,
  "uri": string
}
Campi
query

string

Il testo della query di ricerca.
uri

string

L'URI alla pagina dei risultati di ricerca di Google per la query.

EndSession

Indica che la sessione è terminata, a causa del completamento riuscito (ad es. l'utente dice "Arrivederci") ) o un riassegnazione a un agente.

L'agente non elaborerà ulteriori input dopo la chiusura della sessione e il client deve chiudere a metà e disconnettersi dopo aver ricevuto tutte le risposte rimanenti dall'agente.

Rappresentazione JSON 
{
  "metadata": {
    object
  }
}
Campi
metadata

object (Struct format)

Facoltativo. Fornisce ulteriori informazioni sull'indicatore di fine sessione, ad esempio il motivo della fine della sessione.

SessionOutput.DiagnosticInfo

Contiene i dettagli di esecuzione durante l'elaborazione.

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

object (Message)

Elenco dei messaggi che si sono verificati durante l'elaborazione.
rootSpan

object (Span)

Una traccia dell'intera elaborazione della richiesta, rappresentata come uno span radice. Questo intervallo può contenere intervalli secondari nidificati per operazioni specifiche.