Alat playbook

Dengan menggunakan alat, Anda dapat menghubungkan playbook ke sistem eksternal. Sistem ini dapat menambah pengetahuan tentang playbook dan memberdayakan mereka untuk menjalankan tugas yang kompleks secara efisien.

Anda dapat menggunakan alat bawaan atau membuat alat yang disesuaikan untuk memenuhi persyaratan Anda.

Pengujian alat

Setelah membuat alat, Anda dapat menggunakan fitur pengujian alat untuk memverifikasi bahwa alat tersebut berfungsi. Saat melihat alat, klik tombol Test di atas panel alat. Tindakan ini akan membuka alat untuk input di simulator. Berikan input alat, lalu klik Lihat Output untuk memverifikasi output alat yang benar.

Anda juga dapat menggunakan fitur pengujian alat saat menambahkan alat ke contoh.

Alat bawaan

Alat bawaan dihosting oleh Google. Anda dapat mengaktifkan alat ini di agen tanpa memerlukan konfigurasi manual.

Alat bawaan yang didukung adalah:

  • Code Interpreter: Alat pihak pertama Google yang menggabungkan kemampuan pembuatan kode dan eksekusi kode serta memungkinkan pengguna melakukan berbagai tugas, termasuk: analisis data, visualisasi data, pemrosesan teks, memecahkan persamaan, atau masalah pengoptimalan.

Agen Anda dioptimalkan untuk menentukan cara dan waktu alat ini harus dipanggil, tetapi Anda dapat memberikan contoh tambahan agar sesuai dengan kasus penggunaan Anda.

Contoh harus memiliki skema seperti berikut:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

Alat OpenAPI

Agen dapat terhubung ke API eksternal menggunakan alat OpenAPI dengan menyediakan skema OpenAPI. Secara default, agen akan memanggil API atas nama Anda. Atau, Anda dapat menjalankan alat OpenAPI di sisi klien.

Contoh skema:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

Anda dapat secara opsional menggunakan referensi skema internal @dialogflow/sessionId sebagai jenis skema parameter. Dengan jenis skema parameter ini, ID sesi Dialogflow untuk percakapan saat ini akan diberikan sebagai nilai parameter. Contoh:

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

Batasan alat OpenAPI

Batasan berikut berlaku:

  • Jenis parameter yang didukung adalah path, query, header. Jenis parameter cookie belum didukung.
  • Parameter yang ditentukan oleh skema OpenAPI mendukung jenis data berikut: string, number, integer, boolean, array. Jenis object belum didukung.
  • Saat ini, Anda tidak dapat menentukan parameter kueri di editor contoh konsol.
  • Isi permintaan dan respons harus kosong atau JSON.

Autentikasi API alat OpenAPI

