Alat

Dengan menggunakan alat, Anda dapat menghubungkan aplikasi agen ke sistem eksternal. Sistem ini dapat menambah pengetahuan tentang aplikasi agen dan mendukungnya untuk menjalankan tugas-tugas yang kompleks secara efisien.

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

Batasan

Batasan berikut berlaku:

  • Anda harus membuat penyimpanan data (atau menghubungkan penyimpanan data yang sudah ada) saat membuat alat penyimpanan data untuk aplikasi agen.
  • Aplikasi dengan penyimpanan data yang terpotong dan tidak tidak didukung.

Alat bawaan

Alat bawaan dihosting oleh Google. Anda dapat mengaktifkan alat ini di aplikasi 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 masalah persamaan, atau pengoptimalan.

Aplikasi 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

Aplikasi agen dapat terhubung ke API eksternal menggunakan alat OpenAPI dengan memberikan skema OpenAPI. Secara default, aplikasi 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

Secara opsional, Anda dapat 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 parameter value. 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 menghasilkan token ID atau token akses menggunakan Agen Layanan Dialogflow. Token ditambahkan dalam header HTTP otorisasi saat Dialogflow memanggil API eksternal.
    • Token ID dapat digunakan untuk mengakses layanan Cloud Functions dan 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 layanan Cloud Functions dan Cloud Run berada dalam 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 agar Dialogflow dapat meneruskan kunci API dalam permintaan.
  • OAuth
    • Alur Kredensial Klien OAuth didukung untuk autentikasi server ke server. Client ID, Rahasia Klien, dan endpoint Token dari penyedia OAuth harus dikonfigurasi di Dialogflow. Dialogflow menukar token akses OAuth dan meneruskannya di header autentikasi permintaan.
    • Untuk alur OAuth lainnya, Anda harus menggunakan Alat Fungsi untuk berintegrasi dengan UI login Anda sendiri guna menukar token.
  • Autentikasi TLS bersama
  • Sertifikat CA kustom

Alat penyimpanan data

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

Jenis penyimpanan data dapat berupa salah satu dari hal berikut:

  • PUBLIC_WEB: Penyimpanan data yang berisi konten web publik.
  • UNSTRUCTURED: Penyimpanan data yang berisi data pribadi yang 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 juga dapat berisi cuplikan tentang sumber konten yang digunakan untuk membuat respons. Aplikasi agen lebih lanjut dapat memberikan petunjuk tentang cara melanjutkan dengan 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 meningkatkan perilaku aplikasi agen lebih lanjut. Contoh 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 pada konsol. Ikuti petunjuk untuk membuat penyimpanan data.

Parameter kueri tambahan

Saat membuat contoh alat penyimpanan data, tersedia dua parameter opsional, bersama dengan string query yang diperlukan - string filter dan objek terstruktur userMetadata.

Parameter filter memberikan kemampuan untuk memfilter kueri penelusuran dari data terstruktur Anda atau data tidak terstruktur dengan metadata. String ini harus mengikuti sintaksis ekspresi filter yang didukung. Sebaiknya beberapa contoh untuk memberikan petunjuk kepada LLM agen tentang cara mengisi parameter ini. Jika ada string filter yang tidak valid, filter akan diabaikan saat melakukan kueri penelusuran.

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

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

Parameter userMetadata memberikan informasi tentang pengguna akhir. Semua key-value pair dapat diisi dalam parameter ini. Metadata ini diteruskan ke alat penyimpanan data untuk memberikan informasi yang lebih baik pada hasil penelusuran dan respons alat. Sebaiknya berikan beberapa contoh untuk memberi tahu LLM agen tentang cara mengisi parameter ini.

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

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

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

Keyakinan dasar

Untuk setiap respons yang dihasilkan dari konten penyimpanan data yang terhubung, agen akan mengevaluasi tingkat keyakinan, yang mengukur keyakinan bahwa semua informasi dalam respons didukung oleh informasi dalam penyimpanan data. Anda dapat menyesuaikan respons yang diizinkan dengan memilih tingkat keyakinan terendah yang Anda rasakan. Hanya respons pada atau di atas tingkat keyakinan 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 agen penyimpanan data untuk permintaan generatif ringkasan. Jika tidak ada yang dipilih, opsi model default digunakan. Tabel berikut berisi opsi yang tersedia:

ID Model Dukungan Bahasa
text-bison@001 Tersedia dalam semua bahasa yang didukung.
teks-bison@002 Tersedia dalam semua bahasa yang didukung.
text-bison@001 Tuned (percakapan) Saat ini hanya tersedia bahasa Inggris.
text-bison@001 disetel (informasional) Saat ini hanya tersedia bahasa Inggris.
Gemini-Pro Tersedia dalam semua bahasa yang didukung.

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

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

Placeholder tersebut adalah sebagai berikut:

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

  • $sources: Agen 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 first source

  • $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

Dialog kustom harus menginstruksikan LLM untuk menampilkan "NOT_ENOUGH_INFORMATION" jika tidak dapat memberikan jawaban. Agen akan mengubah konstanta ini menjadi pesan yang ramah pengguna bagi pengguna.

Frasa yang diblokir (konfigurasi tingkat agen)

Anda memiliki opsi untuk mendefinisikan frasa tertentu yang seharusnya tidak diizinkan. Keduanya dikonfigurasi pada tingkat agen dan digunakan oleh LLM agen dan alat penyimpanan data. Jika respons yang dihasilkan atau bagian dari perintah LLM, seperti input pengguna, berisi salah satu frasa yang diblokir kata demi kata, respons tersebut tidak akan ditampilkan.

Alat fungsi

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

Prosesnya sebagai berikut:

  1. Kode klien Anda akan mengirimkan permintaan intent deteksi.
  2. Aplikasi agen mendeteksi bahwa alat fungsi 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 akan memanggil alat tersebut.
  4. Kode klien Anda mengirimkan permintaan intent deteksi lain yang memberikan hasil alat sebagai argumen output.

Contoh berikut menunjukkan skema input dan output dari 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 sebagai berikut:

  1. Kode klien Anda mengirimkan permintaan intent deteksi yang menentukan eksekusi klien.
  2. Aplikasi 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 akan memanggil alat tersebut.
  4. Kode klien Anda mengirimkan permintaan intent deteksi lain yang memberikan hasil alat sebagai argumen output.
Sebelumnya
Praktik terbaik
Berikutnya
Ringkasan