Alat playbook

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

Anda dapat menggunakan alat bawaan atau membuat alat yang disesuaikan dengan kebutuhan 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 View 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 perlu konfigurasi manual.

Alat bawaan yang didukung adalah:

  • Code Interpreter: Alat pihak pertama Google yang menggabungkan kemampuan pembuatan kode dan eksekusi kode serta memungkinkan Anda melakukan berbagai tugas, termasuk analisis data, visualisasi data, pemrosesan teks, dan menyelesaikan 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 skema:

{
  "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.

Anda dapat menguji apakah alat telah disiapkan dengan benar menggunakan fitur Alat pengujian yang tersedia di halaman alat. Fitur ini juga tersedia dalam tampilan contoh saat Anda menambahkan pemanggilan alat ke contoh.

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 menggunakan referensi skema internal @dialogflow/sessionId sebagai jenis skema parameter. Dengan jenis skema parameter ini, ID sesi Dialogflow CX untuk percakapan saat ini 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, dan header. Jenis parameter cookie tidak didukung.
  • Parameter yang ditentukan oleh skema OpenAPI mendukung jenis data berikut: string, number, integer, boolean, dan array. Jenis object tidak didukung.
  • Anda tidak dapat menentukan parameter kueri di editor contoh konsol.
  • Isi permintaan dan respons harus kosong atau menggunakan format application/json.

Pembuatan skema alat OpenAPI

Saat Anda memberikan skema, klik Use Gemini untuk membuat skema menggunakan AI generatif.

Berikan detail berikut untuk memandu pembuatan:

  • URL permintaan.
  • Metode HTTP, seperti GET atau POST.
  • Contoh input.
  • Contoh output.
  • Perintah teks yang menjelaskan alat.

Setelah membuat skema, Anda dapat mengeditnya sesuai kebutuhan dan menambahkan URL serta metode tambahan secara manual.

Autentikasi API alat OpenAPI

Anda dapat menggunakan opsi autentikasi berikut saat memanggil API eksternal.

Autentikasi Agen Layanan Dialogflow CX

Dialogflow CX dapat membuat token ID menggunakan Agen Layanan Dialogflow CX. Token ditambahkan di header HTTP otorisasi saat Dialogflow CX memanggil API eksternal.

Anda dapat menggunakan token ID untuk mengakses fungsi Cloud Run dan layanan Cloud Run setelah memberikan peran roles/cloudfunctions.invoker dan roles/run.invoker ke service-agent-project-number@gcp-sa-dialogflow..

Jika layanan Cloud Run Functions dan Cloud Run berada dalam project resource yang sama, Anda tidak memerlukan izin Identity and Access Management (IAM) tambahan untuk memanggilnya.

Autentikasi akun layanan

Akun layanan dapat mengautentikasi permintaan alat ke Google API mana pun yang mendukungnya.

Buat akun layanan, jika Anda belum memilikinya. Karena akun layanan adalah akun utama, Anda dapat memberinya peran untuk mengakses resource dalam project Anda, seperti yang dapat Anda lakukan untuk akun utama lainnya. Anda dapat menggunakan email akun layanan untuk membuat token akses yang Anda kirim di header Authorization permintaan alat.

Jika Anda mengonfigurasi alat untuk menggunakan akun layanan, Anda harus memiliki izin berikut:

  • roles/iam.serviceAccountUser

Agar Dialogflow CX dapat membuat token, berikan izin berikut kepada Agen Layanan Dialogflow CX:

  • roles/iam.serviceAccountTokenCreator

Akun layanan juga harus memiliki izin untuk mengakses layanan yang menghosting alat.

Autentikasi kunci API

  • Anda dapat mengonfigurasi autentikasi kunci API dengan memberikan nama kunci, lokasi permintaan (header atau string kueri), dan kunci API agar Dialogflow CX meneruskan kunci API dalam permintaan.
  • Sebaiknya berikan kunci API Anda menggunakan Secret Manager.
  • Setelah 15 Agustus 2025, agen yang diekspor tidak akan lagi berisi kunci API nilai mentah.

OAuth

Alur kredensial klien OAuth didukung untuk autentikasi server ke server:

  • Anda dapat menggunakan alur ini jika Generative AI App Builder adalah pemilik resource dan Anda tidak memerlukan otorisasi pengguna akhir.
  • Anda harus mengonfigurasi client ID, rahasia klien, dan endpoint token dari penyedia OAuth di Dialogflow CX.
  • Sebaiknya berikan rahasia klien Anda menggunakan Secret Manager. Agen yang diekspor tidak berisi rahasia klien nilai mentah setelah 15 Agustus 2025.
  • Dialogflow CX menukar token akses OAuth dari penyedia OAuth dan meneruskannya di header otorisasi permintaan.

Token Pemilik

  • Anda dapat mengonfigurasi autentikasi Bearer untuk meneruskan token Bearer secara dinamis dari klien. Token ini disertakan dalam header otorisasi 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 Anda menggunakan Secret Manager. Setelah 15 Agustus 2025, agen yang diekspor tidak akan berisi token Bearer nilai mentah.

Autentikasi TLS bersama

  • Untuk mengetahui informasi selengkapnya, lihat Autentikasi TLS bersama.
  • Sertifikat klien kustom didukung. Anda dapat menyiapkan sertifikat klien di tingkat agen di tab Security di setelan agen.
  • Sertifikat (format PEM) dan kunci pribadi (format PEM) adalah kolom wajib diisi. Setelah ditetapkan, sertifikat klien ini akan digunakan selama mutual TLS untuk semua alat dan webhook.

Sertifikat CA kustom

Autentikasi Secret Manager

Jika menggunakan OAuth, kunci API, atau token pemilik, Anda dapat menyimpan kredensial sebagai secret menggunakan Secret Manager.

Autentikasi alat Anda menggunakan secret dengan mengikuti langkah-langkah berikut:

  1. Buat secret Anda jika Anda belum memilikinya.
  2. Berikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) kepada Dialogflow Service Agent pada secret baru.
  3. Salin kredensial Anda ke papan klip.
  4. Tambahkan versi secret baru ke secret Anda. Tempelkan kredensial Anda sebagai nilai secret.
    • Hilangkan karakter newline di akhir nilai Secret.
  5. Salin nama versi secret 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 tempelkan nama versi rahasia ke kotak input Secret version.
    • Jika Anda menggunakan kunci API, pilih API key sebagai Authentication type, lalu klik Secret version di bagian API key. Tempel nama versi secret ke kotak input Secret version.
    • Jika Anda menggunakan Token pemilik, pilih Bearer token sebagai Authentication type, lalu klik Secret version di bagian Bearer token. Tempelkan nama versi secret ke kotak input Secret version.
  7. Klik Simpan.

