Method: projects.locations.apps.sessions.runSession

Lance une interaction unique avec l'agent CES au cours d'une session.

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
config.session

string

Obligatoire. Identifiant unique de la session. Format : projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation 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)
    }
  ]
}
Champs
config.inputAudioConfig

object (InputAudioConfig)

Facultatif. Configuration pour le traitement de l'entrée audio.
config.outputAudioConfig

object (OutputAudioConfig)

Facultatif. Configuration pour générer le contenu audio de sortie.
config.historicalContexts[]

object (Message)

Facultatif. Contexte historique de la session, y compris les entrées utilisateur, les réponses de l'agent et les autres messages. En règle générale, l'agent CES gère la session automatiquement. Le client n'a donc pas besoin de renseigner explicitement ce champ. Toutefois, le client peut éventuellement remplacer les contextes historiques pour forcer le démarrage de la session à partir d'un certain état.
config.entryAgent

string

Facultatif. Agent d'entrée chargé de gérer la session. Si aucune valeur n'est spécifiée, la session sera gérée par le root agent de l'application. Format : projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Facultatif. Déploiement de l'application à utiliser pour la session. Format : projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Facultatif. Fuseau horaire de l'utilisateur. Si ce champ est fourni, l'agent utilise le fuseau horaire pour les variables liées à la date et à l'heure. Sinon, l'agent utilisera le fuseau horaire spécifié dans App.time_zone_settings.

Le format correspond au fuseau horaire de la base de données des fuseaux horaires IANA (par exemple, "America/Los_Angeles").
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Facultatif. QueryParameters à envoyer à l'agent Dialogflow distant lorsque le contrôle de la session est transféré à l'agent distant.
inputs[]

object (SessionInput)

Obligatoire. Entrées de la session.

Corps de la réponse

Message de réponse pour SessionService.RunSession.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Champs
outputs[]

object (SessionOutput)

Résultats de la session.

Niveaux d'accès des autorisations

Nécessite l'un des niveaux d'accès OAuth suivants :

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

Pour plus d'informations, consultez la page Authentication Overview.

Autorisations IAM

Nécessite l'autorisation IAM suivante sur la ressource session :

  • ces.sessions.runSession

Pour en savoir plus, consultez la documentation IAM.

SessionConfig

Configuration de la session.

Représentation JSON 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
Champs
session

string

Obligatoire. Identifiant unique de la session. Format : projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

Facultatif. Configuration pour le traitement de l'entrée audio.
outputAudioConfig

object (OutputAudioConfig)

Facultatif. Configuration pour générer le contenu audio de sortie.
historicalContexts[]

object (Message)

Facultatif. Contexte historique de la session, y compris les entrées utilisateur, les réponses de l'agent et les autres messages. En règle générale, l'agent CES gère la session automatiquement. Le client n'a donc pas besoin de renseigner explicitement ce champ. Toutefois, le client peut éventuellement remplacer les contextes historiques pour forcer le démarrage de la session à partir d'un certain état.
entryAgent

string

Facultatif. Agent d'entrée chargé de gérer la session. Si aucune valeur n'est spécifiée, la session sera gérée par le root agent de l'application. Format : projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Facultatif. Déploiement de l'application à utiliser pour la session. Format : projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

Facultatif. Fuseau horaire de l'utilisateur. Si ce champ est fourni, l'agent utilise le fuseau horaire pour les variables liées à la date et à l'heure. Sinon, l'agent utilisera le fuseau horaire spécifié dans App.time_zone_settings.

Le format correspond au fuseau horaire de la base de données des fuseaux horaires IANA (par exemple, "America/Los_Angeles").
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Facultatif. QueryParameters à envoyer à l'agent Dialogflow distant lorsque le contrôle de la session est transféré à l'agent distant.

InputAudioConfig

InputAudioConfig configure la façon dont l'agent CES doit interpréter les données audio entrantes.

Représentation JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Champs
audioEncoding

enum (AudioEncoding)

Obligatoire. Encodage des données audio d'entrée.
sampleRateHertz

integer

Obligatoire. Taux d'échantillonnage (en hertz) des données audio d'entrée.
noiseSuppressionLevel

string

Facultatif. Indique si la suppression du bruit doit être activée pour l'entrée audio. Les valeurs disponibles sont "low", "moderate", "high" et "very_high".

AudioEncoding

AudioEncoding spécifie le format d'encodage des données audio.

Enums
AUDIO_ENCODING_UNSPECIFIED Encodage audio non spécifié.
LINEAR16 Encodage audio PCM linéaire 16 bits
MULAW Échantillons de 8 bits compressant des échantillons audio 14 bits qui utilisent la norme G.711 PCMU/MULAW.
ALAW Échantillons de 8 bits compressant des échantillons audio 14 bits qui utilisent la norme G.711 PCMU/A-law.

OutputAudioConfig

OutputAudioConfig configure la façon dont l'agent CES doit synthétiser les réponses audio sortantes.

Représentation JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Champs
audioEncoding

enum (AudioEncoding)

Obligatoire. Encodage des données audio de sortie.
sampleRateHertz

integer

Obligatoire. Taux d'échantillonnage (en hertz) des données audio de sortie.

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters à envoyer à l'agent Dialogflow distant lorsque le contrôle de la session est transféré à l'agent distant.

Représentation JSON 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
Champs
webhookHeaders

map (key: string, value: string)

Facultatif. En-têtes HTTP à envoyer en tant que webhookHeaders dans QueryParameters.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.
payload

object (Struct format)

Facultatif. Charge utile à envoyer dans QueryParameters.
endUserMetadata

object (Struct format)

Facultatif. Métadonnées de l'utilisateur final à envoyer dans QueryParameters.

SessionInput

Entrée pour la session.

