Interacting with API

几乎所有的网络应用程序都依赖于RESTful API。使大型语言模型（LLM）能够与它们交互，可以扩大其实际应用范围。

本教程展示了如何通过工具调用使用LLM进行API调用。

先决条件 - 示例事件管理服务器

我们将使用一个简单的事件管理服务器，并展示如何与之交互。

/// 译文内容：
---
根据上面的信息，执行如下指令：
缺失译文，请检查输入
const express = require('express');；
const { v4: uuidv4 } = require('uuid');；

const app = express();；
const PORT = process.env.PORT || 5566;；

// 中间件
app.use(express.json());；

// 模拟数据库 - 内存存储
let events = [
  {
    id: '1',，
    名称：'2024年科技大会'，
    日期：'2024-06-15T09:00:00Z'，
    地点：加利福尼亚州旧金山
  },
  {
    id: '2',，
    名称：'音乐节'，
    日期：'2024-07-20T18:00:00Z'，
    地点：'德克萨斯州奥斯汀'
  },
  {
    id: '3',，
    名称：'艺术展开幕'，
    日期：'2024-05-10T14:00:00Z'，
    地点：纽约州纽约市
  },
  {
    id: '4',，
    名称：'创业交流活动'，
    日期：'2024-08-05T17:30:00Z'，
    地点：'华盛顿州西雅图'
  },
  {
    id: '5',，
    名称：'美食与美酒品鉴'，
    日期：'2024-09-12T19:00:00Z'，
    地点：'加利福尼亚州纳帕谷'
  }
];

// 用于验证事件数据的辅助函数
const 验证事件 = (事件数据) => {
  const 必填项 = ['姓名', '日期', '地点'];；
  const 缺失项 = required.filter(field => !eventData[field]);；
  
  如果 (missing.length > 0) {
    返回 { valid: false, message: `缺少必填字段：${missing.join(', ')}` };；
  }
  
  // 基本日期验证
  常量 `dateRegex` 定义了一个正则表达式，用于匹配符合特定格式的日期时间字符串。该格式为：`yyyy-mm-ddThh:mm:ss[.ns]Z`，其中 `yyyy` 表示年份，`mm` 表示月份，`dd` 表示日期，`hh` 表示小时，`mm` 表示分钟，`ss` 表示秒，`ns` 表示纳秒（可选），`Z` 表示时区（可选）；
  如果 (!dateRegex.test(eventData.date)) {
    返回 { valid: false, message: '日期必须采用 ISO 8601 格式（YYYY-MM-DDTHH:mm:ssZ）' };；
  }
  
  返回 { valid: true };；
};

// GET /events - 列出所有事件
app.get('/events', (req, res) => {
  res.status(200).json(events);；
});

// POST /events - 创建一个新事件
app.post('/events', (req, res) => {
  const 验证结果 = 验证事件(req.body);；
  
  如果 (!validation.valid) {
    返回状态码400，并返回JSON格式的数据，其中包含错误信息：validation.message；
  }
  
  const newEvent = {
    id: req.body.id || uuidv4(),，
    名称：req.body.name，
    日期：req.body.date，
    位置：req.body.location
  };
  
  将新事件（newEvent）推入事件列表（events）；
  res.status(201).json(newEvent);；
});

// GET /events/{id} - 根据ID检索事件
app.get('/events/:id', (req, res) => {
  const event = events.find(e => e.id === req.params.id);；
  
  如果 (!event) {
    返回状态码404，并返回JSON格式的数据，数据中包含错误信息“未找到事件”；
  }
  
  响应状态码为200，返回JSON格式的事件数据；
});

// DELETE /events/{id} - 根据ID删除事件
app.delete('/events/:id', (req, res) => {
  const eventIndex = events.findIndex(e => e.id === req.params.id);；
  
  如果 (eventIndex === -1) {
    返回状态码404，并返回JSON格式的数据，其中包含错误信息“事件未找到”；
  }
  
  events.splice(eventIndex, 1);；
  响应状态码为204，发送响应；
});

