自定义指令实践

工具描述要清晰准确

• 目标：让意图模型明白这个工具是用来做什么的。

• 注意事项：避免使用模糊不清的语言，确保描述与实际功能一致。

示例：

• 好："查询指定日期的天气情况"

• 不好："查看天气"（过于宽泛，可能被误用于其他天气相关操作）

参数定义需无歧义

• 目标：每个参数的作用和取值范围都应明确。

• 建议做法：尽可能使用枚举值限制参数选项（目前暂未开放枚举值定义，请在描述中定义）；对于开放性输入，则提供详细的描述。

示例 - 定义一个播放音乐的工具：

{
  "type": "object",
  "required": ["action", "media"],
  "properties": {
    "action": {
      "type": "string",
      "description": "播放控制动作",
      "enum": ["play", "pause", "stop"]
    },
    "media": {
      "type": "string",
      "description": "媒体文件名或URL"
    }
  }
}

精简而全面

• 目标：保持工具定义简洁但信息完整。

• 注意事项：不要过度列举例子，仅保留必要的说明部分。

示例 - 查询的工具定义：

{
  "name": "query_city_news",
  "description": "查询指定城市的新闻",
  "parameters": {
    "type": "object",
    "required": ["city"],
    "properties": {
      "city": {
        "type": "string",
        "description": "要查询的城市名称"
      },
      "date": {
        "type": "string",
        "description": "查询的日期，格式为 yyyy-mm-dd，如果为空则查询当前日期"
      }
    }
  }
}

合理合并相似参数

在设计工具调用接口时，合理合并相似参数意味着将具有类似功能或可以共同处理的多个参数整合为一个。这样做不仅能够简化接口定义，减少冗余，还能使工具调用更加直观易懂。下面通过几个例子来具体说明如何进行合理的参数合并：

人类可读时间规范

{
        "humanReadableDate": {
            "title": "人类可读日期",
            "type": "string",
            "x-type": "humanReadableTime",
            "description": "可以是绝对日期，相对日期，标准日期，系统会自动解析成 yyyy-mm-dd 格式",
            "examples": [
                "明天",
                "下周二",
                "三天后"
            ]
        },
        "humanReadableTime": {
            "title": "人类可读时间",
            "type": "string",
            "x-type": "humanReadableTime",
            "description": "可以是自然语言描述的绝对时刻，相对时刻，系统会自动解析成 HH:MM:SS 格式",
            "examples": [
                "三小时后",
                "今天下午5点",
                "12点15"
            ]
        }
    }

参数名 以"date_"开头，系统会把参数理解为humanReadableDate

参数名 以"time_"开头，系统会把参数理解为humanReadableTime

parameters 内部结构

• type: 固定为 "object"。

• properties: 定义具体的键值对，每个键代表一个参数。

• required: 一个字符串数组，列出所有必填参数的名称。

工具列表的元定义

{
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
          "description": { "type": "string", "minLength": 1 },
          "parameters": { "type": "object" }
        },
        "required": ["name", "description"],
        "additionalProperties": false
      }
}

管控台配置

如果需要下发指令的同时给出模型回复，可以在设置页中选择回复模式：

• 根据执行情况回复（默认）：下发指令后，等待端侧返回成功/失败信息，模型生成对应回复，如“已将空调调整到26度”、“已经是最高音量，无法继续调高”。

• 自动回复：下发指令的同时，自动输出回复。

端侧接受指令

如 3.1 配置取消静音技能需要回复。

通过语音指令“取消静音”的下发结果为：

{
    "payload": {
        "output": {
            "event": "RespondingContent",
            "text": "",
            "spoken": "",
            "finished": true,
            "finish_reason": "stop",
            "extra_info": {
                "tool_infos": [

                ],
                "agent_info": {
                    "intent_infos": [
                        {
                            "domain": "general_command",
                            "intent": "unmute"
                        }
                    ],
                    "round": 1
                },
                "commands": "[{\"intent_info\":{\"domain\":\"general_command\",\"intent\":\"unmute\"},\"command_request_id\":\"35b635f3-6511-450e-8fa1-6955d5279367\",\"name\":\"unmute\",\"params\":[]}]",
                "query": "取消静音"
            },
            "dialog_id": "56fe9300-d80c-471a-80bd-20c0296acd93",
            "round_id": "70f636e1d0284bc8a8bac2767e61b4b5",
            "llm_request_id": "1d8f3469274e4d13bbc3b28460eabb76"
        }
    }
}

结果中 payload.output.extra_info.commands 为指令执行结果。

当用户选择根据执行情况回复时， 返回结果中包含command_request_id。在回复结果时，这个 ID 作为回复的 key 使用。

端侧回复指令

您在收到指令或者 Agent的结果后，通过端侧执行，获得一个成功或者失败的结果，同步给服务端，通过如下接口提交：

invoke_result.content 是端侧传递给Agent 的数据部分。我们推荐使用如下端侧统一返回规范格式：

{
  "type": "text",
  "text": "Tool result text"
}

{
  "type": "image",
  "data": "base64-encoded-data",
  "mimeType": "image/png"
  "annotations": {
    "audience": ["user"],
    "priority": 0.9
  }
}

{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

[
    {
        "command_request_id": "xxxx",
        "invoke_result": {
            "content": {
                "type": "text",
                "text": "成功打开"
            },
            "structuredContent": {
                "success": true
            }
        }
    }
]

请求代码示例- 端侧回调执行结果（以 java 为例）

public static HashMap<String,Object> getAgentorCommandResult() {

  HashMap<String,Object> commandResult = new HashMap<>();
  commandResult.put("command_request_id", "35b635f3-6511-450e-8fa1-6955d5279367");
  commandResult.put("invoke_result", new Object<>());
    // invoke_result.structuredContent.success = true/false 执行结果

  ArrayList<Object> commandResults = new ArrayList<>();
  commandResults.add(commandResult);

  HashMap<String,Object> passThroughParams = new HashMap<>();
  passThroughParams.put("command_results", commandResults);
  return passThroughParams;
}
 
//发起打开 agent 请求
MultiModalRequestParam.UpdateParams updateParams = MultiModalRequestParam.UpdateParams.builder()
    .bizParams(MultiModalRequestParam.BizParams.builder()
        .passThroughParams(getAgentorCommandResult())
        .build())
    .build();
conversation.requestToRespond("prompt", "", updateParams);