Method: projects.locations.apps.sessions.runSession

Memulai interaksi satu giliran dengan agen CES dalam sesi.

Permintaan HTTP

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

URL menggunakan sintaks gRPC Transcoding.

Parameter jalur

Parameter
config.session

string

Wajib. ID unik sesi. Format: projects/{project}/locations/{location}/apps/{app}/sessions/{session}

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi 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)
    }
  ]
}
Kolom
config.inputAudioConfig

object (InputAudioConfig)

Opsional. Konfigurasi untuk memproses audio input.
config.outputAudioConfig

object (OutputAudioConfig)

Opsional. Konfigurasi untuk membuat audio output.
config.historicalContexts[]

object (Message)

Opsional. Konteks historis sesi, termasuk input pengguna, respons agen, dan pesan lainnya. Biasanya, agen CES akan mengelola sesi secara otomatis sehingga klien tidak perlu mengisi kolom ini secara eksplisit. Namun, klien dapat secara opsional mengganti konteks historis untuk memulai sesi dari status tertentu.
config.entryAgent

string

Opsional. Agen entri untuk menangani sesi. Jika tidak ditentukan, sesi akan ditangani oleh root agent aplikasi. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

Opsional. Deployment aplikasi yang akan digunakan untuk sesi. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

Opsional. Zona waktu pengguna. Jika diberikan, agen akan menggunakan zona waktu untuk variabel terkait tanggal dan waktu. Jika tidak, agen akan menggunakan zona waktu yang ditentukan di App.time_zone_settings.

Formatnya adalah zona waktu Database Zona Waktu IANA, misalnya "America/Los_Angeles".
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Opsional. QueryParameters untuk dikirim ke agen Dialogflow jarak jauh saat kontrol sesi ditransfer ke agen jarak jauh.
inputs[]

object (SessionInput)

Wajib. Input untuk sesi.

Isi respons

Pesan respons untuk SessionService.RunSession.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
Kolom
outputs[]

object (SessionOutput)

Output untuk sesi.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

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

Untuk mengetahui informasi selengkapnya, lihat Authentication Overview.

Izin IAM

Memerlukan izin IAM berikut pada resource session:

  • ces.sessions.runSession

Untuk mengetahui informasi selengkapnya, lihat dokumentasi IAM.

SessionConfig

Konfigurasi untuk sesi.

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

string

Wajib. ID unik sesi. Format: projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

Opsional. Konfigurasi untuk memproses audio input.
outputAudioConfig

object (OutputAudioConfig)

Opsional. Konfigurasi untuk membuat audio output.
historicalContexts[]

object (Message)

Opsional. Konteks historis sesi, termasuk input pengguna, respons agen, dan pesan lainnya. Biasanya, agen CES akan mengelola sesi secara otomatis sehingga klien tidak perlu mengisi kolom ini secara eksplisit. Namun, klien dapat secara opsional mengganti konteks historis untuk memulai sesi dari status tertentu.
entryAgent

string

Opsional. Agen entri untuk menangani sesi. Jika tidak ditentukan, sesi akan ditangani oleh root agent aplikasi. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

Opsional. Deployment aplikasi yang akan digunakan untuk sesi. Format: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

Opsional. Zona waktu pengguna. Jika diberikan, agen akan menggunakan zona waktu untuk variabel terkait tanggal dan waktu. Jika tidak, agen akan menggunakan zona waktu yang ditentukan di App.time_zone_settings.

Formatnya adalah zona waktu Database Zona Waktu IANA, misalnya "America/Los_Angeles".
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

Opsional. QueryParameters untuk dikirim ke agen Dialogflow jarak jauh saat kontrol sesi ditransfer ke agen jarak jauh.

InputAudioConfig

InputAudioConfig mengonfigurasi cara agen CES menafsirkan data audio yang masuk.

Representasi JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
Kolom
audioEncoding

enum (AudioEncoding)

Wajib. Encoding data audio input.
sampleRateHertz

