AI创客项目开发教程 –AID101-1-3-04 – 后续工具调用实例

/* 
 * ESP32 AI平台调用 Follow-up Tool Calls 示例
 * 
 * 功能描述：
 * 本程序专门为ESP32-S3-DevKitC-1开发板设计，演示如何实现LLM模型的Follow-up Tool Calls功能。
 * 程序首先通过Tool Calls控制LED，然后将执行结果再次发送给LLM，获取更自然的用户反馈。
 * 
 * Follow-up Tool Calls流程：
 * 1. 第一次请求：发送用户指令，获取Tool Calls响应
 * 2. 执行Tool Calls：控制LED的开关或亮度
 * 3. 第二次请求：将Tool Calls响应和执行结果发送给LLM
 * 4. 获取自然语言反馈：LLM根据执行结果生成自然语言回复
 * 
 * 本程序支持的指令类型：
 * - 打开/关闭LED（如"打开LED"、"关闭LED"）
 * - 调节LED亮度（如"把LED调到亮度最大"、"将LED亮度调到中等"）
 * 
 * 作者：Taichi-Maker
 * 作者官网：http://ai.taichi-maker.com
 * 创建日期：2026年06月27日
 * 版本：1.1.7
 * 
 * 硬件要求：
 * - ESP32-S3-DevKitC-1开发板（内置一颗WS2812 LED，数据引脚连接到GPIO 48）
 * 
 * 所需软件库：
 * - FastLED库
 * - ArduinoJson库（版本7.0.0或更高）--用于处理JSON数据
 * 
 * 配置说明：
 * 1. 请先通过Arduino IDE的库管理器安装FastLED、ArduinoJson。
 * 2. 在my_info.h文件中填写您的Wi-Fi名称（ssid）和密码（password）。
 * 3. 在my_info.h文件中将ai_api_key替换为您从AI平台获取的有效API密钥（切勿泄露！）。
 * 4. 确保开发板已正确连接到电脑，并选择正确的开发板型号与端口。
 * 
 * 使用方法：
 * 1. 将本程序上传至ESP32-S3-DevKitC-1开发板。
 * 2. 打开串口监视器（波特率设置为115200）。
 * 3. 程序会自动连接Wi-Fi并发送用户指令给AI平台。
 * 4. 观察第一次Tool Calls响应和LED控制执行过程。
 * 5. 观察第二次请求和LLM生成的自然语言反馈。
 * 
 * 注意事项：
 * - 本例使用client.setInsecure()跳过了SSL证书验证，仅适用于测试环境；
 *   在生产环境中应使用有效证书以确保通信安全。
 * - 亮度级别为1-5级，其中1为最暗，5为最亮。
 * 
 * 兼容性说明：
 * 本程序专为ESP32-S3-DevKitC-1开发板设计，已在ESP32-S3-DevKitC-1开发板上测试通过。
 * 
 * 许可证：MIT License
 * 
 * 程序源：
 * 本程序源自太极创客团队精心开发的《AI创客项目开发教程》。该教程专为热爱科技创新、热衷于动手实践
 * 的创客爱好者与初学者量身打造，是一套完全免费、开源且注重实战的AIoT（人工智能物联网）入门学习资源。
 * 
 * 通过本教程，您可以系统地掌握从项目构思、方案设计、软硬件选型，到实际搭建、系统集成与调试优化的
 * 整个开发流程。
 * 您可以通过以下链接获得更多关于本教程的详细信息：
 * http://ai.taichi-maker.com/index.php/homepage/ai-tutorial/
 */
#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>
#include "my_info.h"

// 引入FastLED库
#include <FastLED.h>

// LED配置
#define DATA_PIN 48
#define NUM_LEDS 1
CRGB leds[NUM_LEDS];

String userCommand = "LED亮度调节为最大";

const char* ai_payload_first_template = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。"
    },
    {
      "role": "user",
      "content": "{{USER_COMMAND}}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "controlLEDOnOFF",
        "description": "控制LED的打开或关闭",
        "parameters": {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "description": "LED控制动作",
              "enum": ["on", "off"]
            }
          },
          "required": ["action"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "controlLEDBrightness",
        "description": "控制LED的亮度级别",
        "parameters": {
          "type": "object",
          "properties": {
            "level": {
              "type": "integer",
              "description": "亮度级别，1-5级，其中1为最暗，5为最亮",
              "minimum": 1,
              "maximum": 5
            }
          },
          "required": ["level"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "temperature": 0.1
})rawliteral";

const char* ai_payload_second_template = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。请根据Tool Calls的执行结果，提供友好的自然语言反馈。"
    },
    {
      "role": "user",
      "content": "{{USER_COMMAND}}"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "{{TOOL_CALL_ID}}",
          "type": "function",
          "function": {
            "name": "{{TOOL_CALL_NAME}}",
            "arguments": "{{TOOL_CALL_ARGUMENTS}}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "{{TOOL_CALL_ID}}",
      "content": "{{EXECUTION_RESULT}}"
    }
  ],
  "temperature": 0.1
})rawliteral";

WiFiClientSecure client;
HTTPClient https;

String firstToolCallResponse = "";
String firstToolCallId = "";
String firstToolCallName = "";
String firstToolCallArguments = "";
String toolExecutionResult = "";