Représentation 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.
}
Champs
willContinue

boolean

Facultatif. Indicateur permettant de déterminer si le message actuel est un fragment d'une entrée plus grande dans la session de streaming bidirectionnel.

Si la valeur est définie sur true, l'agent diffère le traitement jusqu'à ce qu'il reçoive un message ultérieur où willContinue est défini sur false, ou jusqu'à ce que le système détecte un point de terminaison dans l'entrée audio.

REMARQUE : Ce champ ne s'applique pas aux entrées audio et DTMF, car elles sont toujours traitées automatiquement en fonction du signal de fin.
Champ d'union input_type. Type d'entrée. input_type ne peut être qu'un des éléments suivants :
text

string

Facultatif. Données textuelles de l'utilisateur final.
dtmf

string

Facultatif. Chiffres DTMF de l'utilisateur final.
audio

string (bytes format)

Facultatif. Données audio de l'utilisateur final.

Chaîne encodée en base64.
toolResponses

object (ToolResponses)

Facultatif. Résultats d'exécution des appels d'outils du client.
image

object (Image)

Facultatif. Données d'image de l'utilisateur final.
blob

object (Blob)

Facultatif. Données blob de l'utilisateur final.
variables

object (Struct format)

Facultatif. Variables contextuelles pour la session, identifiées par leur nom. L'agent CES n'utilisera que les variables déclarées dans l'application.

Les variables non reconnues seront toujours envoyées à l'[agent Dialogflow][Agent.RemoteDialogflowAgent] en tant que paramètres de session supplémentaires.
event

object (Event)

Facultatif. Saisie d'événement.

ToolResponses

Résultats d'exécution des appels d'outils demandés par le client.

Représentation JSON 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Champs
toolResponses[]

object (ToolResponse)

Facultatif. Liste des résultats d'exécution de l'outil.

Événement

Saisie d'événement.

Représentation JSON 
{
  "event": string
}
Champs
event

string

Obligatoire. Nom de l'événement.

SessionOutput

Sortie de la session.

Représentation 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.
}
Champs
turnIndex

integer

Indique l'ordre séquentiel du tour de conversation auquel appartient cette sortie, en commençant par 1.
turnCompleted

boolean

Si la valeur est "true", l'agent CES a détecté la fin du tour de conversation en cours et ne fournira plus de résultat pour ce tour.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Facultatif. Les informations de diagnostic contiennent des détails sur l'exécution lors du traitement de l'entrée. N'est renseigné que dans le dernier SessionOutput (avec turnCompleted=true) pour chaque tour.
Champ d'union output_type. Type de sortie. output_type ne peut être qu'un des éléments suivants :
text

string

Texte de sortie de l'agent CES.
audio

string (bytes format)

Sortie audio de l'agent CES.

Chaîne encodée en base64.
toolCalls

object (ToolCalls)

Demande au client d'exécuter les outils.
citations

object (Citations)

Citations qui fournissent des informations sur la source du texte généré par l'agent.
googleSearchSuggestions

object (GoogleSearchSuggestions)

Suggestions renvoyées par la recherche Google à la suite de l'appel de GoogleSearchTool.
endSession

object (EndSession)

Indique que la session est terminée.
payload

object (Struct format)

Charge utile personnalisée avec une sortie structurée de l'agent CES.

ToolCalls

Demande au client d'exécuter les outils et de renvoyer les résultats de l'exécution avant de poursuivre la session.

Représentation JSON 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Champs
toolCalls[]

object (ToolCall)

Facultatif. Liste des appels d'outils à exécuter.

Citations

Citations associées à la réponse de l'agent.

Représentation JSON 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Champs
citedChunks[]

object (Citations.CitedChunk)

Liste des informations citées.

Citations.CitedChunk

Élément d'information cité.

Représentation JSON 
{
  "uri": string,
  "title": string,
  "text": string
}
Champs
uri

string

URI utilisé pour la citation.
title

string

Titre du document cité.
text

string

Texte utilisé pour la citation.

GoogleSearchSuggestions

Suggestions de recherche de Google Search Tool.

Représentation JSON 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Champs
htmls[]

string

Style HTML et CSS conforme pour les suggestions de recherche. Les codes HTML et CSS fournis s'adaptent automatiquement aux paramètres de votre appareil et s'affichent en mode clair ou sombre, comme indiqué par @media(prefers-color-scheme).
webSearchQueries[]

object (WebSearchQuery)

Liste des requêtes utilisées pour effectuer la recherche Google, ainsi que les URI des résultats de recherche qui constituent les suggestions de recherche.

WebSearchQuery

Représente une requête de recherche Web unique et son URI de recherche associé.

Représentation JSON 
{
  "query": string,
  "uri": string
}
Champs
query

string

Texte de la requête de recherche.
uri

string

URI de la page de résultats de recherche Google pour la requête.

EndSession

Indique que la session s'est terminée, soit parce qu'elle a été menée à bien (par exemple, l'utilisateur dit "Au revoir !" ) ou une escalade d'agent.

L'agent ne traitera plus aucune entrée une fois la session terminée. Le client doit fermer à moitié la connexion et se déconnecter après avoir reçu toutes les réponses restantes de l'agent.

Représentation JSON 
{
  "metadata": {
    object
  }
}
Champs
metadata

object (Struct format)

Facultatif. Fournit des informations supplémentaires sur le signal de fin de session, comme la raison de la fin de la session.

SessionOutput.DiagnosticInfo

Contient des informations sur l'exécution pendant le traitement.

Représentation JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Champs
messages[]

object (Message)

Liste des messages qui se sont affichés lors du traitement.
rootSpan

object (Span)

Trace du traitement complet de la requête, représentée sous forme de portée racine. Cette étendue peut contenir des étendues enfants imbriquées pour des opérations spécifiques.