// PATCH /events/{id} - 根据ID更新事件的详细信息
app.patch('/events/:id', (req, res) => {
  const eventIndex = events.findIndex(e => e.id === req.params.id);；
  
  如果 (eventIndex === -1) {
    返回状态码404，并返回JSON格式的数据，其中包含错误信息“未找到事件”；
  }
  
  const 验证结果 = 验证事件(req.body);；
  
  如果 (!validation.valid) {
    返回响应状态码400，并返回JSON格式的数据，其中包含错误信息：validation.message；
  }
  
  // 更新事件
  events[eventIndex] = {
    ...events[eventIndex]，
    名称：req.body.name，
    日期：req.body.date，
    位置：req.body.location
  };
  
  响应状态码为200，返回JSON格式的事件数据（events[eventIndex]）；
});

// 错误处理中间件
app.use((err, req, res, next) => {
  console.error(err.stack);；
  响应状态码为500，JSON格式返回错误信息：{ error: '出错了！' }；
});

// 404 错误处理程序
应用使用((请求, 响应) => {
  响应状态码为404，JSON格式的错误信息为：{ error: 'Endpoint not found' }；
});

// 启动服务器
app.listen(PORT, () => {
  console.log(`事件管理API服务器正在端口${PORT}上运行`);；
  控制台输出(`Available endpoints:`);；
  console.log(`  GET    /events      - 列出所有事件`);；
  控制台输出：`POST /events - 创建一个新事件`；
  console.log(`  GET    /events/{id} - 根据ID获取事件`);；
  console.log(`  PATCH  /events/{id} - 根据ID更新事件`);；
  console.log(`  DELETE /events/{id} - 根据ID删除事件`);；
});

module.exports = app;；

---

请求工具

有四种请求工具可供使用。这使得LLM能够在必要时调用GET、POST、PUT、DELETE工具。

步骤1：添加起始节点

开始节点是流程的入口点

步骤2：添加智能体节点

接下来，添加一个智能体节点。在此设置中，代理配置了四种主要工具：GET、POST、PUT和DELETE。每种工具都设置为执行特定类型的API请求。

工具1：GET（检索事件）

• **目的：**从API获取事件列表或特定事件。

• 配置输入：

  • URL：http://localhost:5566/events

  • 名称： get_events

  • 描述： 描述何时使用此工具。例如：“当您需要获取事件时，请使用此工具。”

  • 头信息：（可选）添加任何所需的HTTP头信息。。

  • 查询参数模式（Query Params Schema）：API的JSON模式，使大型语言模型（LLM）能够了解URL结构，以及生成哪些路径和查询参数。例如：

    {
      "id": {
        "type": "字符串",，
        "in": "path",，
        "description": "要获取的物品的ID。/:id"
      },
      "limit": {
        "type": "字符串",，
        "in": "query",，
        "description": "限制获取的项目数量。?limit=10"
      }
    }

工具2：POST（创建事件）

• **目的：**在系统中创建一个新事件。

• 配置输入：

  • URL： http://localhost:5566/events

  • 名称：create_event

  • 描述：当您想要创建新事件时，请使用此选项。

  • 头信息：（可选）添加任何所需的HTTP头信息。

  • Body：硬编码的主体对象，将覆盖由大型语言模型（LLM）生成的主体 Body Schema：API请求体的JSON模式，它使LLM（大型语言模型）知道如何自动生成正确的JSON请求体。例如：

    {
      "name": {
        "type": "字符串",，
        “required”：true，
        "description": "事件名称"
      },
      "date": {
        "type": "字符串",，
        “required”：true，
        "description": "活动日期"
      },
      "location": {
        "type": "字符串",，
        “required”：true，
        “description”：“事件地点”
      }
    }

工具3：PUT（更新事件）

• **目的：**更新现有活动的详细信息。

• 配置输入：

  • URL： http://localhost:5566/events

  • 名称：update_event

  • 描述：当您想要更新事件时，请使用此功能。

  • 头信息：（可选）添加任何所需的HTTP头信息。

  • Body：硬编码的主体对象，将覆盖由大型语言模型（LLM）生成的主体 Body Schema：API请求体的JSON模式，它使LLM能够知道如何自动生成正确的JSON请求体。例如：

    {
      "name": {
        "type": "字符串",，
        “required”：true，
        "description": "事件名称"
      },
      "date": {
        "type": "字符串",，
        “required”：true，
        "description": "活动日期"
      },
      "location": {
        "type": "字符串",，
        “required”：true，
        "description": "活动地点"
      }
    }