void setup() {
  Serial.begin(115200);
  delay(1000);

  // 初始化FastLED
  FastLED.addLeds<WS2812, DATA_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(128);
  leds[0] = CRGB::White;
  FastLED.show();
  Serial.println("FastLED initialized successfully!");

  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println();

  client.setInsecure();
  client.setTimeout(15);

  Serial.println();
  Serial.println("---------- AI Platform Config ----------");
  Serial.print("AI Platform API Endpoint: ");
  Serial.print(ai_host);
  Serial.println(ai_endpoint);
  Serial.println();
  Serial.print("一切就绪，等待几秒钟，便于您观察板上LED状态.");
  delay(5000);

  Serial.println("========== Follow-up Tool Calls 示例开始 ==========");
  callAIPlatformFirst();
  callAIPlatformSecond();
  Serial.println("\n========== Follow-up Tool Calls 示例结束 ==========");
}

void loop() {
  delay(10);
}

// ==================== LED控制函数（FastLED版本） ====================

String controlLEDOnOFF(String action) {
  Serial.print("控制LED开关: ");
  Serial.println(action);
  
  String resultDescription = "";
  if (action == "on") {
    leds[0] = CRGB::White;
    FastLED.show();
    resultDescription = "LED已成功打开";
  } else if (action == "off") {
    leds[0] = CRGB::Black;
    FastLED.show();
    resultDescription = "LED已成功关闭";
  } else {
    resultDescription = "LED控制失败：无效的控制指令";
  }
  return resultDescription;
}

String controlLEDBrightness(int level) {
  Serial.print("控制LED亮度: 级别 ");
  Serial.println(level);
  
  String resultDescription = "";
  if (level >= 1 && level <= 5) {
    uint8_t brightness = map(level, 1, 5, 50, 255);
    FastLED.setBrightness(brightness);
    leds[0] = CRGB::White;
    FastLED.show();
    
    String levelDescription;
    switch (level) {
      case 1: levelDescription = "最暗"; break;
      case 2: levelDescription = "较暗"; break;
      case 3: levelDescription = "中等"; break;
      case 4: levelDescription = "较亮"; break;
      case 5: levelDescription = "最亮"; break;
    }
    resultDescription = "LED亮度已成功调节到" + levelDescription + "级别";
  } else {
    resultDescription = "亮度调节失败：无效的亮度级别";
  }
  return resultDescription;
}


/* 
 * -------------- 第一次向AI平台发送HTTPS请求的函数 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 构造完整的HTTPS请求URL（基于my_info.h中定义的主机、端口和路径）
 * 2. 设置请求头：Content-Type为application/json，Authorization为Bearer + API密钥
 * 3. 发送POST请求，携带包含Tool Call定义的JSON请求体
 * 4. 接收并打印HTTP响应状态码和响应内容
 * 5. 解析响应中的Tool Call参数并执行相应操作
 * 6. 存储Tool Calls响应信息，用于第二次请求
 */
void callAIPlatformFirst() {
  Serial.println("\n>>> 第一次请求：发送用户指令，获取Tool Calls响应...");

  // 构造Authorization请求头：格式为"Bearer <your-api-key>"
  String auth = "Bearer ";
  auth += ai_api_key;

  // 构造第一次请求的JSON体
  String firstPayload = buildFirstPayload();
  
  Serial.println("----- 第一次请求JSON -----");
  Serial.println(firstPayload);
  Serial.println("----- 请求JSON结束 -----");

  // 初始化HTTPS连接（使用client、主机名、端口、API路径）
  if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

    // 设置超时时间（毫秒）- 增加超时时间以处理更复杂的请求
    https.setTimeout(20000); // 20秒超时
    https.setConnectTimeout(10000); // 10秒连接超时

    Serial.println("HTTPS连接已初始化，发送第一次请求...");

    // 添加必要的HTTP请求头
    https.addHeader("Content-Type", "application/json");
    https.addHeader("Authorization", auth);

    // 发送POST请求，并获取HTTP状态码
    int httpCode = https.POST(firstPayload);

    if (httpCode > 0) {
      // 打印HTTP响应状态码（如200表示成功）
      Serial.printf("HTTP响应状态码: %d\n", httpCode);

      // 如果响应成功（HTTP 200 OK）
      if (httpCode == HTTP_CODE_OK) {
        // 获取完整的响应字符串
        String resp = https.getString();
        Serial.println("----- 第一次响应 -----");
        Serial.println(resp);  // 打印AI返回的完整JSON
        Serial.println("----- 响应结束 -----");
        
        // 存储第一次响应，用于第二次请求
        firstToolCallResponse = resp;
        
        // 解析Tool Call响应并执行操作
        parseToolCallResponse(resp);
      }
    } else {
      // 打印HTTP错误信息（如连接失败、超时等）
      Serial.printf("HTTP错误: %s\n", https.errorToString(httpCode).c_str());
      Serial.printf("错误代码: %d\n", httpCode);
    }

    // 结束本次HTTP会话，释放资源
    https.end();
  } else {
    // 如果无法建立HTTPS连接，打印错误提示
    Serial.println("无法连接到服务器");
  }
}

/* 
 * -------------- 第二次向AI平台发送HTTPS请求的函数 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 构造包含Tool Calls响应和执行结果的JSON请求体
 * 2. 设置请求头：Content-Type为application/json，Authorization为Bearer + API密钥
 * 3. 发送POST请求，携带包含对话历史和执行结果的JSON请求体
 * 4. 接收并打印HTTP响应状态码和响应内容
 * 5. 解析并显示LLM生成的自然语言反馈
 */
