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/v1/{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,
    "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.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,
  "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".
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

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

InputAudioConfig

InputAudioConfig configura la modalità di interpretazione dei dati audio in arrivo da parte dell'agente CES.

Rappresentazione JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Campi
audioEncoding

enum (AudioEncoding)

Obbligatorio. La codifica dei dati audio di input.
sampleRateHertz

integer

Obbligatorio. La frequenza di campionamento (in hertz) dei dati audio di input.
noiseSuppressionLevel

string

Facoltativo. Indica se attivare la soppressione del rumore nell'audio di input. I valori disponibili sono "low", "moderate", "high", "very_high".

AudioEncoding

AudioEncoding specifica il formato di codifica per i dati audio.

Enum
AUDIO_ENCODING_UNSPECIFIED Codifica audio non specificata.
LINEAR16 Codifica audio PCM lineare a 16 bit.
MULAW Campioni a 8 bit che comprimono campioni audio a 14 bit utilizzando G.711 PCMU/mu-law.
ALAW Campioni a 8 bit che comprimono campioni audio a 14 bit utilizzando G.711 PCMU/A-law.

OutputAudioConfig

OutputAudioConfig configura il modo in cui l'agente CES deve sintetizzare le risposte audio in uscita.

Rappresentazione JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Campi
audioEncoding

enum (AudioEncoding)

Obbligatorio. La codifica dei dati audio di output.
sampleRateHertz

integer

Obbligatorio. La frequenza di campionamento (in hertz) dei dati audio di output.

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.

SessionInput

Input per la sessione.

Rappresentazione JSON 
{
  "willContinue": boolean,

  // Union field input_type can be only one of the following:
  "text": string,
  "dtmf": string,
  "audio": string,
  "toolResponses": {
    object (ToolResponses)
  },
  "image": {
    object (Image)
  },
  "blob": {
    object (Blob)
  },
  "variables": {
    object
  },
  "event": {
    object (Event)
  }
  // End of list of possible types for union field input_type.
}
Campi
willContinue

boolean

Facoltativo. Un flag che indica se il messaggio corrente è un frammento di un input più grande nella sessione di streaming bidirezionale.

Se impostato su true, l'agente posticipa l'elaborazione fino a quando non riceve un messaggio successivo in cui willContinue è false o fino a quando il sistema non rileva un endpoint nell'input audio.

NOTA: questo campo non si applica agli input audio e DTMF, in quanto vengono sempre elaborati automaticamente in base al segnale di fine.
Campo unione input_type. Il tipo di input. input_type può essere solo uno dei seguenti tipi:
text

string

Facoltativo. Dati di testo dell'utente finale.
dtmf

string

Facoltativo. Cifre DTMF dell'utente finale.
audio

string (bytes format)

Facoltativo. Dati audio dell'utente finale.

Una stringa con codifica in base64.
toolResponses

object (ToolResponses)

Facoltativo. Risultati dell'esecuzione per le chiamate di strumenti dal client.
image

object (Image)

Facoltativo. Dati delle immagini dell'utente finale.
blob

object (Blob)

Facoltativo. Dati blob dell'utente finale.
variables

object (Struct format)

Facoltativo. Variabili contestuali per la sessione, identificate per nome. L'agente CES utilizzerà solo le variabili dichiarate nell'app.

Le variabili non riconosciute verranno comunque inviate all'[agente Dialogflow][Agent.RemoteDialogflowAgent] come parametri di sessione aggiuntivi.
event

object (Event)

Facoltativo. Input evento.

ToolResponses

Risultati dell'esecuzione per le chiamate agli strumenti richieste dal client.

Rappresentazione JSON 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Campi
toolResponses[]

object (ToolResponse)

Facoltativo. L'elenco dei risultati dell'esecuzione dello strumento.

Evento

Input evento.

Rappresentazione JSON 
{
  "event": string
}
Campi
event

string

Obbligatorio. Il nome dell'evento.

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