Akses jaringan pribadi alat OpenAPI

Alat OpenAPI terintegrasi dengan akses jaringan pribadi Direktori Layanan untuk terhubung ke target API di jaringan VPC Anda. Hal ini menjaga traffic tetap berada dalam jaringan Google Cloud dan menerapkanIAM danKontrol Layanan VPC.

Untuk menyiapkan alat OpenAPI yang menargetkan jaringan pribadi:

  1. Ikuti Konfigurasi jaringan pribadi Direktori Layanan untuk mengonfigurasi jaringan VPC dan endpoint Direktori Layanan Anda.
  2. Pastikan akun layanan Dialogflow CX Service Agent dengan alamat berikut ada untuk project agen Anda: 
    service-agent-project-number@gcp-sa-dialogflow.
     Berikan peran IAM berikut kepada akun layanan Dialogflow CX Service Agent:
    • servicedirectory.viewer project Direktori Layanan
    • servicedirectory.pscAuthorizedService project jaringan
  3. Sediakan Service Directory Service beserta skema OpenAPI dan informasi autentikasi opsional saat Anda membuat alat.

Akses parameter sesi alat OpenAPI

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

Anda dapat menentukan parameter sesi yang perlu diteruskan sebagai input menggunakan format berikut:

     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: Breed of the pet.

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

Nilai default alat OpenAPI

Anda dapat menggunakan skema OpenAPI untuk menentukan nilai default. Nilai default ini hanya berlaku jika nilai input yang dihasilkan LLM atau nilai input berbasis parameter sesi tidak tersedia untuk parameter atau properti tersebut.

Anda dapat menentukan nilai default 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: Breed 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 mengetahui informasi selengkapnya tentang cara menggunakan alat penyimpanan data dengan playbook, lihat alat penyimpanan data.

Alat konektor

