> For the complete documentation index, see [llms.txt](https://docs.skydeck.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skydeck.ai/zh-cn/developers/develop-your-own-tools/json-format-for-llm-tools.md).

# 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": "字符串 (例如，url, base64)",
    "avatar": "字符串 (URL或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**：表示创建或最后修改GPT模型提示的日期和时间的ISO 8601格式的字符串。
  * **expected\_output (可选)**：包含与model\_prompt期望输出相关的字段的对象，包括以下子字段：
    * **type**：表示从model\_prompt期望输出的类型的字符串。
    * **format (可选)**：表示期望输出的格式的字符串（如果适用）。
    * **language (可选)**：表示期望输出的编程语言的字符串，如果类型为`code`。
    * **allowed\_values (可选)**：包含允许输出值列表的字符串数组，如果类型为`limited`。
  * **variables (可选)**：包含可能插入到`model_prompt`字符串中的变量的列表，以f-string样式。每个变量包含以下子字段：
    * **name**：表示变量名称的字符串。
    * **type**：显示变量类型的字符串。目前`type`的可能值是`text`表示默认变量，`single-select`或`multi-select`表示选择变量。
    * **description**：表示变量描述的字符串，包括用途和示例。
    * **default**：表示变量默认值的值。如果`type`是`text`或`single-select`，则此值是字符串，如果是`multi-select`，则为字符串数组。
    * **allowed\_values**：包含允许值列表的字符串数组，如果变量类型为`single-select`或`multi-select`。
  * **avatar (可选)**：包含与作为提示的头像或图标的图形图像相关的字段的对象，包括以下子字段：
    * **avatar\_type**：指定包含的头像数据类型的字符串。
    * **avatar**：如果avatar\_type是`url`，则包含指向图像的URL的字符串，或者如果avatar\_type是`base64`，则为代表图像的base64编码字符串。
  * **prompt\_name (可选)**：表示提示名称的字符串。
  * **description (可选)**：提供有关工具及其目的的简短描述的字符串。
  * **usage\_notes (可选)**：包含有关工具使用或任何具体考虑因素的创建者的自由形式注释的字符串。

要指定model\_prompt的期望输出格式，可以在`metadata`对象内添加一个`expected_output`对象。根据期望输出的类型，您可以在`expected_output`对象中包括相关的子字段。

要包含可能插入到`model_prompt`字符串中的变量的字段（以f-string样式），可以在`metadata`对象内添加一个单独的`variables`列表。

要包含作为提示的头像或图标的图形图像，可以在`metadata`对象中添加一个`avatar`字段。

在`metadata`对象中包含`expected_output`，`variables`，`avatar`，`prompt_name`，`description`，和`usage_notes`字段有助于在一个地方保存有关提示的所有上下文信息，使其更易于管理和理解。

您可以在JSON对象的顶级使用`version`字段来显式跟踪整个JSON文件的版本


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.