Alat OpenAPI dan Konektor Integrasi

Anda dapat menggunakan fitur Agent Assist bersama dengan API dan sumber data eksternal. Google Cloud menyediakan alat OpenAPI dan Integration Connectors untuk memfasilitasi integrasi Agent Assist Anda.

Alat OpenAPI

Alat OpenAPI memungkinkan koneksi antara fitur Agent Assist dan API eksternal. Koneksi ini memungkinkan fitur Agent Assist membaca dan menulis informasi dari berbagai sumber. Untuk membuat alat OpenAPI, Anda harus memberikan skema OpenAPI yang menjelaskan API eksternal yang ingin Anda hubungkan.

Alat Integration Connectors

Gunakan Konektor Integrasi untuk terhubung Google Cloud ke berbagai sumber data. Alat konektor memungkinkan fitur Agent Assist menggunakan Integration Connector untuk membaca dan menulis sumber data tersebut.

Sebelum memulai

Untuk menyiapkan lingkungan guna membuat alat OpenAPI dan Integration Connectors, masukkan project ID dan region Anda, lalu jalankan kode berikut.

CLOUDSDK_CORE_PROJECT=YOUR_PROJECT_ID
REGION=YOUR_REGION
API_VERSION=v2beta1
API_ENDPOINT=https://${REGION}-dialogflow.googleapis.com/${API_VERSION}

function gcurl () {
        curl -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "X-Goog-User-Project: ${CLOUDSDK_CORE_PROJECT}" -H "Content-Type: application/json; charset=utf-8" "$@"
}

Membuat alat OpenAPI

Untuk menggunakan alat OpenAPI, Anda harus meminta pembuatannya terlebih dahulu dan menyimpan nama resource alat.

Langkah 1: Minta untuk membuat alat

Ikuti langkah-langkah berikut untuk meminta pembuatan alat OpenAPI.

  1. Sesuaikan kode sebagai berikut:
    1. Dalam satu project, gunakan nilai tool_key yang unik di antara semua alat Anda.
    2. Masukkan skema OpenAPI Anda sendiri di kolom open_api_spec.text_schema.

  2. Jalankan kode yang disesuaikan berikut. 

    $ cat > create-tool-request.json << EOF
{
  "tool_key": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "display_name": "TOOL_DISPLAY_NAME",
  "open_api_spec": {
    "text_schema": "Your-Schema"
  }
}
EOF
    


    $ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-tool-request.json | tee create-tool-response.json

Jika berhasil, API akan menampilkan alat yang baru dibuat, yang berisi nama resource, seperti yang ditunjukkan dalam contoh berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "createTime": "2025-06-02T18:11:38.999174724Z",
  "updateTime": "2025-06-02T18:11:38.999174724Z",
  "displayName": "TOOL_DISPLAY_NAME",
  "openApiSpec": {
    "textSchema": "Your-Schema"
  }
}

Langkah 2: Simpan nama resource alat

Simpan nama resource alat dalam variabel lingkungan untuk digunakan nanti. Berikut adalah contoh template untuk variabel lingkungan resource alat.

TOOL_RESOURCE=$(cat create-tool-response.json | jq .name | tr -d '"')

Pelatih AI dengan alat OpenAPI

Anda dapat menggunakan alat OpenAPI dengan fitur pelatih AI untuk mengakses informasi tambahan dari luar Google Cloud. Informasi eksternal tersebut kemudian dapat digunakan untuk membuat saran yang membantu agen pusat kontak.

Langkah 1: Buat generator

Contoh berikut membuat generator dengan variabel lingkungan resource alat.