Alat konektor memungkinkan Anda mengonfigurasi agen untuk melakukan tindakan menggunakan koneksi yang dikonfigurasi di Integration Connectors. Setiap alat konektor dikonfigurasi dengan satu koneksi dan satu atau beberapa tindakan. Anda dapat membuat beberapa alat untuk satu koneksi guna mengelompokkan berbagai tindakan yang akan digunakan oleh agen Anda.

Alat konektor mendukung Jenis konektor berikut:

Anda dapat menggunakan contoh untuk membantu agen menggunakan alat konektor secara efektif dengan menunjukkan cara memanggil alat dan menggunakan respons.

Membuat koneksi

Untuk membuat koneksi dan menghubungkannya ke agen Anda, buka Tools > Create, pilih jenis alat Connector dan jenis konektor yang Anda pilih, lalu klik Create Connection. Tindakan ini akan membuka pembuatan Integration Connectors dengan beberapa kolom yang telah diisi otomatis.

Atau, Anda dapat membuka Integration Connectors dan mengikuti petunjuk untuk membuat koneksi.

Tindakan konektor

Anda dapat menyediakan dua jenis tindakan untuk agen Anda untuk setiap alat konektor. Untuk mengetahui informasi selengkapnya, lihat Entity, operasi, dan tindakan.

  1. Operasi CRUD entitas:

    Setiap koneksi memiliki entity yang sesuai dengan objek sumber data tersebut (untuk BigQuery, ini adalah tabel; untuk Salesforce, ini adalah objek, seperti Order atau Case).

    Anda dapat melakukan operasi CRUD pada setiap entity:

    • Create: Memvalidasi dan membuat entity dengan nilai kolom yang ditentukan.
    • List: Penelusuran instance entity berbasis filter.
    • Update: Metode berbasis filter untuk mengubah nilai kolom entity.
    • Delete: Menghapus entity.
    • Get: Mengambil satu entity menggunakan entityId.

    Untuk mengetahui informasi selengkapnya tentang operasi CRUD entity, lihat dokumentasi Connectors.

  2. Tindakan khusus konektor:

    Banyak Konektor mendukung tindakan ExecuteCustomQuery, yang memungkinkan Anda menjalankan kueri SQL terhadap sumber data, tempat setiap entity sumber data dapat direferensikan sebagai tabel. Untuk mengetahui informasi selengkapnya, lihat daftar konektor yang didukung.

Tindakan tambahan berbeda-beda 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 tindakan alat konektor, Anda dapat membatasi kompleksitas tindakan ini untuk agen.

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

Menentukan sekumpulan kolom output akan mengurangi ukuran respons alat untuk mengurangi batas token. Hal ini memungkinkan agen menangani output dengan hanya mengekspos kolom yang relevan.

Autentikasi

Jika koneksi yang Anda gunakan mengizinkan pengabaian autentikasi, konfigurasikan alat untuk meneruskan kredensial dari parameter sesi yang ditentukan.

Isi kredensial ini di parameter sesi. Alat ini kemudian meneruskannya secara otomatis ke sumber data untuk autentikasi saat memanggil tindakan.

Alat fungsi

Jika Anda memiliki kemampuan yang dapat diakses oleh kode klien, tetapi tidak dapat diakses oleh alat OpenAPI, Anda dapat menggunakan alat fungsi. Sisi klien selalu menjalankan alat fungsi, bukan agen.

Prosesnya adalah sebagai berikut:

  1. Kode klien Anda mengirimkan permintaan deteksi intent.
  2. Agen mendeteksi bahwa alat fungsi diperlukan, dan respons intent deteksi berisi nama alat beserta argumen input. Sesi ini dijeda hingga permintaan deteksi intent lain diterima dengan hasil alat.
  3. Kode klien Anda memanggil alat.
  4. Kode klien Anda mengirimkan permintaan deteksi intent 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 deteksi intent kedua yang memberikan hasil alat:

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

Eksekusi sisi klien

Anda dapat menjalankan alat OpenAPI dan penyimpanan data di sisi klien, seperti alat fungsi, 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 deteksi intent yang menentukan eksekusi klien.
  2. Agen mendeteksi bahwa alat diperlukan, dan respons deteksi intent berisi nama alat beserta argumen input. Sesi ini dijeda hingga permintaan deteksi intent lain diterima dengan hasil alat.
  3. Kode klien Anda memanggil alat.
  4. Kode klien Anda mengirimkan permintaan deteksi intent lain yang memberikan hasil alat sebagai argumen output.
Sebelumnya
Parameter playbook
Berikutnya
Setelan playbook