Method: projects.locations.apps.sessions.runSession

Leitet eine einzelne Interaktion mit dem CES-Agenten innerhalb einer Sitzung ein.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
config.session

string

Erforderlich. Die eindeutige ID der Sitzung. Format: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "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)
    }
  ]
}
Felder
config.inputAudioConfig

object (InputAudioConfig)

Optional. Konfiguration für die Verarbeitung des Audioeingangs.
config.outputAudioConfig

object (OutputAudioConfig)

Optional. Konfiguration zum Generieren der Audioausgabe.
config.historicalContexts[]

object (Message)

Optional. Der bisherige Kontext der Sitzung, einschließlich Nutzereingaben, Agentenantworten und anderer Nachrichten. Normalerweise verwaltet der CES-Agent die Sitzung automatisch, sodass der Client dieses Feld nicht explizit ausfüllen muss. Der Client kann die bisherigen Kontexte jedoch optional überschreiben, um den Sitzungsstart in einem bestimmten Zustand zu erzwingen.
config.entryAgent

string

Optional. Der Einstiegs-Agent, der die Sitzung verarbeitet. Wenn nicht angegeben, wird die Sitzung von der root agent der App verarbeitet. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Optional. Die Bereitstellung der App, die für die Sitzung verwendet werden soll. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Optional. Die Zeitzone des Nutzers. Falls angegeben, verwendet der Agent die Zeitzone für datums- und uhrzeitbezogene Variablen. Andernfalls wird die im App.time_zone_settings angegebene Zeitzone verwendet.

Das Format ist die Zeitzone aus der IANA-Zeitzonendatenbank, z.B. „America/Los_Angeles“.
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Optional. QueryParameters, die an den Dialogflow-Remote-Agent gesendet werden sollen, wenn die Sitzungssteuerung an den Remote-Agent übertragen wird.
inputs[]

object (SessionInput)

Erforderlich. Eingaben für die Sitzung.

Antworttext

Antwortnachricht für SessionService.RunSession.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Felder
outputs[]

object (SessionOutput)

Ausgaben für die Sitzung.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

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

Weitere Informationen finden Sie unter Authentication Overview.

IAM-Berechtigungen

Erfordert die folgende IAM-Berechtigung für die Ressource session:

  • ces.sessions.runSession

Weitere Informationen finden Sie in der IAM-Dokumentation.

SessionConfig

Die Konfiguration für die Sitzung.

JSON-Darstellung 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
Felder
session

string

Erforderlich. Die eindeutige ID der Sitzung. Format: projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

Optional. Konfiguration für die Verarbeitung des Audioeingangs.
outputAudioConfig

object (OutputAudioConfig)

Optional. Konfiguration zum Generieren der Audioausgabe.
historicalContexts[]

object (Message)

Optional. Der bisherige Kontext der Sitzung, einschließlich Nutzereingaben, Agentenantworten und anderer Nachrichten. Normalerweise verwaltet der CES-Agent die Sitzung automatisch, sodass der Client dieses Feld nicht explizit ausfüllen muss. Der Client kann die bisherigen Kontexte jedoch optional überschreiben, um den Sitzungsstart in einem bestimmten Zustand zu erzwingen.
entryAgent

string

Optional. Der Einstiegs-Agent, der die Sitzung verarbeitet. Wenn nicht angegeben, wird die Sitzung von der root agent der App verarbeitet. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Optional. Die Bereitstellung der App, die für die Sitzung verwendet werden soll. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

Optional. Die Zeitzone des Nutzers. Falls angegeben, verwendet der Agent die Zeitzone für datums- und uhrzeitbezogene Variablen. Andernfalls wird die im App.time_zone_settings angegebene Zeitzone verwendet.

Das Format ist die Zeitzone aus der IANA-Zeitzonendatenbank, z.B. „America/Los_Angeles“.
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Optional. QueryParameters, die an den Dialogflow-Remote-Agent gesendet werden sollen, wenn die Sitzungssteuerung an den Remote-Agent übertragen wird.

InputAudioConfig

Mit InputAudioConfig wird konfiguriert, wie der CES-Agent die eingehenden Audiodaten interpretieren soll.

JSON-Darstellung 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Felder
audioEncoding

enum (AudioEncoding)

Erforderlich. Die Codierung der Audioeingabedaten.
sampleRateHertz

integer