工具4：删除（删除事件）

• **目的：**从系统中移除一个事件。

• 配置输入：

  • URL： http://localhost:5566/events

  • 名称：delete_event

  • 说明：当您需要删除事件时，请使用此功能。

  • 头信息：（可选）添加任何所需的HTTP头信息。。

  • 查询参数模式（Query Params Schema）：API的JSON模式，使大型语言模型（LLM）能够了解URL结构，以及应生成哪些路径和查询参数。例如：

    {
      "id": {
        "type": "字符串",，
        “required”：true，
        "in": "path",，
        "description": "要删除的项目的ID。/:id"
      }
    }

智能体如何使用这些工具

• 智能体可以根据用户的请求或流程的逻辑动态选择要使用的工具。

• 每个工具都对应特定的HTTP方法和端点，并具有明确定义的输入模式。

• 智能体利用大型语言模型（LLM）来解释用户输入，填写所需参数，并发出适当的API调用。

当然！以下是一些交互示例，供您参考，包括示例用户查询以及每种查询对应的预期行为，这些行为与相应的工具（GET、POST、PUT、DELETE）相关联：

交互示例

1. 检索事件（GET）

示例查询：

“显示所有即将发生的事件。”

预期行为：

• 智能体选择GET工具。

• 它向http://localhost:5566/events发送一个GET请求。

• 智能体向用户返回所有事件的列表。

---

示例查询：

“获取ID为12345的事件详情。”

预期行为：

• 智能体选择GET工具。

• 它向http://localhost:5566/events/12345发送一个GET请求。

• 智能体返回了ID为“12345”的事件的详细信息。

---

2. 创建新事件（POST）

示例查询：

“在2024年7月15日于科技厅举办一场名为‘AI大会’的新活动。”

预期行为：

• 智能体选择POST工具。

• 它向http://localhost:5566/events发送一个POST请求，请求体内容如下：

  {
    "name": "人工智能会议",，
    "日期"："2024-07-15"，
    "位置"："技术大厅"
  }

• 智能体确认事件已创建，并可能返回新事件的详细信息。

---

3. 更新事件（PUT）

示例查询：

“将2024年7月15日‘AI大会’的举办地点更改为‘主礼堂’。”

预期行为：

• 智能体选择PUT工具。

• 它向http://localhost:5566/events发送一个带有更新后事件详细信息的PUT请求：

  {
    "name": "人工智能会议",，
    "日期"："2024-07-15"，
    “地点”：“主礼堂”
  }

• 智能体确认事件已更新。

---

4. 删除事件（DELETE）

示例查询：

“删除ID为12345的事件。”

预期行为：

• 智能体选择 DELETE 工具。

• 它向http://localhost:5566/events/12345发送一个DELETE请求。

• 智能体确认事件已删除。

完整流程

{"request": "GET /api/v1/users", "response": "200 OK"}

---

OpenAPI工具包

如果你只有几个API，那么这4个请求工具就非常好用，但想象一下，如果有数十个甚至数百个API，维护起来就会变得很困难。为了解决这个问题，Flowise提供了一个OpenAPI工具包，该工具包能够接收一个OpenAPI YAML文件，并将每个API解析为一个工具。OpenAPI规范（OAS）是一种普遍接受的标准，用于以机器可读取和解释的格式描述RESTful API的详细信息。

使用事件管理API，我们可以生成一个OpenAPI YAML文件：

/// 译文内容：
---
根据上面的信息，执行如下指令：
你是个专业的翻译，负责把英语内容翻译成中文内容，请帮我翻译一下原文内容
openapi: 3.0.0
信息：
  版本：1.0.0
  标题：事件管理API
  描述：用于管理事件数据的API

服务器：
  - 网址：http://localhost:5566
    描述：本地开发服务器