integer

Wajib. Frekuensi sampel (dalam Hertz) data audio input.
noiseSuppressionLevel

string

Opsional. Apakah akan mengaktifkan peredam bising pada audio input. Nilai yang tersedia adalah "low", "moderate", "high", "very_high".

AudioEncoding

AudioEncoding menentukan format encoding untuk data audio.

Enum
AUDIO_ENCODING_UNSPECIFIED Encoding audio tidak ditentukan.
LINEAR16 Encoding audio PCM linear 16-bit.
MULAW Sampel 8-bit yang memadatkan sampel audio 14-bit menggunakan G.711 PCMU/mu-law.
ALAW Sampel 8-bit yang memadatkan sampel audio 14-bit menggunakan G.711 PCMU/A-law.

OutputAudioConfig

OutputAudioConfig mengonfigurasi cara agen CES harus menyintesis respons audio keluar.

Representasi JSON 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
Kolom
audioEncoding

enum (AudioEncoding)

Wajib. Encoding data audio output.
sampleRateHertz

integer

Wajib. Frekuensi sampel (dalam Hertz) data audio output.

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters untuk dikirim ke agen Dialogflow jarak jauh saat kontrol sesi ditransfer ke agen jarak jauh.

Representasi JSON 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
Kolom
webhookHeaders

map (key: string, value: string)

Opsional. Header HTTP yang akan dikirim sebagai webhookHeaders di QueryParameters.

Objek yang berisi daftar pasangan "key": value. Contoh: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
payload

object (Struct format)

Opsional. Payload yang akan dikirim dalam QueryParameters.
endUserMetadata

object (Struct format)

Opsional. Metadata pengguna akhir yang akan dikirim dalam QueryParameters.

SessionInput

Input untuk sesi.

Representasi 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.
}
Kolom
willContinue

boolean

Opsional. Flag untuk menunjukkan apakah pesan saat ini adalah fragmen input yang lebih besar dalam sesi streaming bidi.

Jika disetel ke true, agen akan menunda pemrosesan hingga menerima pesan berikutnya dengan willContinue adalah false, atau hingga sistem mendeteksi titik akhir dalam input audio.

CATATAN: Kolom ini tidak berlaku untuk input audio dan DTMF, karena input tersebut selalu diproses secara otomatis berdasarkan sinyal pengakhiran.
Kolom union input_type. Jenis input. input_type hanya ada berupa salah satu diantara berikut:
text

string

Opsional. Data teks dari pengguna akhir.
dtmf

string

Opsional. Digit DTMF dari pengguna akhir.
audio

string (bytes format)

Opsional. Data audio dari pengguna akhir.

String berenkode base64.
toolResponses

object (ToolResponses)

Opsional. Hasil eksekusi untuk panggilan alat dari klien.
image

object (Image)

Opsional. Data gambar dari pengguna akhir.
blob

object (Blob)

Opsional. Data blob dari pengguna akhir.
variables

object (Struct format)

Opsional. Variabel kontekstual untuk sesi, yang dikelompokkan berdasarkan nama. Hanya variabel yang dideklarasikan di aplikasi yang akan digunakan oleh agen CES.

Variabel yang tidak dikenali akan tetap dikirim ke [agen Dialogflow][Agent.RemoteDialogflowAgent] sebagai parameter sesi tambahan.
event

object (Event)

Opsional. Input acara.

ToolResponses

Hasil eksekusi untuk panggilan alat yang diminta dari klien.

Representasi JSON 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
Kolom
toolResponses[]

object (ToolResponse)

Opsional. Daftar hasil eksekusi alat.

Acara

Input acara.

Representasi JSON 
{
  "event": string
}
Kolom
event

string

Wajib. Nama acara.

SessionOutput

Output untuk sesi.

Representasi 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.
}
Kolom
turnIndex

integer

Menunjukkan urutan percakapan yang berurutan yang menjadi bagian dari output ini, dimulai dari 1.
turnCompleted