Erforderlich. Die Abtastrate (in Hertz) der Audioeingabedaten.
noiseSuppressionLevel

string

Optional. Gibt an, ob die Rauschunterdrückung für das eingegebene Audio aktiviert werden soll. Verfügbare Werte sind „low“, „moderate“, „high“ und „very_high“.

AudioEncoding

AudioEncoding gibt das Codierungsformat für Audiodaten an.

Enums
AUDIO_ENCODING_UNSPECIFIED Nicht angegebene Audiocodierung.
LINEAR16 16-Bit-Codierung mit linearer PCM-Audio.
MULAW 8-Bit-Samples zur Kompandierung von 14-Bit-Audiosamples mit G.711 PCMU/mu-law.
ALAW 8-Bit-Samples zur Kompandierung von 14-Bit-Audiosamples mit G.711 PCMU/A-law.

OutputAudioConfig

Mit OutputAudioConfig wird konfiguriert, wie der CES-Agent ausgehende Audioantworten synthetisieren soll.

JSON-Darstellung 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Felder
audioEncoding

enum (AudioEncoding)

Erforderlich. Die Codierung der Audioausgabedaten.
sampleRateHertz

integer

Erforderlich. Die Abtastrate (in Hertz) der Ausgabedaten.

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters, die an den Dialogflow-Remote-Agent gesendet werden sollen, wenn die Sitzungssteuerung an den Remote-Agent übertragen wird.

JSON-Darstellung 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
Felder
webhookHeaders

map (key: string, value: string)

Optional. Die HTTP-Header, die als „webhookHeaders“ in QueryParameters gesendet werden sollen.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
payload

object (Struct format)

Optional. Die Nutzlast, die in QueryParameters gesendet werden soll.
endUserMetadata

object (Struct format)

Optional. Die Metadaten zu Endnutzern, die in QueryParameters gesendet werden sollen.

SessionInput

Eingabe für die Sitzung.

JSON-Darstellung 
{
  "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.
}
Felder
willContinue

boolean

Optional. Ein Flag, das angibt, ob die aktuelle Nachricht ein Fragment einer größeren Eingabe in der bidirektionalen Streaming-Sitzung ist.

Wenn true festgelegt ist, verschiebt der Agent die Verarbeitung, bis er eine nachfolgende Nachricht mit willContinue = false empfängt oder das System einen Endpunkt in der Audioeingabe erkennt.

HINWEIS: Dieses Feld gilt nicht für Audio- und DTMF-Eingaben, da diese immer automatisch auf Grundlage des Endpunkt-Signals verarbeitet werden.
Union-Feld input_type. Der Typ der Eingabe. Für input_type ist nur einer der folgenden Werte zulässig:
text

string

Optional. Textdaten vom Endnutzer.
dtmf

string

Optional. DTMF-Ziffern vom Endnutzer.
audio

string (bytes format)

Optional. Audiodaten des Endnutzers.

Ein base64-codierter String.
toolResponses

object (ToolResponses)

Optional. Ausführungsergebnisse für die Tool-Aufrufe vom Client.
image

object (Image)

Optional. Bilddaten vom Endnutzer.
blob

object (Blob)

Optional. Blob-Daten vom Endnutzer.
variables

object (Struct format)

Optional. Kontextvariablen für die Sitzung, nach Namen sortiert. Der CES-Kundenservicemitarbeiter verwendet nur Variablen, die in der App deklariert sind.

Nicht erkannte Variablen werden weiterhin als zusätzliche Sitzungsparameter an den [Dialogflow-Agent][Agent.RemoteDialogflowAgent] gesendet.
event

object (Event)

Optional. Eingabe von Ereignissen

ToolResponses

Ausführungsergebnisse für die angeforderten Tool-Aufrufe vom Client.

JSON-Darstellung 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Felder
toolResponses[]

object (ToolResponse)

Optional. Die Liste der Ergebnisse der Tool-Ausführung.

Ereignis

Eingabe von Ereignissen

JSON-Darstellung 
{
  "event": string
}
Felder
event

string

Erforderlich. Der Name des Ereignisses.

SessionOutput

Ausgabe für die Sitzung.

JSON-Darstellung 
{
  "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.
}
Felder
turnIndex

integer

Gibt die fortlaufende Nummer des Gesprächsbeitrags an, zu dem diese Ausgabe gehört, beginnend mit 1.
turnCompleted

boolean

