Method: projects.locations.apps.sessions.runSession

Memulai interaksi satu giliran dengan agen CES dalam sesi.

Permintaan HTTP

POST https://ces.googleapis.com/v1beta/{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,
    "useToolFakes": boolean,
    "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.useToolFakes

boolean

Opsional. Apakah akan menggunakan tiruan alat untuk sesi. Jika kolom ini disetel, agen akan mencoba menggunakan tiruan alat, bukan memanggil alat yang sebenarnya.
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,
  "useToolFakes": boolean,
  "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".
useToolFakes

boolean

Opsional. Apakah akan menggunakan tiruan alat untuk sesi. Jika kolom ini disetel, agen akan mencoba menggunakan tiruan alat, bukan memanggil alat yang sebenarnya.
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

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

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.

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.