void callAIPlatformSecond() {
  Serial.println("\n>>> 第二次请求：发送Tool Calls响应和执行结果，获取自然语言反馈...");

  // 构造Authorization请求头：格式为"Bearer <your-api-key>"
  String auth = "Bearer ";
  auth += ai_api_key;

  // 构造第二次请求的JSON体
  String secondPayload = buildSecondPayload();
  
  Serial.println("----- 第二次请求JSON -----");
  Serial.println(secondPayload);
  Serial.println("----- 请求JSON结束 -----");

  // 初始化HTTPS连接（使用client、主机名、端口、API路径）
  if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

    // 设置超时时间（毫秒）
    https.setTimeout(20000); // 20秒超时
    https.setConnectTimeout(10000); // 10秒连接超时

    Serial.println("HTTPS连接已初始化，发送第二次请求...");

    // 添加必要的HTTP请求头
    https.addHeader("Content-Type", "application/json");
    https.addHeader("Authorization", auth);

    // 发送POST请求，并获取HTTP状态码
    int httpCode = https.POST(secondPayload);

    if (httpCode > 0) {
      // 打印HTTP响应状态码（如200表示成功）
      Serial.printf("HTTP响应状态码: %d\n", httpCode);

      // 如果响应成功（HTTP 200 OK）
      if (httpCode == HTTP_CODE_OK) {
        // 获取完整的响应字符串
        String resp = https.getString();
        Serial.println("----- 第二次响应 -----");
        Serial.println(resp);  // 打印AI返回的完整JSON
        Serial.println("----- 响应结束 -----");
        
        // 解析并显示自然语言反馈
        parseSecondResponse(resp);
      }
    } else {
      // 打印HTTP错误信息（如连接失败、超时等）
      Serial.printf("HTTP错误: %s\n", https.errorToString(httpCode).c_str());
      Serial.printf("错误代码: %d\n", httpCode);
    }

    // 结束本次HTTP会话，释放资源
    https.end();
  } else {
    // 如果无法建立HTTPS连接，打印错误提示
    Serial.println("无法连接到服务器");
  }
}

/* 
 * -------------- 构造第一次请求的JSON体 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用预定义的JSON模板（ai_payload_first_template）
 * 2. 替换模板中的占位符为实际值
 * 3. 返回完整的第一次请求JSON体
 * 
 * 这种方法使第一次请求的结构更加直观，便于学习者理解Tool Calls的实现
 * 
 * 返回值：
 * - String: 构造好的第一次请求JSON体
 */
String buildFirstPayload() {
  // 从模板开始构建请求体
  String payload = ai_payload_first_template;
  
  // 替换模板中的占位符
  payload.replace("{{USER_COMMAND}}", userCommand);
  
  return payload;
}

/* 
 * -------------- 构造第二次请求的JSON体 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用预定义的JSON模板（ai_payload_second_template）
 * 2. 解析第一次Tool Calls响应，提取关键信息
 * 3. 替换模板中的占位符为实际值
 * 4. 返回完整的第二次请求JSON体
 * 
 * 这种方法使第二次请求的结构更加直观，便于学习者理解Follow-up Tool Calls的实现
 * 
 * 返回值：
 * - String: 构造好的第二次请求JSON体
 */
String buildSecondPayload() {
  // 解析第一次Tool Calls响应
  DynamicJsonDocument firstDoc(4096);
  DeserializationError error = deserializeJson(firstDoc, firstToolCallResponse);
  
  if (error) {
    Serial.print("第一次响应JSON解析失败: ");
    Serial.println(error.c_str());
    return "";
  }
  
  // 从模板开始构建请求体
  String payload = ai_payload_second_template;
  
  // 准备替换的值
  String escapedArguments = firstToolCallArguments;
  // 转义参数字符串中的双引号，确保JSON格式正确
  escapedArguments.replace("\"", "\\\"");
  
  // 替换模板中的占位符
  payload.replace("{{USER_COMMAND}}", userCommand);
  payload.replace("{{TOOL_CALL_ID}}", firstToolCallId);
  payload.replace("{{TOOL_CALL_NAME}}", firstToolCallName);
  payload.replace("{{TOOL_CALL_ARGUMENTS}}", escapedArguments);
  payload.replace("{{EXECUTION_RESULT}}", toolExecutionResult);
  
  return payload;
}



/* 
 * -------------- 解析第一次Tool Call响应的函数--------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用ArduinoJson库解析JSON响应
 * 2. 检查响应中是否包含tool_calls字段
 * 3. 提取函数名称和参数
 * 4. 调用统一的LED控制函数执行操作
 * 5. 存储Tool Calls信息用于第二次请求
 */