boolean

Jika benar, agen CES telah mendeteksi akhir giliran percakapan saat ini dan tidak akan memberikan output lebih lanjut untuk giliran ini.
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

Opsional. Informasi diagnostik berisi detail eksekusi selama pemrosesan input. Hanya diisi di SessionOutput terakhir (dengan turnCompleted=true) untuk setiap giliran.
Kolom union output_type. Jenis output. output_type hanya ada berupa salah satu diantara berikut:
text

string

Teks output dari agen CES.
audio

string (bytes format)

Menghasilkan audio dari agen CES.

String berenkode base64.
toolCalls

object (ToolCalls)

Meminta klien untuk menjalankan alat.
citations

object (Citations)

Kutipan yang memberikan informasi sumber untuk teks yang dihasilkan agen.
googleSearchSuggestions

object (GoogleSearchSuggestions)

Saran yang ditampilkan dari Google Penelusuran sebagai hasil dari pemanggilan GoogleSearchTool.
endSession

object (EndSession)

Menunjukkan bahwa sesi telah berakhir.
payload

object (Struct format)

Payload kustom dengan output terstruktur dari agen CES.

ToolCalls

Permintaan agar klien menjalankan alat dan menampilkan hasil eksekusi sebelum melanjutkan sesi.

Representasi JSON 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
Kolom
toolCalls[]

object (ToolCall)

Opsional. Daftar panggilan alat yang akan dieksekusi.

Kutipan

Kutipan yang terkait dengan respons agen.

Representasi JSON 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
Kolom
citedChunks[]

object (Citations.CitedChunk)

Daftar informasi yang dikutip.

Citations.CitedChunk

Bagian informasi yang dikutip.

Representasi JSON 
{
  "uri": string,
  "title": string,
  "text": string
}
Kolom
uri

string

URI yang digunakan untuk kutipan.
title

string

Judul dokumen yang dikutip.
text

string

Teks yang digunakan untuk kutipan.

GoogleSearchSuggestions

Saran penelusuran dari Google Search Tool.

Representasi JSON 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
Kolom
htmls[]

string

Penataan gaya HTML dan CSS yang sesuai untuk saran penelusuran. HTML dan CSS yang disediakan akan otomatis menyesuaikan setelan perangkat Anda, ditampilkan dalam mode terang atau gelap yang ditunjukkan oleh @media(prefers-color-scheme).
webSearchQueries[]

object (WebSearchQuery)

Daftar kueri yang digunakan untuk melakukan penelusuran Google beserta URI hasil penelusuran yang membentuk saran penelusuran.

WebSearchQuery

Mewakili satu kueri penelusuran web dan URI penelusuran terkaitnya.

Representasi JSON 
{
  "query": string,
  "uri": string
}
Kolom
query

string

Teks kueri penelusuran.
uri

string

URI ke halaman hasil Google Penelusuran untuk kueri.

EndSession

Menunjukkan bahwa sesi telah berakhir, karena berhasil diselesaikan (misalnya, pengguna mengatakan "Selamat tinggal" ) atau eskalasi agen.

Agen tidak akan memproses input lebih lanjut setelah sesi dihentikan dan klien harus menutup sebagian dan memutuskan koneksi setelah menerima semua respons yang tersisa dari agen.

Representasi JSON 
{
  "metadata": {
    object
  }
}
Kolom
metadata

object (Struct format)

Opsional. Memberikan informasi tambahan tentang sinyal akhir sesi, seperti alasan mengakhiri sesi.

SessionOutput.DiagnosticInfo

Berisi detail eksekusi selama pemrosesan.

Representasi JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
Kolom
messages[]

object (Message)

Daftar pesan yang terjadi selama pemrosesan.
rootSpan

object (Span)

Trace seluruh pemrosesan permintaan, yang ditampilkan sebagai rentang root. Rentang ini dapat berisi rentang turunan bertingkat untuk operasi tertentu.