Opsi autentikasi berikut didukung saat memanggil API eksternal:

  • Autentikasi Agen Layanan Dialogflow
    • Dialogflow dapat membuat token ID atau token akses menggunakan Dialogflow Service Agent. Token ditambahkan di header HTTP otorisasi saat Dialogflow memanggil API eksternal.
    • Token ID dapat digunakan untuk mengakses fungsi Cloud Run dan layanan Cloud Run setelah Anda memberikan peran roles/cloudfunctions.invoker dan roles/run.invoker ke service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Jika fungsi Cloud Run dan layanan Cloud Run berada di project resource yang sama, Anda tidak memerlukan izin IAM tambahan untuk memanggilnya.
    • Token akses dapat digunakan untuk mengakses Google Cloud API lain setelah Anda memberikan peran yang diperlukan ke service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.

  • Autentikasi Akun Layanan

    • Akun layanan dapat digunakan untuk mengautentikasi permintaan alat ke Google API mana pun yang mendukungnya. Karena akun layanan adalah akun utama, akun tersebut dapat mengakses resource dalam project Anda dengan memberinya peran, seperti yang Anda lakukan untuk akun utama lainnya. Email akun layanan akan digunakan untuk membuat token akses yang akan dikirim dalam header Authorization permintaan alat.

    • Untuk menggunakan fitur ini, izin berikut diperlukan:

      • roles/iam.serviceAccountUser kepada pengguna yang membuat atau memperbarui alat untuk menggunakan autentikasi akun layanan.
      • roles/iam.serviceAccountTokenCreator ke Dialogflow Service Agent.

    • Jika Anda mencoba menggunakan akun layanan di beberapa project, pastikan kebijakan organisasi Anda mendukungnya. Kedua izin tersebut harus diberikan di project yang berisi akun layanan.

  • Kunci API

    • Anda dapat mengonfigurasi autentikasi kunci API dengan memberikan nama kunci, lokasi permintaan (header atau string kueri), dan kunci API sehingga Dialogflow meneruskan kunci API dalam permintaan.
    • Sebaiknya berikan kunci API Anda menggunakan Secret Manager.

  • OAuth

    • Alur Kredensial Klien OAuth didukung untuk autentikasi server ke server:

      • Alur ini dapat digunakan jika konsol Builder Agen adalah pemilik resource dan tidak diperlukan otorisasi pengguna akhir.
      • Client ID, Client Secret, dan endpoint Token dari penyedia OAuth perlu dikonfigurasi di Dialogflow.
      • Dialogflow menukar token akses OAuth dari penyedia OAuth dan meneruskannya di header autentikasi permintaan.

    • Untuk alur OAuth lainnya yang memerlukan otorisasi pengguna akhir seperti Alur Kode Otorisasi dan alur PKCE:

      1. Anda harus menerapkan UI login Anda sendiri dan mendapatkan token akses di sisi klien.

      2. Kemudian Anda dapat:

        a. Gunakan opsi autentikasi Token Pembawa untuk meneruskan token ke Alat OpenAPI. Dialogflow akan menyertakan token ini di header otorisasi saat memanggil alat.

        b. Gunakan alat Fungsi untuk memanggil alat sendiri di sisi klien dan meneruskan hasil panggilan alat ke Dialogflow.

  • Token Pembawa

    • Anda dapat mengonfigurasi autentikasi Bearer untuk meneruskan token Bearer secara dinamis dari klien. Token ini disertakan dalam header autentikasi permintaan.
    • Saat menyiapkan autentikasi alat, Anda dapat menetapkan parameter sesi untuk bertindak sebagai token Bearer. Misalnya, gunakan $session.params.<parameter-name-for-token> untuk menentukan token.
    • Saat runtime, tetapkan token Bearer ke parameter sesi:
    DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}
    • Jika Anda perlu mengonfigurasi token statis, bukan mengambil token dari parameter sesi, sebaiknya berikan token menggunakan Secret Manager.

  • Autentikasi TLS bersama

    • Lihat dokumentasi Autentikasi TLS bersama.
    • Sertifikat klien kustom didukung. Anda dapat menyiapkan sertifikat klien di tingkat agen pada tab keamanan di setelan agen. Sertifikat (format PEM) dan kunci pribadi (format PEM) adalah kolom wajib. Setelah ditetapkan, sertifikat klien ini akan digunakan selama TLS bersama untuk semua alat dan webhook.

  • Sertifikat CA kustom

Autentikasi Secret Manager

Jika menggunakan OAuth, kunci API, atau token Bearer, Anda dapat menyimpan kredensial sebagai secret menggunakan Secret Manager. Berikut adalah langkah-langkah yang diperlukan untuk mengautentikasi alat Anda menggunakan secret:

  1. Buat secret jika Anda belum memilikinya.
  2. Berikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret baru kepada Dialogflow Service Agent.
  3. Salin kredensial Anda ke papan klip.
  4. Tambahkan versi secret baru ke secret Anda. Tempelkan kredensial Anda sebagai nilai secret.
    • Hapus karakter baris baru di akhir.
  5. Salin nama versi rahasia yang baru saja Anda tambahkan. Format namanya adalah projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
  6. Buka layar edit alat, lalu:
    • Jika Anda menggunakan OAuth, pilih OAuth sebagai Authentication type, lalu klik Secret version di bagian Client secret dan tempel nama versi secret ke kotak input Secret version.
    • Jika Anda menggunakan kunci API, pilih API key sebagai Authentication type, lalu klik Secret version di bagian API key. Tempelkan nama versi secret ke kotak input Secret version.
    • Jika Anda menggunakan token Pembawa, pilih Token pembawa sebagai Jenis autentikasi, lalu klik Versi rahasia di bagian Token pembawa. Tempelkan nama versi secret ke kotak input Secret version.
  7. Klik Simpan.