$ cat > create-generator-request.json << _EOF_
{"agent_coaching_context":{"instructions":[{"agent_action":"help customer by using the tool to find information from library of congress","condition":"The customer asks about library of congress","description":"agent coaching test","display_name":"Search for information"}],"overarching_guidance":"Help customer with questions"},"description":"prober-generate-suggestions-with-agent-coaching-generator","inference_parameter":{"max_output_tokens":256,"temperature":0},"tools":["${TOOL_RESOURCE}"],"trigger_event":"CUSTOMER_MESSAGE"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

Anda akan menerima respons yang terlihat seperti contoh generator pelatih AI berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID",
  "description": "example-generator",
  "inferenceParameter": {
    "maxOutputTokens": 256,
    "temperature": 0
  },
  "triggerEvent": "CUSTOMER_MESSAGE",
  "createTime": "2025-06-02T18:30:51.021461728Z",
  "updateTime": "2025-06-02T18:30:51.021461728Z",
  "agentCoachingContext": {
    "instructions": [
      {
        "displayName": "Search for information",
        "condition": "The customer asks about library of congress",
        "agentAction": "help customer by using the tool to find information from library of congress"
      }
    ],
    "version": "1.5",
    "overarchingGuidance": "Help customer with questions"
  },
  "tools": [
    "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID"
  ]
}

Simpan nama resource generator

Simpan sebagai variabel lingkungan untuk digunakan nanti, seperti dalam contoh berikut.

GENERATOR_RESOURCE=$(cat create-generator-response.json | jq .name | tr -d '"')

Langkah 2: Buat profil percakapan

Jalankan kode berikut untuk membuat profil percakapan.

$ cat > create-conversation-profile-request.json << _EOF_
{"displayName":"prober-generate-suggestions-with-agent-coaching-generator","humanAgentAssistantConfig":{"humanAgentSuggestionConfig":{"generators":["${GENERATOR_RESOURCE}"]}}}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversationProfiles -d @create-conversation-profile-request.json | tee create-conversation-profile-response.json

Anda akan menerima respons seperti berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
  "humanAgentAssistantConfig": {
    "humanAgentSuggestionConfig": {
      "generators": [
        "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
      ]
    }
  },
  "languageCode": "en-US",
  "createTime": "2025-06-02T18:40:39.940318Z",
  "updateTime": "2025-06-02T18:40:39.940318Z",
  "projectNumber": "${project_number}"
}

Simpan nama resource profil percakapan

Simpan nama ini sebagai variabel lingkungan, seperti contoh berikut.

CONVERSATION_PROFILE_RESOURCE=$(cat create-conversation-profile-response.json | jq .name | tr -d '"')

Langkah 3: Buat percakapan

Jalankan kode berikut untuk membuat percakapan.

$ cat > create-conversation-request.json << _EOF_
{"conversationProfile":"${CONVERSATION_PROFILE_RESOURCE}"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversations -d @create-conversation-request.json | tee create-conversation-response.json

Anda akan menerima respons seperti berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID",
  "lifecycleState": "IN_PROGRESS",
  "conversationProfile": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "startTime": "2025-06-02T18:43:40.818123Z",
  "conversationStage": "HUMAN_ASSIST_STAGE",
  "source": "ONE_PLATFORM_API",
  "initialConversationProfile": {
    "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
    "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
    "humanAgentAssistantConfig": {
      "humanAgentSuggestionConfig": {
        "generators": [
          "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
        ]
      }
    },
    "languageCode": "en-US"
  },
  "projectNumber": "${project_number}",
  "initialGeneratorContexts": {
    "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID": {
      "generatorType": "AGENT_COACHING",
      "generatorVersion": "1.5"
    }
  }
}

Menyimpan nama resource percakapan

Simpan nama ini sebagai variabel lingkungan untuk digunakan nanti. Variabel Anda harus memiliki format berikut.

CONVERSATION_RESOURCE=$(cat create-conversation-response.json | jq .name | tr -d '"')

Langkah 4: Buat pengguna akhir

Jalankan kode berikut untuk membuat pengguna akhir.

$ cat > create-end-user-request.json << _EOF_
{"role":"END_USER"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-end-user-request.json | tee create-end-user-response.json

Anda akan menerima respons seperti berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID/participants/End-User-Participant-ID",
  "role": "END_USER"
}

Menyimpan nama resource pengguna akhir

Simpan nama resource pengguna akhir sebagai variabel lingkungan seperti berikut. 

END_USER_RESOURCE=$(cat create-end-user-response.json | jq .name | tr -d '"')

Langkah 5: Buat agen manusia

Jalankan kode berikut untuk membuat agen manusia.

