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.

Batasan

Batasan berikut berlaku:

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 lainnya setelah Anda memberikan peran yang diperlukan ke service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • 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.

  • 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>
    }
  }
  ...
}

  • 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

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 tidak ada parameter sesi tersebut, 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

Alat penyimpanan data dapat digunakan oleh agen untuk menjawab pertanyaan pengguna akhir dari penyimpanan data Anda. Anda dapat menyiapkan satu penyimpanan data dari setiap jenis per alat, dan alat tersebut akan membuat kueri di setiap penyimpanan data ini untuk mendapatkan jawaban. Secara default, agen akan memanggil alat penyimpanan data untuk Anda. Atau, Anda dapat menjalankan alat penyimpanan data di sisi klien.

Jenis penyimpanan data dapat berupa salah satu dari berikut:

  • PUBLIC_WEB: Penyimpanan data yang berisi konten web publik.
  • UNSTRUCTURED: Penyimpanan data yang berisi data pribadi tidak terstruktur.
  • STRUCTURED: Penyimpanan data yang berisi data terstruktur (misalnya FAQ).

Contoh berikut menunjukkan cara mereferensikan penyimpanan data:

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

Respons alat penyimpanan data mungkin juga berisi cuplikan tentang sumber konten yang digunakan untuk membuat respons. Agen dapat memberikan petunjuk lebih lanjut tentang cara melanjutkan jawaban dari penyimpanan data atau cara merespons jika tidak ada jawaban.

Anda dapat menimpa jawaban dengan menambahkan entri FAQ untuk pertanyaan tertentu.

Contoh dapat digunakan untuk lebih meningkatkan perilaku agen. Contoh ini harus memiliki skema berikut:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

Membuat penyimpanan data

Untuk membuat penyimpanan data dan menghubungkannya ke aplikasi, Anda dapat menggunakan link Alat di navigasi sebelah kiri konsol. Ikuti petunjuk untuk membuat penyimpanan data.

Parameter kueri tambahan

Saat membuat contoh alat penyimpanan data, parameter input alat requestBody menyediakan tiga input opsional bersama dengan string query yang diperlukan - string filter, objek terstruktur userMetadata, dan string fallback.

Parameter filter memberikan kemampuan untuk memfilter kueri penelusuran data terstruktur atau data tidak terstruktur dengan metadata. String ini harus mengikuti sintaksis ekspresi filter yang didukung untuk penyimpanan data. Beberapa contoh dan contoh mendetail dianjurkan untuk mengarahkan LLM playbook tentang cara mengisi parameter ini. Jika string filter tidak valid, filter akan diabaikan saat menjalankan kueri penelusuran.

Contoh string filter untuk menyaring hasil penelusuran berdasarkan lokasi dapat terlihat seperti:

  "filter": "country: ANY(\"Canada\")"

Praktik terbaik untuk pemfilteran:

  • Tentukan kolom yang tersedia untuk pemfilteran dan nilai yang valid untuk setiap kolom ini, sehingga playbook memahami batasan dalam membuat filter yang valid. Misalnya, untuk memfilter hasil untuk penyimpanan data yang menyimpan informasi menu, mungkin ada kolom meal dengan "sarapan", "makan siang", dan "makan malam" sebagai nilai yang valid; dan kolom servingSize yang dapat berupa bilangan bulat dari 0 hingga 5. Petunjuk Anda dapat terlihat seperti:

    When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.

  • Jika playbook ditujukan untuk audiens pengguna eksternal, Anda mungkin perlu menambahkan petunjuk agar playbook tidak merespons pengguna dengan informasi tentang pembuatan filter ini. Misalnya:

    Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."

    Memberikan contoh kasus ini juga akan membantu.

Parameter userMetadata memberikan informasi tentang pengguna akhir. Setiap pasangan nilai kunci dapat diisi dalam parameter ini. Metadata ini diteruskan ke alat penyimpanan data untuk memberikan informasi yang lebih baik tentang hasil penelusuran dan respons alat. Sebaiknya berikan beberapa contoh untuk memberi tahu LLM playbook tentang cara mengisi parameter ini.