Akses jaringan pribadi alat OpenAPI

Alat OpenAPI terintegrasi dengan akses jaringan pribadi Service Directory, sehingga dapat terhubung ke target API di dalam jaringan VPC Anda. Tindakan ini akan menjaga traffic tetap berada dalam jaringan Google Cloud dan menerapkan IAM serta Kontrol Layanan VPC.

Untuk menyiapkan alat OpenAPI yang menargetkan jaringan pribadi:

  1. Ikuti Konfigurasi jaringan pribadi Service Directory untuk mengonfigurasi jaringan VPC dan endpoint Service Directory Anda.

  2. Akun layanan Agen Layanan Dialogflow dengan alamat berikut harus ada untuk project agen Anda: 

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     Berikan peran IAM berikut ke akun layanan Dialogflow Service Agent:

    • servicedirectory.viewer project Service Directory
    • servicedirectory.pscAuthorizedService dari project jaringan

  3. Berikan Layanan Direktori Layanan beserta skema OpenAPI dan informasi autentikasi opsional saat membuat alat.

Akses parameter sesi alat OpenAPI

Input alat Open API berasal dari percakapan pengguna dengan LLM menggunakan skema sebagai panduan. Dalam beberapa situasi, input mungkin perlu berasal dari parameter sesi yang dikumpulkan selama alur atau diberikan sebagai input parameter kueri bersama dengan input pengguna.

Parameter sesi yang perlu diteruskan sebagai input dapat ditentukan sebagai

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Bread of the pet.

Jika parameter sesi tersebut tidak tersedia, input yang dihasilkan LLM akan diteruskan ke alat.

Nilai default alat OpenAPI

Skema Open API dapat digunakan untuk menentukan nilai default. Nilai default hanya digunakan jika tidak ada nilai input yang dihasilkan LLM atau nilai input berbasis parameter sesi untuk parameter atau properti tersebut.

Nilai default dapat ditentukan sebagai bagian dari skema sebagai berikut:

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

Jika tidak ada nilai yang dihasilkan LLM, nilai parameter sesi, atau nilai default, input tidak akan ditentukan.

Alat penyimpanan data

Untuk informasi tentang cara menggunakan alat penyimpanan data dengan playbook, lihat dokumentasi alat penyimpanan data.

Alat konektor

Alat konektor dapat digunakan oleh agen untuk melakukan tindakan menggunakan Koneksi yang dikonfigurasi di Konektor Integrasi. Setiap alat konektor dikonfigurasi dengan satu Koneksi dan satu atau beberapa tindakan. Jika diperlukan, beberapa alat dapat dibuat untuk satu Koneksi guna mengelompokkan berbagai tindakan untuk digunakan agen Anda.

Alat konektor mendukung Jenis konektor berikut:

Contoh harus digunakan untuk meningkatkan penggunaan alat konektor oleh agen dengan menunjukkan cara agen harus memanggil alat dan menggunakan respons.

Membuat koneksi

Untuk membuat koneksi dan menghubungkannya ke agen, Anda dapat membuka Tools > Create, memilih jenis alat Connector, jenis konektor yang Anda pilih, dan menggunakan tombol Create Connection. Tindakan ini akan mengarahkan Anda ke pembuatan Konektor Integrasi dengan sejumlah kolom yang telah diisi otomatis.

Atau, Anda dapat membuka Konektor Integrasi dan mengikuti petunjuk untuk membuat koneksi.

Tindakan konektor