$ cat > create-human-agent-request.json << _EOF_
{"role":"HUMAN_AGENT"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-human-agent-request.json | tee create-human-agent-response.json

Anda akan menerima respons seperti berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-IDHuman-Agent-Participant-ID",
  "role": "HUMAN_AGENT"
}

Simpan nama resource agen manusia

Simpan nama resource agen manusia sebagai variabel lingkungan seperti berikut.

HUMAN_AGENT_RESOURCE=$(cat create-human-agent-response.json | jq .name | tr -d '"')

Langkah 6: Kirim teks ke pelatih AI

Jalankan kode berikut untuk mengirim teks ke pelatih AI dengan metode AnalyzeContent.

cat > analyze-content-1-request.json << _EOF_
{"text_input":{"languageCode":"en-US","text":"Can you search library of congress for the latest trends"}}
_EOF_

gcurl -X POST "${API_ENDPOINT}/${END_USER_RESOURCE}:analyzeContent" -d @analyze-content-1-request.json | tee analyze-content-1-response.json

Langkah 7: Verifikasi panggilan alat

Jalankan kode berikut untuk memverifikasi panggilan alat.

cat analyze-content-1-response.json| jq ".humanAgentSuggestionResults[0].generateSuggestionsResponse.generatorSuggestionAnswers[0].generatorSuggestion.toolCallInfo"

Anda akan menerima respons seperti berikut.

[
  {
    "toolCall": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
      "action": "search",
      "inputParameters": {
        "q": "latest trends",
        "fo": "json",
        "tool_description": "A generic search endpoint that might be available across various LoC APIs. The structure of the results will vary.\n",
        "at": "trending_content"
      },
      "createTime": "2025-06-02T18:56:53.882479179Z"
    },
    "toolCallResult": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/MjM0NTU3NDk2MTM5NTAwNzQ4OQ",
      "action": "search",
      "content": ""}]}",
      "createTime": "2025-06-02T18:56:54.289367086Z"
    }
  }
]

Langkah 8: (Opsional) Hapus resource

Untuk menghapus resource yang Anda buat pada langkah-langkah sebelumnya, jalankan kode berikut.

Profil percakapan

gcurl -X DELETE ${API_ENDPOINT}/${CONVERSATION_PROFILE_RESOURCE}

Pembuat

gcurl -X DELETE ${API_ENDPOINT}/${GENERATOR_RESOURCE}

Alat OpenAPI

gcurl -X DELETE ${API_ENDPOINT}/${TOOL_RESOURCE}

Membuat alat Integration Connectors

Anda dapat menyiapkan Integration Connectors menggunakan konsol Google Cloud . Ikuti langkah-langkah berikut untuk membuat alat Konektor Integrasi Agent Assist berdasarkan konektor BigQuery.

Langkah 1: Buat alat konektor BigQuery

Sebelum membuat alat Integration Connectors, buka Google Cloud console dan buat BigQuery Integration Connectors.

Langkah 2: Minta untuk membuat alat Integration Connectors

Jalankan kode berikut untuk meminta pembuatan alat. Untuk kolom connector_spec.name, gunakan nama resource konektor BigQuery Anda.

cat > create-connector-tool-request.json << _EOF_
{
  "tool_key": "order_tool",
  "description": "order bigquery connector tool",
  "display_name": "order bigquery connector tool",
  "connector_spec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/Your-Connector-ID",
    "actions": [
                             {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "LIST"
                               }
                             }, {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "GET"
                               }
                             }
                           ]
  }
}
_EOF_


gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-connector-tool-request.json | tee create-connector-tool-response.json

Anda akan menerima respons yang terlihat seperti berikut.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "order_tool",
  "description": "order bigquery connector tool",
  "createTime": "2025-06-03T19:29:55.896178942Z",
  "updateTime": "2025-06-03T19:29:55.896178942Z",
  "connectorSpec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/order-bigquery-connector",
    "actions": [
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "LIST"
        }
      },
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "GET"
        }
      }
    ]
  },
  "displayName": "order bigquery connector tool"
}

Langkah berikutnya

Untuk mengetahui daftar lengkap alat Integration Connectors yang didukung Agent Assist, lihat daftar alat Dialogflow Connector.