# LLM 工具的 JSON 格式

## 簡介

以一種能迅速加入到程式或工具編輯器的方式分享工具，如果有一種標準的方式來表示工具並說明如何使用它，那麼這種分享方式的效果會大大提升。我們希望實現以下的功能：

* 一個用於視覺代表工具的圖標
* 提示的元數據：
  * 工具的名稱
  * 工具的描述
  * 工具的使用說明
* 工具字符串中包含的佔位參數
* 預期的輸出
* 版本控制和時間戳。

## JSON 格式說明

```json
{
  "version": "字串或整數",
  "model_prompt": "含有 {{variable_name}} 佔位符的字串",
  "metadata": {
    "prompt_name": "字串",
    "description": "字串",
    "usage_notes": "字串",
    "model_version": ["字串", "字串", …],
    "creator": {
      "name": "字串",
      "email": "字串",
      "organization": "字串"
    },
    "parameters": {
      "temperature": "浮點數",
      "max_tokens": "整數",
      "top_p": "浮點數",
      "frequency_penalty": "浮點數",
      "presence_penalty": "浮點數"
    },
    "variables": [
      {
        "name": "變數名稱1",
        "type": "文本",
        "description": "字串",
        "default": "字串",
      },
      {
        "name": "變數名稱2",
        "type": "單選",
        "description": "字串",
        "default": "value1",
        "allowed_values": ["value1", "value2", "value3"]
      },
      {
        "name": "變數名稱3",
        "type": "多選",
        "description": "字串",
        "default": ["value1", "value2"]
        "allowed_values": ["value1", "value2", "value3"]
      },
      ...
    ],
    "expected_output": {
      "type": "字串 (例如：文本，程式碼，有限制的)",
      "format": "字串 (可選，例如：JSON，XML，CSV)",
      "language": "字串 (可選，例如：Python，JavaScript)",
      "allowed_values": ["字串1", "字串2", ...] (可選)
    },
    "avatar_type": "字串 (例如，網址，base64)",
    "avatar": "字串 (網址或 base64 編碼的圖片，建議 256x256 像素)",
    "timestamp": "字串 (ISO 8601 格式)"
  }
}
```

你可以從[這裡](https://skydeck-public-assets.s3.amazonaws.com/sample_tool.json)下載我們的範例 JSON。

## 字段說明

* **model\_prompt**：包含 GPT 模型提示符的字符串。
* **metadata**：包含有關 GPT 模型提示符的附加資訊的對象，包括以下子字段：
  * **model\_version**：表示所使用的 GPT 模型版本的字符串。
  * **creator**：包含有關 GPT 模型提示符創建者的信息的對象，包括以下子字段：
    * **name**：表示創建者名稱的字符串。
    * **email**：表示創建者電子郵箱的字符串。
    * **organization**：表示創建者所屬組織的字符串。
  * **parameters**：包含 GPT 模型參數的信息的對象，包括以下子字段：
    * **temperature**：表示用於控制輸出隨機性的溫度的浮點數。
    * **max\_tokens**：表示生成響應中的最大令牌數量的整數。
    * **top\_p**：表示核心採樣概率閾值的浮點數。
    * **frequency\_penalty**：表示根據數據集中的頻率對令牌所應用的懲罰的浮點數。
    * **presence\_penalty**：表示根據其在提示中的存在對新令牌所應用的懲罰的浮點數。
  * **timestamp**：以 ISO 8601 格式表示的字符串，表示創建或最後修改 GPT 模型提示符的日期和時間。
  * **expected\_output (Optional)**：包含與模型提示符的預期輸出相關的字段的對象，包括以下子字段：
    * **type**：表示從模型提示符預期的輸出類型的字符串。
    * **format (Optional)**：表示預期輸出的格式的字符串（如果適用）。
    * **language (Optional)**：表示預期輸出的程式設計語言的字符串（如果類型為 `code`）。
    * **allowed\_values (Optional)**：含有一列允許的輸出值的字符串數組（如果類型為 `limited`）。
  * **variables (Optional)**：包含可能以 f-string 格式插入到 `model_prompt` 字符串中的變量的列表。每個變量包含以下子字段：
    * **name**：表示變量名稱的字符串。
    * **type**：顯示變量類型的字符串。目前，`type` 的可能值是 `text`（對於默認變量），以及 `single-select` 或 `multi-select`（對於選擇變量）。
    * **description**：顯示變量描述的字符串，包括用法和示例。
    * **default**：顯示變量的默認值的值。如果 `type` 是 `text` 或 `single-select`，則此值為字符串，如果為 `multi-select`，則為字符串數組。
    * **allowed\_values**：如果變量類型為 `single-select` 或 `multi-select`，則含有一列允許的值的字符串數組。
  * **avatar (Optional)**：包含與作為提示符的頭像或圖標的圖片相關的字段的對象，包括以下子字段：
    * **avatar\_type**：指定包含的頭像資料類型的字符串。
    * **avatar**：如果 avatar\_type 為 `url`，則為指向圖片的 URL 的字符串，如果 avatar\_type 為 `base64`，則為表示圖片的 base64 編碼字符串。
  * **prompt\_name (Optional)**：表示提示符名稱的字符串。
  * **description (Optional)**：提供有關該工具及其目的的簡短說明的字符串。
  * **usage\_notes (Optional)**：包含創建者關於工具使用或與工具相關的任何特定注意事項的自由格式註釋的字符串。

要指定模型提示符的預期輸出格式，可以在 `metadata` 對象中添加一個 `expected_output` 對象。根據預期輸出的類型，您可以在 `expected_output` 對象中包含相關的子字段。

要包含可能以 f-string 格式插入到 `model_prompt` 字符串中的變量的字段，您可以在 `metadata` 對象中添加一個單獨的 `variables` 列表。

要包含作為提示符的頭像或圖標的圖像，您可以在 `metadata` 對象中添加一個 `avatar` 字段。

在 `metadata` 對象內包含 `expected_output`、`variables`、`avatar`、`prompt_name`、`description` 和 `usage_notes` 字段有助於將有關提示符的所有上下文資訊保持在一個地方，使其更易於管理和理解。

您可以在 JSON 對象的頂層使用 `version` 字段來顯式跟踪整個 JSON 文件的版本。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.skydeck.ai/zh-hk/developers/develop-your-own-tools/json-format-for-llm-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.