Wenn „true“ angegeben ist, hat der CES-Agent das Ende des aktuellen Gesprächsabschnitts erkannt und gibt für diesen Abschnitt keine weiteren Ausgaben aus.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Optional. Diagnoseinformationen enthalten Ausführungsdetails während der Verarbeitung der Eingabe. Wird nur im letzten SessionOutput (mit turnCompleted=true) für jede Runde ausgefüllt.
Union-Feld output_type. Der Typ der Ausgabe. Für output_type ist nur einer der folgenden Werte zulässig:
text

string

Ausgabetext des CES-Agents.
audio

string (bytes format)

Audioausgabe des CES-Agents.

Ein base64-codierter String.
toolCalls

object (ToolCalls)

Bitte den Kunden, die Tools auszuführen.
citations

object (Citations)

Zitationen, die die Quellinformationen für den vom Agenten generierten Text enthalten.
googleSearchSuggestions

object (GoogleSearchSuggestions)

Die Vorschläge, die von der Google Suche als Ergebnis des Aufrufs von GoogleSearchTool zurückgegeben werden.
endSession

object (EndSession)

Gibt an, dass die Sitzung beendet wurde.
payload

object (Struct format)

Benutzerdefinierte Nutzlast mit strukturierter Ausgabe des CES-Agents.

ToolCalls

Aufforderung an den Client, die Tools auszuführen und die Ausführungsergebnisse zurückzugeben, bevor die Sitzung fortgesetzt wird.

JSON-Darstellung 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Felder
toolCalls[]

object (ToolCall)

Optional. Die Liste der auszuführenden Tool-Aufrufe.

Zitationen

Zitationen, die mit der Antwort des Agents verknüpft sind.

JSON-Darstellung 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Felder
citedChunks[]

object (Citations.CitedChunk)

Liste der zitierten Informationen.

Citations.CitedChunk

Zitierte Information.

JSON-Darstellung 
{
  "uri": string,
  "title": string,
  "text": string
}
Felder
uri

string

URI, der für die Quellenangabe verwendet wird.
title

string

Titel des zitierten Dokuments.
text

string

Text, der für die Quellenangabe verwendet wird.

GoogleSearchSuggestions

Suchvorschläge von Google Search Tool.

JSON-Darstellung 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Felder
htmls[]

string

Konforme HTML- und CSS-Stile für Suchvorschläge. Der bereitgestellte HTML- und CSS-Code passt sich automatisch an Ihre Geräteeinstellungen an und wird entweder im hellen oder im dunklen Modus angezeigt, je nachdem, was mit @media(prefers-color-scheme) angegeben ist.
webSearchQueries[]

object (WebSearchQuery)

Liste der Anfragen, die für die Google-Suche verwendet wurden, sowie der Suchergebnis-URIs, aus denen die Suchvorschläge bestehen.

WebSearchQuery

Stellt eine einzelne Websuchanfrage und den zugehörigen Such-URI dar.

JSON-Darstellung 
{
  "query": string,
  "uri": string
}
Felder
query

string

Der Text der Suchanfrage.
uri

string

Die URI der Google-Suchergebnisseite für die Anfrage.

EndSession

Gibt an, dass die Sitzung beendet wurde, entweder aufgrund eines erfolgreichen Abschlusses (z.B. wenn der Nutzer „Tschüss!“ sagt) ) oder eine Eskalierung an einen Kundenservicemitarbeiter.

Der Kundenservicemitarbeiter verarbeitet keine weiteren Eingaben mehr, nachdem die Sitzung beendet wurde. Der Client sollte die Verbindung halb schließen und trennen, nachdem er alle verbleibenden Antworten vom Kundenservicemitarbeiter erhalten hat.

JSON-Darstellung 
{
  "metadata": {
    object
  }
}
Felder
metadata

object (Struct format)

Optional. Enthält zusätzliche Informationen zum Signal für das Ende der Sitzung, z. B. den Grund für das Beenden der Sitzung.

SessionOutput.DiagnosticInfo

Enthält Ausführungsdetails während der Verarbeitung.

JSON-Darstellung 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Felder
messages[]

object (Message)

Liste der Nachrichten, die während der Verarbeitung aufgetreten sind.
rootSpan

object (Span)

Ein Trace der gesamten Anfrageverarbeitung, dargestellt als Stamm-Span. Dieser Bereich kann verschachtelte untergeordnete Bereiche für bestimmte Vorgänge enthalten.