Untuk setiap alat konektor, ada dua jenis tindakan yang dapat disediakan untuk agen Anda (lihat Entitas, operasi, dan tindakan untuk mengetahui informasi selengkapnya):

  1. Operasi CRUD entity

    Setiap Koneksi Anda memiliki "entity" yang sesuai dengan objek sumber data tersebut (untuk BigQuery, ini adalah tabel; untuk Salesforce, ini adalah objek, seperti 'Pesanan' atau 'Kasus').

    Anda dapat melakukan operasi CRUD pada setiap entity:

    • Create: membuat entity dengan nilai kolom yang ditentukan
    • Daftar: penelusuran instance entity berbasis filter
    • Update: metode berbasis filter untuk mengubah nilai kolom entity
    • Hapus: menghapus entity
    • Get mengambil satu entity menggunakan entityId

    Pelajari lebih lanjut detail operasi CRUD entity di dokumen Konektor.

  2. Tindakan khusus konektor

    Banyak Konektor mendukung tindakan 'ExecuteCustomQuery', yang memungkinkan eksekusi kueri SQL terhadap sumber data, dengan setiap entitas sumber data dapat direferensikan sebagai tabel. Lihat daftar ini untuk konektor yang didukung.

    Tindakan tambahan berbeda berdasarkan jenis konektor - misalnya, lihat tindakan konektor BigQuery atau tindakan konektor Salesforce.

Mengonfigurasi kolom input / output untuk operasi CRUD

Dengan memilih kolom input atau output tertentu untuk digunakan oleh tindakan alat konektor, Anda dapat membatasi kompleksitas tindakan ini untuk agen.

Misalnya, jika Anda hanya perlu membuat entitas dengan subset kolomnya, mengonfigurasi kumpulan kolom ini dalam tindakan akan menyederhanakan tindakan untuk agen.

Menentukan kumpulan kolom output akan mengurangi ukuran respons alat (berguna jika batas token menjadi masalah) dan menyederhanakan penanganan output oleh agen dengan hanya mengekspos kolom yang relevan.

Autentikasi

Jika koneksi yang Anda gunakan dikonfigurasi untuk mengizinkan penggantian autentikasi, alat ini dapat dikonfigurasi untuk meneruskan kredensial dari parameter sesi yang ditentukan.

Anda sebagai pembuat agen bertanggung jawab atas cara kredensial ini diisi ke parameter sesi dan alat akan otomatis meneruskannya ke sumber data yang akan digunakan untuk autentikasi saat tindakan alat dipanggil.

Alat fungsi

Jika memiliki fungsi yang dapat diakses oleh kode klien, tetapi tidak dapat diakses oleh alat OpenAPI, Anda dapat menggunakan alat fungsi. Alat fungsi selalu dijalankan di sisi klien, bukan oleh agen.

Prosesnya adalah sebagai berikut:

  1. Kode klien Anda mengirimkan permintaan intent deteksi.
  2. Agen mendeteksi bahwa alat fungsi diperlukan, dan respons intent deteksi berisi nama alat bersama dengan argumen input. Sesi ini dijeda hingga permintaan intent deteksi lain diterima dengan hasil alat.
  3. Kode klien Anda memanggil alat tersebut.
  4. Kode klien Anda mengirim permintaan intent deteksi lain yang memberikan hasil alat sebagai argumen output.

Contoh berikut menunjukkan skema input dan output alat fungsi:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

Contoh berikut menunjukkan permintaan dan respons intent deteksi awal menggunakan REST:

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

Contoh berikut menunjukkan permintaan intent deteksi kedua, yang memberikan hasil alat:

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

Eksekusi sisi klien

Seperti alat fungsi, alat OpenAPI dan penyimpanan data dapat dijalankan di sisi klien dengan menerapkan penggantian API saat berinteraksi dengan sesi.

Contoh:

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}

Prosesnya adalah sebagai berikut:

  1. Kode klien Anda mengirimkan permintaan intent deteksi yang menentukan eksekusi klien.
  2. Agen mendeteksi bahwa alat diperlukan, dan respons intent deteksi berisi nama alat beserta argumen input. Sesi ini dijeda hingga permintaan intent deteksi lain diterima dengan hasil alat.
  3. Kode klien Anda memanggil alat tersebut.
  4. Kode klien Anda mengirim permintaan intent deteksi lain yang memberikan hasil alat sebagai argumen output.
Sebelumnya
Parameter playbook
Berikutnya
Setelan playbook