# 工具调用 — 为 3Chat Agent 配置自定义 MCP 工具 **URL:** \ **Category:** 使用指南\ **Tags:** mcp\ **Created:** [2025 年9 月 23 日 16:44 UTC](https://group.3chatai.cn/t/topic/112 "2025-09-23T16:44:06Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Zhiyu](https://avatars.discourse-cdn.com/v4/letter/z/96bed5/32.png) [@Zhiyu](https://group.3chatai.cn/u/Zhiyu)\ **Post date:** [2025 年9 月 23 日 16:44 UTC](https://group.3chatai.cn/t/topic/112/1 "2025-09-23T16:44:06Z")
定义 MCP 工具可将您企业外部系统的实时数据或操作能力（如订单系统、CRM、ERP、会员平台等）接入 3Chat Agent。这些能力可驱动 3Chat 在售前阶段执行 “智能营销 SOP” —— 主动引导留资与转化；在售后阶段化身 “业务专家” —— 精准执行退款、改约、积分发放等操作，全面提升客户留存与复购率。 # 💡 入门建议： 在传统的客服场景中，客服人员或销售团队常被问到一些协助客户处理复杂问题的咨询，例如： - “我的订单现在到哪了？” - “能帮我改一下收货地址吗？” - “我有 500 积分，能换什么？” - “帮我取消明天的预约” 这些问题往往需要调用 **外部系统数据或触发业务** 操作。然后，简单的问答智能体又无法仅通过知识库来回答实效性要求很高的问题。转接人工后，人工也需要查询很多平台才能完成一次客户问题的咨询，费时费力。 针对以上的难题，通过接入自定义 MCP 工具，3Chat Agent 可充分理解客户的需求自动完成这些操作，无需人工介入。 # 🧭 导航指引 登陆 3Chat 后台，您可通过以下路径配置 MCP 工具： 3Chat Agent \> MCP \> 工具调用 # ⚙ 快速操作指导 ## 前置准备工作 1. 思考需要 3Chat Agent 协助客户处理哪些业务操作和访问哪些外部数据 - 开放接口(OpenApi)。 2. 保证提供给 3Chat Agent 使用的外部开放接口的执行性能，默认的超时时长 60秒。超过此时间，3Chat Agent 会认定请求超时。 3. 为保证 3Chat Agent 可以安全可信的调用外部的开放接口，需要登陆对应的外部系统，获取有效的访问认证授权。具体操作参考：[创建外部系统的认证授权（Token）](https://group.3chatai.cn/t/topic/111) 。 ## 配置自定义 MCP 工具 > 以获取Shopify上的订单物流信息为例 首先，通过导航指引，[3Chat Agent] - [MCP] - [工具调用]进入工具调用页面。在工具列表的右上方点击添加操作，进入工具配置页面。 ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/b355997a09e4781ef19562818434a21183c79f93.png) ### 步骤 1：填写工具的基本信息 需要定义工具的名称。提供工具描述，说明工具的作用以及 3Chat Agent 在什么时候需要使用此工具。 ```auto getOrderDetail 使用此工具调取客户订单的详细信息。该工具提供客户的所有订单的详情，包括订单状态，发货状态，购买的商品，收货地址等信息。 ``` ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/7d74e7ec09e12dbfdb9994f64304d82a0fa73c4f.jpeg) #### 👍 工具描述建议 - 要足够清晰 清楚的说明何时使用此工具，以及它应该提供的详细的信息 - 建议示例：使用此工具获取客户订单的详细信息，获取到的信息可以帮助排查与订单相关的问题。工具将提供客户的所有订单详情，如订单状态、购买的商品、收货地址、物流跟踪信息或其他相关订单信息。 - 不建议的示例：使用此数据连接器获取订单信息。 #### 👍 工具描述建议 - 避免使用代词 避免使用 “我们”、“他们” 等代词，应该替换成明确的专有名词，例如公司的名字，外部平台的名字。 - 建议的示例：使用此工具获取客户在 Shopify 店铺 3Chat 中的所有订单信息。 - 不建议的示例：使用此工具获取客户在我们店铺的订单信息。 #### 👍 工具描述建议 - 场景要具体 描述使用工具的场景场景 - 建议示例：使用此工具查询未解决的问题，例如客户想了解问题前的处理状态、是否已经解决，处理后是否能保证系统能恢复工作性能等 - 不建议示例：使用此工具查询未解决的问题 #### 👍 工具描述建议 - 适当提供以下客户的常用短语 参考客户在过往对话中表述问题的方式，并在描述中加入他们常用的关键词和短语。 ### 步骤 2：配置请求信息 - 填写填写您的外部系统接口地址，为了保证数据安全，我们会强制您使用 HTTPS 地址。选择正确的工具执行方式。目前支持 GET、POST、PUT 和 DELETE 四种。 ```auto https://3chat-ai-demo.myshopify.com/admin/api/2025-07/graphql.json ``` ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/82af80ed676fafebc33d7029de31e3c3bd6f9d66.png) - 根据您填写的 HTTPS 接口地址的要求，选择一个已填写的认证授权。选择的 **认证令牌** 会在处理 Headers 时 **默认添加参数名 Authentication** 。 - 定义 3Chat Agent 在使用工具前需要收集的数据信息，在这里定义的所有参数，都需要在 HTTPS 请求地址或者请求体中使用，具体的语法是 “{{data\_name}}”。其中： - 未完整填写参数名、数据类型和参数描述的数据，会在状态列中显示 “未定义”，提醒您完成填写。 - 已完整填写 3 个参数信息但未在请求地址或请求体中使用的数据，会在状态列中显示 “未使用”，提醒您使用此参数。 - 当且仅当所有数据状态为 “已使用” 且请求体 JSON 格式合法时，才允许执行才一步操作。 - 如果工具不需要收集任何信息即可被 3Chat Agent 使用，可以不定义收集参数。 ```auto email，字符串，客户邮箱 ``` ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/598ecddeb7031a5643994c44c7c06f2bb1b29541.jpeg) - 添加必要的请求头参数，如果 HTTPS 接口要求的认证令牌需要指定除 “Authentication” 以外的其他的参数名，可以在请求头参数中填写。 以下token仅作测试使用，可能随时过期失效；建议生成自己的token。 ```auto Content-Type:application/json X-Shopify-Access-Token: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 ``` ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/164a36106a8ee84b652c5483a712cd31ea09daac.jpeg) - 填写满足 JSON 格式的请求体，在请求体中可以为 HTTPS 接口请求体中每个参数的定义赋值。支持指定已定义的收集参数，默认值或者 3Chat 的主数据标准字段和自定义字段，如 “联系人” 等。 ```auto { "query": "query OrdersByEmail($q: String!) { orders(first: 50, query: $q, sortKey: CREATED_AT, reverse: true) { edges { node { id name createdAt email displayFulfillmentStatus fulfillments(first: 10) { id status displayStatus createdAt inTransitAt deliveredAt trackingInfo { company number url } } } } pageInfo { hasNextPage endCursor } } }", "variables": { "q": "email:'{{email}}'" } } ``` ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/80f143eccb9ee998d575e6eab380ea3fe63b996a.jpeg) - 当同时满足以下两个条件时，可以执行下一步操作：响应测试 - 未指定收集参数或定义的收集参数都已使用 - 请求体 JSON 格式合法 ### 步骤 3：响应测试 响应测试用于帮助用户验证请求配置是否正确，提供实时响应和示例响应两种方式： **第一种：实时响应** 。适用于现有的成熟 HTTPS 接口，通过实际的接口请求获取真实的响应结构 **第二种：示例响应** 。适用于开发中的 HTTPS 接口，可以先完成工具配置，和接口同步测试验证 #### 3.1 实时响应方式 如果在请求体或者 HTTPS 请求地址中有指定收集参数或主数据变量，需要在执行接口测试操作前指定参数值。完成请求参数赋值后，点击接口测试操作，获取接口返回结构。需要注意：接口测试会真实执行接口，在测试前请您保证接口访问的数据是测试数据，不要影响您的真实业务数据。 示例参数： ```auto email:zhang.zhiyu@xinheyun.com ``` 返回值： ```auto { "data": { "orders": { "edges": [ { "node": { "id": "gid://shopify/Order/10194884526372", "name": "#1001", "createdAt": "2025-09-24T03:45:45Z", "email": "zhang.zhiyu@xinheyun.com", "displayFulfillmentStatus": "PARTIALLY_FULFILLED", "fulfillments": [ { "id": "gid://shopify/Fulfillment/5867516100900", "status": "SUCCESS", "displayStatus": "FULFILLED", "createdAt": "2025-09-24T05:54:15Z", "inTransitAt": null, "deliveredAt": null, "trackingInfo": [ { "company": "SF Express", "number": "SF3237923216655", "url": "https://www.sf-express.com/we/ow/chn/en/waybill/waybill-detail/SF3237923216655" } ] }, { "id": "gid://shopify/Fulfillment/5867458003236", "status": "CANCELLED", "displayStatus": "CANCELED", "createdAt": "2025-09-24T04:23:45Z", "inTransitAt": null, "deliveredAt": null, "trackingInfo": [ { "company": "SF Express", "number": "SF0288599313823", "url": "https://www.sf-express.com/we/ow/chn/en/waybill/waybill-detail/SF0288599313823" } ] }, { "id": "gid://shopify/Fulfillment/5867455840548", "status": "CANCELLED", "displayStatus": "CANCELED", "createdAt": "2025-09-24T04:19:06Z", "inTransitAt": null, "deliveredAt": null, "trackingInfo": [ { "company": "Amazon Logistics", "number": "188888111", "url": "https://track.amazon.com/tracking/188888111" } ] } ] } } ], "pageInfo": { "hasNextPage": false, "endCursor": "eyJsYXN0X2lkIjoxMDE5NDg4NDUyNjM3MiwibGFzdF92YWx1ZSI6MTc1ODY4NTU0NTAwMH0=" } } }, "extensions": { "cost": { "requestedQueryCost": 23, "actualQueryCost": 5, "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1995, "restoreRate": 100 } } } } ``` ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/b5329d9aac979076b1c392d165d14566ea5d1672.png) #### 3.2 示例响应方式 可直接填写响应体的 JSON 结构，请保证填写的语法正确。 ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/834d9a6919700e44347492dbe1b42206c3824122.png) 当响应示例中的 JSON 格式语法正确时，可以执行下一步：响应数据映射 ### 步骤 4：响应数据映射 此步骤用于配置响应结构中的参数映射和 3Chat Agent 的可访问性 1. 当完成接口测试或者手动填写响应结构后，自动提取响应体 JSON 结构中的所有响应参数的结构，创建响应参数列表。参数名中保留了原有响应体中的嵌套层级。 ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/381f0a6c7f4c7cbc91305f2ad18fe14e9f85e327.png) 1. 按需对响应参数的配置转换规则：在数据行尾，点击 **编辑** 按钮进入配置窗口。 | 映射示例1: trackingInfo.company | 映射示例2: trackingInfo.number | | --- | --- | | ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/63fc8d6f4a53e56dfc1c651d5547f5e26238f1df.png) | ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/330fa7f3d8e58aa03c8b97ea14381c817fa46627.png) | - 响应参数名：响应参数的参数名 (Key)，保留原始 JSON 结构中的层级 - 示例响应值：响应体结构中获取的响应参数值 - 映射参数名：3Chat Agent 可见的参数名，默认值为原响应体的参数名。 - 数据类型：3Chat Agent 可见的数据类型，默认值为原响应体的参数类型。可根据实际情况指定参数类型转换。 - 可访问：标识 3Chat Agent 是否对此响应参数可见 1. 映射修改后的结果如下表所示 | 映射前 | 映射后 | | --- | --- | | ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/83dac85dccc4c8ae469b7fa51eb071698ae4104e.png) | ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/0391c5549d70b38883452929e739932546cb9c5e.png) | #### 👍 配置参数转换的建议 | 建议 | 效果 | | --- | --- | | 当响应参数的命名无法真实表达字段含义时，可以修改成业务友好的参数名。例如：“abc” : “O-250823-001”，表达订单编号，建议指定映射参数名 “orderCode”。 | | | **响应参数值转换 String** 当响应参数值通过数字或业务不友好的字符串表达某些状态时，3Chat Agent 无法通过数字来推测具体的状态描述例如：订单状态：“orderStatus” : 5，需要指定 5 = “已发货”。“orderStatus” : “SHIP”，需要指定 SHIP = “已发货” | ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/dc4150815e70dafe02a278bc3736be3c49bffbdb.png) | | 当 **响应参数通过时间戳的格式** 表达一个具体的时间时，3Chat Agent 无法通过读取时间戳来获取实际时间，需要指定转换类型为 Datetime，把时间戳转换为标准 UTC 时间。 | ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/117d26ae0d25bd2ac1f8ae008795eae33131702c.png) | ## 保存并运行工具 当完成上述配置后，点击保存数据并运行此工具，3Chat Agent 即可在生产环境使用此工具处理客户的咨询。当不需要此工具被 3Chat Agent 访问时，操作暂停停止此工具即可。 ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/eb0b712abd0fa9ae2f67570edd5a0b0babd01868.png) # 在AI任务中让 3Chat Agent 执行工具调用 接入 MCP（Model Context Protocol）标准协议，3Chat Agent 能够非常灵活的调用已创建并运行的工具。只需要您使用 AI任务[[3Chat AI任务功能介绍](https://group.3chatai.cn/t/topic/82)] 功能，清晰的告诉 3Chat Agent 什么时候该 “伸手” 做什么事情即可。 在 AI Task 的执行步骤中，您需要描述业务流程规则，告诉 3Chat Agent 两部信息： - **条件** （什么时候需要做什么事）； ```auto 当用户询问订单发货状态时 ``` - **动作** （具体要用哪个 MCP 工具） ```auto 如果用户输入或上下文中有邮箱 → 调用 {{tool.update.visitor.email}} 记录邮箱 如果没有，则礼貌性的询问“您的email是多少？方便我查询订单状态” 如果{{var.visitor.email}}不为空，则调用工具getOrderDetail。从返回值中，找到‘物流公司’和‘物流单号’，返回给用户。 ``` 我们给这个Task命名为”返回订单物流信息“ ![image](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/333f0fb4177b1180c4b587af96f9e4920b42ba22.png) # 成果验收 1. 当用户询问订单到哪里时，触发AI任务，即”返回订单物流信息“； 2. AI任务因为没有识别到邮箱，所以主动询问用户； 3. 用户回复邮箱之后，Agent调用MCP工具，成功返回物流信息。 ![IMG_0509](https://canada1.discourse-cdn.com/flex012/uploads/x3chat/original/1X/b869f8ec6c305b37b443eb85d7b92f5ebcc6ca15.png)