> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据连接器

> 通过 Integrations、MCP 或 Custom API 连接外部服务，并在 AI Agent Skills 中使用相应工具。

数据连接器让 AI Agent 能够使用外部服务提供的工具。只需配置一次连接，即可在 Skills 中为每个 Agent 添加所需的具体工具。

打开 **AI Agent > Data connectors**，查看和管理连接。

![Data connectors 页面，其中显示 Integrations、MCP 和 Custom API 标签页以及可用集成。](https://mintcdn.com/lchnan/RNoD5r5OXiTray6k/product-assets/english-help-2026-10-30/data-connectors-integrations.png?fit=max\&auto=format\&n=RNoD5r5OXiTray6k\&q=85\&s=f70d467e86e5027f147b3b063f161a36)

Open AI Agent > Data connectors to view Integrations, MCP servers, and Custom API connectors.

## 选择连接器类型

Data connectors 页面提供三种连接外部服务的方式：

| 类型 | 用途 |
| - | - |
| **Integrations** | 通过引导式授权流程连接受支持的服务。例如，Shopify Admin 提供订单、物流跟踪、退货和退款的只读工具。 |
| **MCP** | 连接 MCP 服务器，并让 AI Agent 能够使用该服务器提供的工具。 |
| **Custom API** | 当您需要连接自己的 API 时，创建向 HTTPS 端点发送的自定义 HTTP 请求。 |

选择相应标签页，搜索现有连接或配置新连接。

## 将连接器工具添加到 AI Agent Skill

连接服务后，并不会自动将所有可用工具添加到每个 AI Agent。请在 Skills 中选择各 Agent 可以使用的工具。

1. 打开要配置的 AI Agent。
2. 在 **Profile** 中找到 **Skills**，然后选择 **Manage**。
3. 创建 Skill 或打开现有 Skill。
4. 在 **Step-by-Step instructions** 中输入 **/**。
5. 展开相应的 **Integration**、**MCP** 或 **Data connectors** 分组，然后选择要插入的工具。
6. 说明何时使用该工具、需要收集哪些信息，以及如何处理工具返回的结果。
7. 保存 Skill，在 Preview 中进行测试，并在准备就绪后发布 AI Agent。

![AI Agent Skill 编辑器，其中显示包含 Shopify Admin 工具的斜杠命令菜单。](https://mintcdn.com/lchnan/RNoD5r5OXiTray6k/product-assets/english-help-2026-10-30/shopify-skill-command-menu.png?fit=max\&auto=format\&n=RNoD5r5OXiTray6k\&q=85\&s=beb0f5f6d2938e563088e177eca982c4)

Type / in Step-by-Step instructions, then select a tool from the connected Shopify Admin integration.

> [!TIP]
>
> 为每个连接器步骤清楚定义成功、无结果和失败时的处理方式。不要让 AI Agent 推断工具未返回的信息。

有关触发器、指令和测试的更多指导，请参阅 [AI Skills](https://docs.ycloud.com/zh/documentation/agents/ai-agent/ai-skills.md)。

## 示例：查询 Shopify 订单

此示例将创建一个 Skill，用于回答客户有关 Shopify 订单和物流的问题。

### 1. 连接 Shopify Admin

1. 前往 **AI Agent > Data connectors**。
2. 在 **Integrations** 标签页中打开 **Shopify Admin**，并完成授权流程。
3. 确认该集成显示 **Connected**。

Shopify Admin 提供以下只读工具：

* `find_orders`：根据客户提供的信息查找订单
* `get_order`：获取所选订单
* `get_order_fulfillments`：获取物流和履约详情
* `get_fulfillment_events`：获取物流跟踪事件
* `get_order_returns` 和 `get_return`：获取退货详情
* `get_order_refunds` 和 `get_refund`：获取退款详情

### 2. 创建 Skill

在 AI Agent 的 **Profile** 中，选择 **Skills** 下的 **Manage**，然后使用以下配置创建 Skill。

**Name**

> 查询 Shopify 订单

**Start trigger**

> 当客户询问 Shopify 订单、物流、退货或退款状态时使用此 Skill。请勿将其用于商品推荐、结账问题或修改订单的请求。

**Step-by-Step instructions**

1. 向客户询问识别订单所需的信息。
2. 输入 **/**，然后从 **Integration · Shopify Admin** 中插入 `find_orders`，用它查找匹配的订单。
3. 如果没有匹配订单或有多个订单匹配，请客户提供更多识别信息。不要猜测客户所指的订单。
4. 为匹配的订单插入并使用 `get_order`。
5. 如果客户询问物流，请插入并使用 `get_order_fulfillments`。需要物流跟踪事件详情时，使用 `get_fulfillment_events`。
6. 如果客户询问退货或退款，请插入相应的退货或退款工具。
7. 仅总结工具返回的信息。如果工具调用失败或无法获取所需信息，请说明无法确认结果，并在适当情况下转接人工。

> [!NOTE]
>
> 连接 Shopify Admin 后，上述工具名称会显示在 **/** 命令菜单中。请从该菜单选择命令，而不是以纯文本形式输入工具名称。

### 3. 发布前测试

请至少在 Preview 中测试以下情况：

* 客户信息匹配到一个订单
* 没有匹配订单
* 匹配到多个订单
* 无法获取履约或物流跟踪详情
* Shopify 工具返回错误
* 客户要求 Agent 修改订单，而只读的 Shopify Admin 集成无法执行此操作

## 创建 Custom API 连接器

如果希望 AI Agent Skill 调用您自己的 HTTPS API，请使用 Custom API 连接器。

在 **Custom API** 标签页中选择 **New data connector**。您还可以按名称搜索现有 Custom API 连接器，并按状态筛选。

![完整的 Data connectors 页面，其中包含搜索、状态筛选、现有连接器和 New data connector。](https://mintcdn.com/lchnan/6u8ntRayC38GXyQF/product-assets/english-help-context-2026-09-25/final-connector-list-annotated.svg?fit=max\&auto=format\&n=6u8ntRayC38GXyQF\&q=85\&s=1e69a488687c963b905ed5916ebd9b9c)

Open AI Agent > Data connectors, then select New data connector.

### 名称和描述

使用能够说明功能的名称，例如 `retrieve_order`。在描述中说明何时应使用该连接器以及它会返回什么内容。

![Data connector 的 About 步骤，其中名称和描述字段已突出显示。](https://mintcdn.com/lchnan/gXEJIQXV2JH2VUQJ/product-assets/english-help-2026-09-22/connector-about-annotated.svg?fit=max\&auto=format\&n=gXEJIQXV2JH2VUQJ\&q=85\&s=a57c6777577f87f55494f26d51d28eb2)

Describe the connector's purpose in About before configuring its API request. This draft has not been saved.

### 配置 API 请求

输入 HTTPS 端点并选择请求方法：

* **GET** 读取信息。
* **POST** 创建信息。
* **PUT** 替换或更新信息。
* **PATCH** 更新资源的一部分。
* **DELETE** 删除信息。

![Data connector 的 API connection 步骤，其中 HTTP 方法和 URL 已突出显示。](https://mintcdn.com/lchnan/gXEJIQXV2JH2VUQJ/product-assets/english-help-2026-09-22/connector-api-annotated.svg?fit=max\&auto=format\&n=gXEJIQXV2JH2VUQJ\&q=85\&s=5effb08c414cdb9ecc3bce86ed58e377)

Choose the HTTP method and enter the endpoint URL. This incomplete draft has not sent a request.

#### HTTP headers

选择 **Add header**，然后以键值对形式输入每个必需的 header。

![完整的 API connection 表单，其中显示 Content-Type 和 Accept 请求 header。](https://mintcdn.com/lchnan/6u8ntRayC38GXyQF/product-assets/english-help-context-2026-09-25/final-connector-headers-annotated.svg?fit=max\&auto=format\&n=6u8ntRayC38GXyQF\&q=85\&s=f23c6cb0a8f850aa38a904ed0d1900cf)

Select Add header and enter each header as a key-value pair. This example has not been saved or sent.

#### Request body

对于需要发送数据的请求，请输入有效的 JSON request body，其中应包含 API 所需的字段。

![Data connector 页面滚动到 POST JSON request body 的位置。](https://mintcdn.com/lchnan/6u8ntRayC38GXyQF/product-assets/english-help-context-2026-09-25/final-connector-body-annotated.svg?fit=max\&auto=format\&n=6u8ntRayC38GXyQF\&q=85\&s=5099ae99db2d135e6253c53ecefb9937)

Enter valid JSON in Request Body. This fictional order example has not been sent.

### 测试响应

选择 **Test request**，确认连接器返回预期响应。

> [!WARNING]
>
> **测试会发送真实的 API 请求。** POST、PUT、PATCH 或 DELETE 请求可能会创建、更改或删除数据。请尽可能在安全环境中测试，或先使用只读 GET 请求。

![Test response 步骤，其中显示 Test Request 和已禁用的 Set live 按钮。](https://mintcdn.com/lchnan/6u8ntRayC38GXyQF/product-assets/english-help-context-2026-09-25/final-connector-test-entry-annotated.svg?fit=max\&auto=format\&n=6u8ntRayC38GXyQF\&q=85\&s=087754abdc3b082833f41e0822a3261c)

Select Test Request to run the configured API call. No request has been run in this example.

### 将连接器设为 live

测试成功后，选择 **Set live**。设为 live 的 Custom API 连接器可以从 Skill 指令中的 **/** 命令菜单中选择。

如需停止使用 Custom API 连接器，请打开该连接器并选择 **Set to draft**，或在连接器列表中关闭其状态。将连接器移至 draft 之前，请检查并解决列出的所有依赖项。

![完整的 Data connectors 列表，其中显示现有 live 连接器的 Status 开关。](https://mintcdn.com/lchnan/6u8ntRayC38GXyQF/product-assets/english-help-context-2026-09-25/final-connector-status-annotated.svg?fit=max\&auto=format\&n=6u8ntRayC38GXyQF\&q=85\&s=36fb2456c31e1e068179cc06e978feed)

Use the Status switch in the list to move a live connector to draft. The switches shown here have not been changed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.