OpenAPI 和整合連接器工具

您可以搭配使用 Agent Assist 功能、外部 API 和資料來源。 Google Cloud 提供 OpenAPI 和整合連接器工具，方便您整合 Agent Assist。

OpenAPI 工具

OpenAPI 工具可讓 Agent Assist 功能與外部 API 連結。這項連結可讓 Agent Assist 功能讀取及寫入多個來源的資訊。如要建立 OpenAPI 工具，您必須提供 OpenAPI 結構定義，說明要連結的外部 API。

Integration Connectors 工具

使用整合連接器連結 Google Cloud 各種資料來源。連接器工具可讓 Agent Assist 功能使用整合連接器，讀取及寫入這些資料來源。

事前準備

如要設定環境來建立 OpenAPI 和 Integration Connectors 工具，請輸入專案 ID 和區域，然後執行下列程式碼。

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" "$@"
}

建立 OpenAPI 工具

如要使用 OpenAPI 工具，請先要求建立工具，並儲存工具資源名稱。

步驟 1：要求建立工具

請按照下列步驟要求建立 OpenAPI 工具。

1. 請按照下列方式自訂程式碼：
   1. 在單一專案中，請使用在所有工具中不重複的 tool_key 值。
   2. 在 open_api_spec.text_schema 欄位中輸入自己的 OpenAPI 架構。

2. 執行下列自訂程式碼。

   $ 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
   

如果成功，API 會傳回新建立的工具，其中包含資源名稱，如下例所示。

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

步驟 2：儲存工具資源名稱

將工具資源名稱儲存在環境變數中，以供後續使用。以下是工具資源環境變數的範本範例。

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

使用 OpenAPI 工具的 AI 教練

您可以搭配 AI 輔導功能使用 OpenAPI 工具，從 Google Cloud外部存取額外資訊。接著，系統會根據外部資訊生成建議，協助聯絡中心服務專員。

步驟 1：建立產生器

以下範例會使用工具資源環境變數建立產生器。

$ 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

您應該會收到類似下列 AI 訓練教練生成器範例的回覆。

{
  "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"
  ]
}

儲存產生器資源名稱

將其儲存為環境變數，以供日後使用，如下列範例所示。

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

步驟 2：建立對話設定檔

執行下列程式碼來建立對話設定檔。

$ 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

您應該會收到類似以下的回覆。

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

儲存對話設定檔資源名稱

將這個名稱儲存為環境變數，如下列範例所示。

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

步驟 3：建立對話

執行下列程式碼來建立對話。

$ 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

您應該會收到類似以下的回覆。

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

儲存對話資源名稱

將這個名稱儲存為環境變數，以供後續使用。變數應採用下列格式。

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

步驟 4：建立使用者

執行下列程式碼來建立使用者。

$ 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

您應該會收到類似以下的回覆。

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

儲存使用者資源名稱

將使用者資源名稱儲存為環境變數，如下所示。

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

步驟 5：建立真人服務專員

執行下列程式碼來建立真人客服專員。

$ 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

您應該會收到類似以下的回覆。

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

儲存真人服務專員資源名稱

將真人服務專員資源名稱儲存為環境變數，如下所示。

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

步驟 6：傳送訊息給 AI 教練

執行下列程式碼，使用 AnalyzeContent 方法將文字傳送至 AI 教練。

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

步驟 7：驗證工具呼叫

執行下列程式碼，驗證工具呼叫。

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

您應該會收到類似以下的回覆。

[
  {
    "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"
    }
  }
]

步驟 8：(選用) 刪除資源

如要刪除您在先前步驟中建立的資源，請執行下列程式碼。

對話設定檔

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

產生者

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

OpenAPI 工具

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

建立 Integration Connectors 工具

您可以使用 Google Cloud 控制台設定整合連接器。請按照下列步驟，根據 BigQuery 連接器建立 Agent Assist Integration Connectors 工具。

步驟 1：建立 BigQuery 連接器工具

建立 Integration Connectors 工具前，請前往 Google Cloud 控制台，並建立 BigQuery Integration Connectors。

步驟 2：要求建立 Integration Connectors 工具

執行下列程式碼，要求建立工具。在 connector_spec.name 欄位中，請使用 BigQuery 連接器的資源名稱。

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

您應該會收到類似以下的回覆。

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

後續步驟

如需 Agent Assist 支援的整合連接器工具完整清單，請參閱 Dialogflow 連接器工具清單。