路径：
  /events:
    获取：
      摘要：列出所有事件
      操作ID：listEvents
      响应：
        '200':
          描述：事件列表
          内容：
            application/json：
              模式：
                类型：数组
                项目：
                  $ref: '#/components/schemas/Event'
    
    帖子：
      摘要：创建新事件
      操作ID：createEvent
      请求正文：
        必需：是
        内容：
          application/json：
            模式：
              $ref: '#/组件/模式/事件输入'
      响应：
        '201':
          描述：该事件已创建
          内容：
            application/json：
              模式：
                $ref: '#/组件/模式/事件'
        '400':
          描述：输入无效
          内容：
            application/json：
              模式：
                $ref: '#/components/schemas/Error'

  /events/{id}:
    参数：
      - 名称：id
        在：路径
        必需：是
        模式：
          类型：字符串
        描述：事件ID
    
    获取：
      摘要：根据ID检索事件
      操作ID：getEventById
      响应：
        '200':
          描述：该事件
          内容：
            application/json：
              模式：
                $ref: '#/组件/模式/事件'
        '404':
          描述：未找到事件
          内容：
            application/json：
              模式：
                $ref: '#/components/schemas/Error'
    
    补丁：
      摘要：根据ID更新事件的详细信息
      操作ID：updateEventDetails
      请求正文：
        必需：是
        内容：
          application/json：
            模式：
              $ref: '#/组件/模式/事件输入'
      响应：
        '200':
          描述：活动的详细信息已更新
          内容：
            application/json：
              模式：
                $ref: '#/组件/模式/事件'
        '400':
          描述：输入无效
          内容：
            application/json：
              模式：
                $ref: '#/components/schemas/Error'
        '404':
          描述：未找到事件
          内容：
            application/json：
              模式：
                $ref: '#/组件/模式/错误'
    
    删除：
      摘要：按ID删除事件
      操作ID：删除事件
      响应：
        '204':
          描述：该事件已被删除
        '404':
          描述：未找到事件
          内容：
            application/json：
              模式：
                $ref: '#/组件/模式/错误'

组件：
  模式：
    事件：
      类型：对象
      属性：
        id：
          类型：字符串
          描述：事件的唯一标识符
        名称：
          类型：字符串
          描述：事件的名称
        日期：
          类型：字符串
          格式：日期-时间
          描述：以ISO 8601格式表示的事件日期和时间
        位置：
          类型：字符串
          描述：活动地点
      所需：
        - 名称
        - 日期
        - 位置
    
    事件输入：
      类型：对象
      属性：
        名称：
          类型：字符串
          描述：事件的名称
        日期：
          类型：字符串
          格式：日期-时间
          描述：以ISO 8601格式表示的事件日期和时间
        位置：
          类型：字符串
          描述：活动地点
      要求：
        - 名称
        - 日期
        - 位置
    
    错误：
      类型：对象
      属性：
        错误：
          类型：字符串
          描述：错误信息

步骤1：添加起始节点

步骤2：添加智能体节点

接下来，添加一个智能体节点。在此设置中，智能体仅配置了一个工具——OpenAPI Toolkit

工具：OpenAPI Toolkit

• **目的：**从YAML文件中获取API列表，并将每个API转换为工具列表

• 配置输入：

  • **YAML文件：**OpenAPI的YAML文件

  • 直接返回：是否直接从API返回响应

  • 头信息：（可选）添加任何所需的HTTP头信息。。

  • 移除空参数：从解析后的参数中移除所有值为空的键

  • 自定义代码：自定义返回响应的方式

交互示例：

我们可以使用之前示例中的相同示例查询来对其进行测试：

---

按顺序调用API

从上面的示例中，我们已经看到了智能体如何动态调用工具并与API进行交互。在某些情况下，可能需要在某些操作之前或之后按顺序调用API。例如，您可能会从CRM中获取客户列表并将其传递给智能体。在这种情况下，您可以使用HTTP节点。

最佳实践

• 与应用程序编程接口（API）交互通常用于希望智能体获取最新信息的情况。例如，智能体可能会检索您的日历可用性、项目状态或其他实时数据。

• 在系统提示中明确包含当前时间通常很有帮助。Flowise提供了一个名为{{current_date_time}}的变量，用于检索当前日期和时间。这使得大型语言模型（LLM）能够感知当前时刻，因此，如果你询问自己今天的可用性，模型可以引用正确的日期。否则，它可能会依赖其最后一次训练的截止日期，这将返回过时的信息。例如：

你是个得力的助手。

今天的日期时间是{{current_date_time }}