void parseToolCallResponse(String jsonResponse) {
  // 解析JSON响应
  DynamicJsonDocument doc(4096);
  DeserializationError error = deserializeJson(doc, jsonResponse);
  
  if (error) {
    Serial.print("JSON解析失败: ");
    Serial.println(error.c_str());
    return;
  }
  
  // 检查是否有tool_calls
  if (doc.containsKey("choices") && doc["choices"].size() > 0) {
    JsonObject choice = doc["choices"][0];
    JsonObject message = choice["message"];
    
    if (message.containsKey("tool_calls") && message["tool_calls"].size() > 0) {
      JsonObject toolCall = message["tool_calls"][0];
      JsonObject function = toolCall["function"];
      String functionName = function["name"].as<String>();
      
      // 存储Tool Calls信息
      firstToolCallId = toolCall["id"].as<String>();
      firstToolCallName = functionName;
      firstToolCallArguments = function["arguments"].as<String>();
      
      Serial.print("检测到工具调用: ");
      Serial.println(functionName);
      Serial.print("Tool Call ID: ");
      Serial.println(firstToolCallId);
      Serial.print("Tool Call参数: ");
      Serial.println(firstToolCallArguments);
      
      if (functionName == "controlLEDOnOFF") {
        // 解析LED开关函数参数
        DynamicJsonDocument argsDoc(512);
        DeserializationError argsError = deserializeJson(argsDoc, firstToolCallArguments);
        
        if (argsError) {
          Serial.print("参数解析失败: ");
          Serial.println(argsError.c_str());
          return;
        }
        
        String action = argsDoc["action"].as<String>();
        
        Serial.print(">>> 第二步：执行Tool Calls，控制LED开关...");
        Serial.print("执行动作: ");
        Serial.println(action);
        
        // 调用LED开关控制函数并保存执行结果
        toolExecutionResult = controlLEDOnOFF(action);
        
      } else if (functionName == "controlLEDBrightness") {
        // 解析LED亮度函数参数
        DynamicJsonDocument argsDoc(512);
        DeserializationError argsError = deserializeJson(argsDoc, firstToolCallArguments);
        
        if (argsError) {
          Serial.print("参数解析失败: ");
          Serial.println(argsError.c_str());
          return;
        }
        
        int level = argsDoc["level"].as<int>();
        
        Serial.print(">>> 第二步：执行Tool Calls，控制LED亮度...");
        Serial.print("执行亮度调节: ");
        Serial.println(level);
        
        // 调用LED亮度控制函数并保存执行结果
        toolExecutionResult = controlLEDBrightness(level);
        
      } else {
        Serial.print("未知函数: ");
        Serial.println(functionName);
      }
    } else {
      // 没有tool_calls，可能是普通文本响应
      Serial.println("未检测到tool_calls");
      if (message.containsKey("content")) {
        String content = message["content"].as<String>();
        Serial.print("模型回复: ");
        Serial.println(content);
      }
    }
  }
}

/* 
 * -------------- 解析第二次响应的函数--------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用ArduinoJson库解析JSON响应
 * 2. 提取LLM生成的自然语言反馈
 * 3. 显示反馈内容
 */
void parseSecondResponse(String jsonResponse) {
  // 解析JSON响应
  DynamicJsonDocument doc(4096);
  DeserializationError error = deserializeJson(doc, jsonResponse);
  
  if (error) {
    Serial.print("第二次响应JSON解析失败: ");
    Serial.println(error.c_str());
    return;
  }
  
  // 提取并显示自然语言反馈
  if (doc.containsKey("choices") && doc["choices"].size() > 0) {
    JsonObject choice = doc["choices"][0];
    JsonObject message = choice["message"];
    
    if (message.containsKey("content") && !message["content"].as<String>().isEmpty()) {
      String content = message["content"].as<String>();
      Serial.println(">>> LLM自然语言反馈:");
      Serial.println(content);
    } else {
      Serial.println("LLM没有提供自然语言反馈");
    }
  } else {
    Serial.println("无法解析第二次响应");
  }
}

/*
========================================================================
 【附录】本程序实际发送的HTTP请求内容（供参考）
========================================================================

第一次请求：

POST /compatible-mode/v1/chat/completions HTTP/1.1
Host: dashscope.aliyuncs.com
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Length: [自动计算]

{
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。"
    },
    {
      "role": "user",
      "content": "LED亮度调节为最大"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "controlLEDOnOFF",
        "description": "控制LED的打开或关闭",
        "parameters": {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "description": "LED控制动作",
              "enum": ["on", "off"]
            }
          },
          "required": ["action"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "controlLEDBrightness",
        "description": "控制LED的亮度级别",
        "parameters": {
          "type": "object",
          "properties": {
            "level": {
              "type": "integer",
              "description": "亮度级别，1-5级，其中1为最暗，5为最亮",
              "minimum": 1,
              "maximum": 5
            }
          },
          "required": ["level"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "temperature": 0.1
}

第一次响应 
{
  "choices": [
    {
      "finish_reason": "tool_calls",
      "index": 0,
      "message": {
        "content": "",
        "role": "assistant",
        "tool_calls": [
          {
            "function": {
              "arguments": "{\"level\": 5}",
              "name": "controlLEDBrightness"
            },
            "id": "call_a4b2372b98b1492681255a",
            "index": 0,
            "type": "function"
          }
        ]
      }
    }
  ],
  "created": 1782587266,
  "id": "chatcmpl-e5b396d-99d7-4702-ac18-ed87f61aefb0f",
  "model": "qwen-flash",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 21,
    "prompt_tokens": 275,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 296
  }
}
第二次请求（Follow-up Tool Calls）：

POST /compatible-mode/v1/chat/completions HTTP/1.1
Host: dashscope.aliyuncs.com
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Length: [自动计算]

{
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。请根据Tool Calls的执行结果，提供友好的自然语言反馈。"
    },
    {
      "role": "user",
      "content": "LED亮度调节为最大"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_a4b2372b98b1492681255a",
          "type": "function",
          "function": {
            "name": "controlLEDBrightness",
            "arguments": "{\"level\": 5}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_a4b2372b98b1492681255a",
      "content": "LED亮度已成功调节到最亮级别"
    }
  ],
  "temperature": 0.1
}

第二次响应:

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "已将LED亮度调节到最大值，现在灯光最亮哦！✨",
        "role": "assistant"
      }
    }
  ],
  "created": 1782587267,
  "id": "chatcmpl-4dc8fbf-1fb-9af9d-904f4dd-60286b17cd",
  "model": "qwen-flash",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 16,
    "prompt_tokens": 90,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 106
  }
}
 * 
 * 说明：
 * - 第一次请求用于获取Tool Calls响应
 * - 第二次请求包含完整的对话历史，包括Tool Calls和执行结果
 * - 第二次请求中的tool角色消息提供了Tool Calls的执行结果
 * - LLM根据执行结果生成自然语言反馈，提供更友好的用户体验
 * ========================================================================
 */

