OpenAPI 和 Integration Connectors 工具

您可以将 Agent Assist 功能与外部 API 和数据源搭配使用。 Google Cloud 提供了 OpenAPI 和 Integration Connectors 工具，以方便您进行 Agent Assist 集成。

OpenAPI 工具

借助 OpenAPI 工具，您可以将 Agent Assist 功能与外部 API 连接起来。通过这种连接，Agent Assist 功能可以从多个来源读取和写入信息。如需创建 OpenAPI 工具，您必须提供一个 OpenAPI 架构，用于描述您要连接的外部 API。

Integration Connectors 工具

您可以使用 Integration Connectors 连接到各种数据源。 Google Cloud 借助连接器工具，Agent Assist 功能可以使用 Integration Connectors 读取和写入这些数据源。

准备工作

如需设置环境以创建 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. 在单个项目中，使用在所有工具中唯一的 tool_key 值。
2. 在 open_api_spec.text_schema 字段中输入您自己的 OpenAPI 架构。

运行以下自定义代码。

$ 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 教练

您可以将 OpenAPI 工具与 AI 教练功能搭配使用，以从外部访问额外信息 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 控制台设置Integration Connectors。请按照以下步骤基于 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 支持的 Integration Connectors 工具的完整列表，请参阅 Dialogflow 连接器工具列表。

OpenAPI 和 Integration Connectors 工具 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

OpenAPI 工具

Integration Connectors 工具

准备工作

创建 OpenAPI 工具

第 1 步：请求创建工具

第 2 步：保存工具资源名称

使用 OpenAPI 工具的 AI 教练

第 1 步：创建生成器

保存生成器资源名称

第 2 步：创建对话配置文件

保存对话配置文件资源名称

第 3 步：创建对话

保存对话资源名称

第 4 步：创建最终用户

保存最终用户资源名称

第 5 步：创建人工客服

保存人工客服资源名称

第 6 步：向 AI 教练发送文本

第 7 步：验证工具调用

第 8 步：（可选）删除资源

对话配置文件

生成器

OpenAPI 工具

创建 Integration Connectors 工具

第 1 步：创建 BigQuery 连接器工具

第 2 步：请求创建 Integration Connectors 工具

后续步骤

OpenAPI 和 Integration Connectors 工具