Contoh nilai parameter userMetadata untuk menyaring hasil penelusuran yang relevan dengan pengguna tertentu dapat terlihat seperti:

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

Parameter fallback memberikan jawaban yang harus direspons oleh alat penyimpanan data jika tidak ada jawaban ringkas yang valid untuk kueri. Beberapa contoh dapat diberikan untuk menginstruksikan LLM playbook tentang cara mengisi penggantian untuk input pengguna yang terkait dengan berbagai topik. Tidak akan ada cuplikan dalam output alat. Pengoptimalan ini dapat digunakan untuk mengurangi latensi dan penggunaan batas token input.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

Jika Anda menemukan beberapa respons selama pengujian tidak memenuhi ekspektasi, penyesuaian berikut tersedia di halaman Alat untuk alat penyimpanan data:

Melandasi keyakinan

Untuk setiap respons yang dihasilkan dari konten penyimpanan data yang terhubung, playbook akan mengevaluasi tingkat keyakinan, yang mengukur keyakinan bahwa semua informasi dalam respons didukung oleh informasi di penyimpanan data. Anda dapat menyesuaikan respons yang diizinkan dengan memilih tingkat keyakinan terendah yang Anda inginkan. Hanya respons pada atau di atas tingkat kepercayaan tersebut yang akan ditampilkan.

Ada 5 tingkat keyakinan yang dapat dipilih: VERY_LOW, LOW, MEDIUM, HIGH, dan VERY_HIGH.

Konfigurasi ringkasan

Anda dapat memilih model generatif yang digunakan oleh pengendali penyimpanan data untuk permintaan generatif ringkasan. Jika tidak ada yang dipilih, opsi model default akan digunakan. Tabel berikut berisi opsi yang tersedia:

ID Model Dukungan Bahasa
text-bison@002 Tersedia dalam semua bahasa yang didukung.
gemini-1.0-pro-001 Tersedia dalam semua bahasa yang didukung.

Anda juga dapat memberikan perintah Anda sendiri untuk panggilan LLM ringkasan.

Perintah adalah template teks yang mungkin berisi placeholder standar. Placeholder akan diganti dengan nilai yang sesuai saat runtime dan teks akhir akan dikirim ke LLM.

Placeholder-nya adalah sebagai berikut:

  • $original-query: Teks kueri pengguna.
  • $rewritten-query: Playbook menggunakan modul penulis ulang untuk menulis ulang kueri pengguna asli ke dalam format yang lebih akurat.

  • $sources: Playbook menggunakan Enterprise Search untuk menelusuri sumber berdasarkan kueri pengguna. Sumber yang ditemukan dirender dalam format tertentu:

    [1] title of first source
content of first source
[2] title of second source
content of second source

  • $end-user-metadata: Informasi tentang pengguna yang mengirim kueri dirender dalam format berikut:

    The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}

  • $conversation: Histori percakapan dirender dalam format berikut:

    Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

Perintah kustom harus menginstruksikan LLM untuk menampilkan "NOT_ENOUGH_INFORMATION" saat tidak dapat memberikan jawaban. Playbook akan mengubah konstanta ini menjadi pesan yang mudah digunakan bagi pengguna.

Setelan payload

Setelan payload menyediakan cara untuk menambahkan cuplikan penyimpanan data sebagai konten kaya dalam payload respons yang dirender di messenger.

Frasa yang dilarang (konfigurasi tingkat playbook)

Anda memiliki opsi untuk menentukan frasa tertentu yang tidak boleh diizinkan. Ini dikonfigurasi di tingkat playbook dan digunakan oleh LLM playbook dan alat penyimpanan data. Jika respons yang dihasilkan atau bagian dari perintah LLM, seperti input pengguna, berisi salah satu frasa yang dilarang secara verbatim, respons tersebut tidak akan ditampilkan.

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
Praktik terbaik playbook