/* 
 * ESP32 AI平台调用 Follow-up Tool Calls 示例
 * 
 * 功能描述：
 * 本程序专门为ESP32-S3-DevKitC-1开发板设计，演示如何实现LLM模型的Follow-up Tool Calls功能。
 * 程序首先通过Tool Calls控制LED，然后将执行结果再次发送给LLM，获取更自然的用户反馈。
 * 
 * Follow-up Tool Calls流程：
 * 1. 第一次请求：发送用户指令，获取Tool Calls响应
 * 2. 执行Tool Calls：控制LED的开关或亮度
 * 3. 第二次请求：将Tool Calls响应和执行结果发送给LLM
 * 4. 获取自然语言反馈：LLM根据执行结果生成自然语言回复
 * 
 * 本程序支持的指令类型：
 * - 打开/关闭LED（如"打开LED"、"关闭LED"）
 * - 调节LED亮度（如"把LED调到亮度最大"、"将LED亮度调到中等"）
 * 
 * 作者：Taichi-Maker
 * 作者官网：http://ai.taichi-maker.com
 * 创建日期：2026年06月27日
 * 版本：1.1.7
 * 
 * 硬件要求：
 * - ESP32-S3-DevKitC-1开发板（内置一颗WS2812 LED，数据引脚连接到GPIO 48）
 * 
 * 所需软件库：
 * - FastLED库
 * - ArduinoJson库（版本7.0.0或更高）--用于处理JSON数据
 * 
 * 配置说明：
 * 1. 请先通过Arduino IDE的库管理器安装FastLED、ArduinoJson。
 * 2. 在my_info.h文件中填写您的Wi-Fi名称（ssid）和密码（password）。
 * 3. 在my_info.h文件中将ai_api_key替换为您从AI平台获取的有效API密钥（切勿泄露！）。
 * 4. 确保开发板已正确连接到电脑，并选择正确的开发板型号与端口。
 * 
 * 使用方法：
 * 1. 将本程序上传至ESP32-S3-DevKitC-1开发板。
 * 2. 打开串口监视器（波特率设置为115200）。
 * 3. 程序会自动连接Wi-Fi并发送用户指令给AI平台。
 * 4. 观察第一次Tool Calls响应和LED控制执行过程。
 * 5. 观察第二次请求和LLM生成的自然语言反馈。
 * 
 * 注意事项：
 * - 本例使用client.setInsecure()跳过了SSL证书验证，仅适用于测试环境；
 *   在生产环境中应使用有效证书以确保通信安全。
 * - 亮度级别为1-5级，其中1为最暗，5为最亮。
 * 
 * 兼容性说明：
 * 本程序专为ESP32-S3-DevKitC-1开发板设计，已在ESP32-S3-DevKitC-1开发板上测试通过。
 * 
 * 许可证：MIT License
 * 
 * 程序源：
 * 本程序源自太极创客团队精心开发的《AI创客项目开发教程》。该教程专为热爱科技创新、热衷于动手实践
 * 的创客爱好者与初学者量身打造，是一套完全免费、开源且注重实战的AIoT（人工智能物联网）入门学习资源。
 * 
 * 通过本教程，您可以系统地掌握从项目构思、方案设计、软硬件选型，到实际搭建、系统集成与调试优化的
 * 整个开发流程。
 * 您可以通过以下链接获得更多关于本教程的详细信息：
 * http://ai.taichi-maker.com/index.php/homepage/ai-tutorial/
 */
#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>
#include "my_info.h"

// 引入FastLED库
#include <FastLED.h>

// LED配置
#define DATA_PIN 48
#define NUM_LEDS 1
CRGB leds[NUM_LEDS];

String userCommand = "LED亮度调节为最大";

const char* ai_payload_first_template = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。"
    },
    {
      "role": "user",
      "content": "{{USER_COMMAND}}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "controlLEDOnOFF",
        "description": "控制LED的打开或关闭",
        "parameters": {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "description": "LED控制动作",
              "enum": ["on", "off"]
            }
          },
          "required": ["action"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "controlLEDBrightness",
        "description": "控制LED的亮度级别",
        "parameters": {
          "type": "object",
          "properties": {
            "level": {
              "type": "integer",
              "description": "亮度级别，1-5级，其中1为最暗，5为最亮",
              "minimum": 1,
              "maximum": 5
            }
          },
          "required": ["level"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "temperature": 0.1
})rawliteral";

const char* ai_payload_second_template = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。请根据Tool Calls的执行结果，提供友好的自然语言反馈。"
    },
    {
      "role": "user",
      "content": "{{USER_COMMAND}}"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "{{TOOL_CALL_ID}}",
          "type": "function",
          "function": {
            "name": "{{TOOL_CALL_NAME}}",
            "arguments": "{{TOOL_CALL_ARGUMENTS}}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "{{TOOL_CALL_ID}}",
      "content": "{{EXECUTION_RESULT}}"
    }
  ],
  "temperature": 0.1
})rawliteral";

WiFiClientSecure client;
HTTPClient https;

String firstToolCallResponse = "";
String firstToolCallId = "";
String firstToolCallName = "";
String firstToolCallArguments = "";
String toolExecutionResult = "";

void setup() {
  Serial.begin(115200);
  delay(1000);

  // 初始化FastLED
  FastLED.addLeds<WS2812, DATA_PIN, GRB>(leds, NUM_LEDS);
  FastLED.setBrightness(128);
  leds[0] = CRGB::White;
  FastLED.show();
  Serial.println("FastLED initialized successfully!");

  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println();

  client.setInsecure();
  client.setTimeout(15);

  Serial.println();
  Serial.println("---------- AI Platform Config ----------");
  Serial.print("AI Platform API Endpoint: ");
  Serial.print(ai_host);
  Serial.println(ai_endpoint);
  Serial.println();
  Serial.print("一切就绪，等待几秒钟，便于您观察板上LED状态.");
  delay(5000);

  Serial.println("========== Follow-up Tool Calls 示例开始 ==========");
  callAIPlatformFirst();
  callAIPlatformSecond();
  Serial.println("\n========== Follow-up Tool Calls 示例结束 ==========");
}

void loop() {
  delay(10);
}

// ==================== LED控制函数（FastLED版本） ====================

String controlLEDOnOFF(String action) {
  Serial.print("控制LED开关: ");
  Serial.println(action);
  
  String resultDescription = "";
  if (action == "on") {
    leds[0] = CRGB::White;
    FastLED.show();
    resultDescription = "LED已成功打开";
  } else if (action == "off") {
    leds[0] = CRGB::Black;
    FastLED.show();
    resultDescription = "LED已成功关闭";
  } else {
    resultDescription = "LED控制失败：无效的控制指令";
  }
  return resultDescription;
}

String controlLEDBrightness(int level) {
  Serial.print("控制LED亮度: 级别 ");
  Serial.println(level);
  
  String resultDescription = "";
  if (level >= 1 && level <= 5) {
    uint8_t brightness = map(level, 1, 5, 50, 255);
    FastLED.setBrightness(brightness);
    leds[0] = CRGB::White;
    FastLED.show();
    
    String levelDescription;
    switch (level) {
      case 1: levelDescription = "最暗"; break;
      case 2: levelDescription = "较暗"; break;
      case 3: levelDescription = "中等"; break;
      case 4: levelDescription = "较亮"; break;
      case 5: levelDescription = "最亮"; break;
    }
    resultDescription = "LED亮度已成功调节到" + levelDescription + "级别";
  } else {
    resultDescription = "亮度调节失败：无效的亮度级别";
  }
  return resultDescription;
}


/* 
 * -------------- 第一次向AI平台发送HTTPS请求的函数 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 构造完整的HTTPS请求URL（基于my_info.h中定义的主机、端口和路径）
 * 2. 设置请求头：Content-Type为application/json，Authorization为Bearer + API密钥
 * 3. 发送POST请求，携带包含Tool Call定义的JSON请求体
 * 4. 接收并打印HTTP响应状态码和响应内容
 * 5. 解析响应中的Tool Call参数并执行相应操作
 * 6. 存储Tool Calls响应信息，用于第二次请求
 */
void callAIPlatformFirst() {
  Serial.println("\n>>> 第一次请求：发送用户指令，获取Tool Calls响应...");

  // 构造Authorization请求头：格式为"Bearer <your-api-key>"
  String auth = "Bearer ";
  auth += ai_api_key;

  // 构造第一次请求的JSON体
  String firstPayload = buildFirstPayload();
  
  Serial.println("----- 第一次请求JSON -----");
  Serial.println(firstPayload);
  Serial.println("----- 请求JSON结束 -----");

  // 初始化HTTPS连接（使用client、主机名、端口、API路径）
  if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

    // 设置超时时间（毫秒）- 增加超时时间以处理更复杂的请求
    https.setTimeout(20000); // 20秒超时
    https.setConnectTimeout(10000); // 10秒连接超时

    Serial.println("HTTPS连接已初始化，发送第一次请求...");

    // 添加必要的HTTP请求头
    https.addHeader("Content-Type", "application/json");
    https.addHeader("Authorization", auth);

    // 发送POST请求，并获取HTTP状态码
    int httpCode = https.POST(firstPayload);

    if (httpCode > 0) {
      // 打印HTTP响应状态码（如200表示成功）
      Serial.printf("HTTP响应状态码: %d\n", httpCode);

      // 如果响应成功（HTTP 200 OK）
      if (httpCode == HTTP_CODE_OK) {
        // 获取完整的响应字符串
        String resp = https.getString();
        Serial.println("----- 第一次响应 -----");
        Serial.println(resp);  // 打印AI返回的完整JSON
        Serial.println("----- 响应结束 -----");
        
        // 存储第一次响应，用于第二次请求
        firstToolCallResponse = resp;
        
        // 解析Tool Call响应并执行操作
        parseToolCallResponse(resp);
      }
    } else {
      // 打印HTTP错误信息（如连接失败、超时等）
      Serial.printf("HTTP错误: %s\n", https.errorToString(httpCode).c_str());
      Serial.printf("错误代码: %d\n", httpCode);
    }

    // 结束本次HTTP会话，释放资源
    https.end();
  } else {
    // 如果无法建立HTTPS连接，打印错误提示
    Serial.println("无法连接到服务器");
  }
}

/* 
 * -------------- 第二次向AI平台发送HTTPS请求的函数 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 构造包含Tool Calls响应和执行结果的JSON请求体
 * 2. 设置请求头：Content-Type为application/json，Authorization为Bearer + API密钥
 * 3. 发送POST请求，携带包含对话历史和执行结果的JSON请求体
 * 4. 接收并打印HTTP响应状态码和响应内容
 * 5. 解析并显示LLM生成的自然语言反馈
 */
void callAIPlatformSecond() {
  Serial.println("\n>>> 第二次请求：发送Tool Calls响应和执行结果，获取自然语言反馈...");

  // 构造Authorization请求头：格式为"Bearer <your-api-key>"
  String auth = "Bearer ";
  auth += ai_api_key;

  // 构造第二次请求的JSON体
  String secondPayload = buildSecondPayload();
  
  Serial.println("----- 第二次请求JSON -----");
  Serial.println(secondPayload);
  Serial.println("----- 请求JSON结束 -----");

  // 初始化HTTPS连接（使用client、主机名、端口、API路径）
  if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

    // 设置超时时间（毫秒）
    https.setTimeout(20000); // 20秒超时
    https.setConnectTimeout(10000); // 10秒连接超时

    Serial.println("HTTPS连接已初始化，发送第二次请求...");

    // 添加必要的HTTP请求头
    https.addHeader("Content-Type", "application/json");
    https.addHeader("Authorization", auth);

    // 发送POST请求，并获取HTTP状态码
    int httpCode = https.POST(secondPayload);

    if (httpCode > 0) {
      // 打印HTTP响应状态码（如200表示成功）
      Serial.printf("HTTP响应状态码: %d\n", httpCode);

      // 如果响应成功（HTTP 200 OK）
      if (httpCode == HTTP_CODE_OK) {
        // 获取完整的响应字符串
        String resp = https.getString();
        Serial.println("----- 第二次响应 -----");
        Serial.println(resp);  // 打印AI返回的完整JSON
        Serial.println("----- 响应结束 -----");
        
        // 解析并显示自然语言反馈
        parseSecondResponse(resp);
      }
    } else {
      // 打印HTTP错误信息（如连接失败、超时等）
      Serial.printf("HTTP错误: %s\n", https.errorToString(httpCode).c_str());
      Serial.printf("错误代码: %d\n", httpCode);
    }

    // 结束本次HTTP会话，释放资源
    https.end();
  } else {
    // 如果无法建立HTTPS连接，打印错误提示
    Serial.println("无法连接到服务器");
  }
}

/* 
 * -------------- 构造第一次请求的JSON体 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用预定义的JSON模板（ai_payload_first_template）
 * 2. 替换模板中的占位符为实际值
 * 3. 返回完整的第一次请求JSON体
 * 
 * 这种方法使第一次请求的结构更加直观，便于学习者理解Tool Calls的实现
 * 
 * 返回值：
 * - String: 构造好的第一次请求JSON体
 */
String buildFirstPayload() {
  // 从模板开始构建请求体
  String payload = ai_payload_first_template;
  
  // 替换模板中的占位符
  payload.replace("{{USER_COMMAND}}", userCommand);
  
  return payload;
}

/* 
 * -------------- 构造第二次请求的JSON体 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用预定义的JSON模板（ai_payload_second_template）
 * 2. 解析第一次Tool Calls响应，提取关键信息
 * 3. 替换模板中的占位符为实际值
 * 4. 返回完整的第二次请求JSON体
 * 
 * 这种方法使第二次请求的结构更加直观，便于学习者理解Follow-up Tool Calls的实现
 * 
 * 返回值：
 * - String: 构造好的第二次请求JSON体
 */
String buildSecondPayload() {
  // 解析第一次Tool Calls响应
  DynamicJsonDocument firstDoc(4096);
  DeserializationError error = deserializeJson(firstDoc, firstToolCallResponse);
  
  if (error) {
    Serial.print("第一次响应JSON解析失败: ");
    Serial.println(error.c_str());
    return "";
  }
  
  // 从模板开始构建请求体
  String payload = ai_payload_second_template;
  
  // 准备替换的值
  String escapedArguments = firstToolCallArguments;
  // 转义参数字符串中的双引号，确保JSON格式正确
  escapedArguments.replace("\"", "\\\"");
  
  // 替换模板中的占位符
  payload.replace("{{USER_COMMAND}}", userCommand);
  payload.replace("{{TOOL_CALL_ID}}", firstToolCallId);
  payload.replace("{{TOOL_CALL_NAME}}", firstToolCallName);
  payload.replace("{{TOOL_CALL_ARGUMENTS}}", escapedArguments);
  payload.replace("{{EXECUTION_RESULT}}", toolExecutionResult);
  
  return payload;
}



/* 
 * -------------- 解析第一次Tool Call响应的函数--------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用ArduinoJson库解析JSON响应
 * 2. 检查响应中是否包含tool_calls字段
 * 3. 提取函数名称和参数
 * 4. 调用统一的LED控制函数执行操作
 * 5. 存储Tool Calls信息用于第二次请求
 */
void parseToolCallResponse(String jsonResponse) {
  // 解析JSON响应
  DynamicJsonDocument doc(4096);
  DeserializationError error = deserializeJson(doc, jsonResponse);
  
  if (error) {
    Serial.print("JSON解析失败: ");
    Serial.println(error.c_str());
    return;
  }
  
  // 检查是否有tool_calls
  if (doc.containsKey("choices") && doc["choices"].size() > 0) {
    JsonObject choice = doc["choices"][0];
    JsonObject message = choice["message"];
    
    if (message.containsKey("tool_calls") && message["tool_calls"].size() > 0) {
      JsonObject toolCall = message["tool_calls"][0];
      JsonObject function = toolCall["function"];
      String functionName = function["name"].as<String>();
      
      // 存储Tool Calls信息
      firstToolCallId = toolCall["id"].as<String>();
      firstToolCallName = functionName;
      firstToolCallArguments = function["arguments"].as<String>();
      
      Serial.print("检测到工具调用: ");
      Serial.println(functionName);
      Serial.print("Tool Call ID: ");
      Serial.println(firstToolCallId);
      Serial.print("Tool Call参数: ");
      Serial.println(firstToolCallArguments);
      
      if (functionName == "controlLEDOnOFF") {
        // 解析LED开关函数参数
        DynamicJsonDocument argsDoc(512);
        DeserializationError argsError = deserializeJson(argsDoc, firstToolCallArguments);
        
        if (argsError) {
          Serial.print("参数解析失败: ");
          Serial.println(argsError.c_str());
          return;
        }
        
        String action = argsDoc["action"].as<String>();
        
        Serial.print(">>> 第二步：执行Tool Calls，控制LED开关...");
        Serial.print("执行动作: ");
        Serial.println(action);
        
        // 调用LED开关控制函数并保存执行结果
        toolExecutionResult = controlLEDOnOFF(action);
        
      } else if (functionName == "controlLEDBrightness") {
        // 解析LED亮度函数参数
        DynamicJsonDocument argsDoc(512);
        DeserializationError argsError = deserializeJson(argsDoc, firstToolCallArguments);
        
        if (argsError) {
          Serial.print("参数解析失败: ");
          Serial.println(argsError.c_str());
          return;
        }
        
        int level = argsDoc["level"].as<int>();
        
        Serial.print(">>> 第二步：执行Tool Calls，控制LED亮度...");
        Serial.print("执行亮度调节: ");
        Serial.println(level);
        
        // 调用LED亮度控制函数并保存执行结果
        toolExecutionResult = controlLEDBrightness(level);
        
      } else {
        Serial.print("未知函数: ");
        Serial.println(functionName);
      }
    } else {
      // 没有tool_calls，可能是普通文本响应
      Serial.println("未检测到tool_calls");
      if (message.containsKey("content")) {
        String content = message["content"].as<String>();
        Serial.print("模型回复: ");
        Serial.println(content);
      }
    }
  }
}

/* 
 * -------------- 解析第二次响应的函数--------------
 * 
 * 该函数完成以下步骤：
 * 1. 使用ArduinoJson库解析JSON响应
 * 2. 提取LLM生成的自然语言反馈
 * 3. 显示反馈内容
 */
void parseSecondResponse(String jsonResponse) {
  // 解析JSON响应
  DynamicJsonDocument doc(4096);
  DeserializationError error = deserializeJson(doc, jsonResponse);
  
  if (error) {
    Serial.print("第二次响应JSON解析失败: ");
    Serial.println(error.c_str());
    return;
  }
  
  // 提取并显示自然语言反馈
  if (doc.containsKey("choices") && doc["choices"].size() > 0) {
    JsonObject choice = doc["choices"][0];
    JsonObject message = choice["message"];
    
    if (message.containsKey("content") && !message["content"].as<String>().isEmpty()) {
      String content = message["content"].as<String>();
      Serial.println(">>> LLM自然语言反馈:");
      Serial.println(content);
    } else {
      Serial.println("LLM没有提供自然语言反馈");
    }
  } else {
    Serial.println("无法解析第二次响应");
  }
}

/*
========================================================================
 【附录】本程序实际发送的HTTP请求内容（供参考）
========================================================================

第一次请求：

POST /compatible-mode/v1/chat/completions HTTP/1.1
Host: dashscope.aliyuncs.com
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Length: [自动计算]

{
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。"
    },
    {
      "role": "user",
      "content": "LED亮度调节为最大"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "controlLEDOnOFF",
        "description": "控制LED的打开或关闭",
        "parameters": {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "description": "LED控制动作",
              "enum": ["on", "off"]
            }
          },
          "required": ["action"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "controlLEDBrightness",
        "description": "控制LED的亮度级别",
        "parameters": {
          "type": "object",
          "properties": {
            "level": {
              "type": "integer",
              "description": "亮度级别，1-5级，其中1为最暗，5为最亮",
              "minimum": 1,
              "maximum": 5
            }
          },
          "required": ["level"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "temperature": 0.1
}

第一次响应 
{
  "choices": [
    {
      "finish_reason": "tool_calls",
      "index": 0,
      "message": {
        "content": "",
        "role": "assistant",
        "tool_calls": [
          {
            "function": {
              "arguments": "{\"level\": 5}",
              "name": "controlLEDBrightness"
            },
            "id": "call_a4b2372b98b1492681255a",
            "index": 0,
            "type": "function"
          }
        ]
      }
    }
  ],
  "created": 1782587266,
  "id": "chatcmpl-e5b396d-99d7-4702-ac18-ed87f61aefb0f",
  "model": "qwen-flash",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 21,
    "prompt_tokens": 275,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 296
  }
}
第二次请求（Follow-up Tool Calls）：

POST /compatible-mode/v1/chat/completions HTTP/1.1
Host: dashscope.aliyuncs.com
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Length: [自动计算]

{
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能家居助手，可以控制LED的开关和亮度。请根据Tool Calls的执行结果，提供友好的自然语言反馈。"
    },
    {
      "role": "user",
      "content": "LED亮度调节为最大"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_a4b2372b98b1492681255a",
          "type": "function",
          "function": {
            "name": "controlLEDBrightness",
            "arguments": "{\"level\": 5}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_a4b2372b98b1492681255a",
      "content": "LED亮度已成功调节到最亮级别"
    }
  ],
  "temperature": 0.1
}

第二次响应:

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "已将LED亮度调节到最大值，现在灯光最亮哦！✨",
        "role": "assistant"
      }
    }
  ],
  "created": 1782587267,
  "id": "chatcmpl-4dc8fbf-1fb-9af9d-904f4dd-60286b17cd",
  "model": "qwen-flash",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 16,
    "prompt_tokens": 90,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "total_tokens": 106
  }
}
 * 
 * 说明：
 * - 第一次请求用于获取Tool Calls响应
 * - 第二次请求包含完整的对话历史，包括Tool Calls和执行结果
 * - 第二次请求中的tool角色消息提供了Tool Calls的执行结果
 * - LLM根据执行结果生成自然语言反馈，提供更友好的用户体验
 * ========================================================================
 */