AI Agents · 课时

定义工具模式（JSON Schema）

Q: 「定义工具模式（JSON Schema）」这节课中我会学到什么？

使用类型、描述、枚举和必填字段，为工具参数编写 JSON Schema 定义。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用类型、描述、枚举和必填字段，为工具参数编写 JSON Schema 定义。

定义工具模式（JSON Schema） 是 CoddyKit 上的免费 AI Agents 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

工具模式就是 JSON Schema

OpenAI、Anthropic 以及大多数其他服务都使用 JSON Schema 定义工具参数。

如果您使用过 OpenAPI / Swagger，那么您已经掌握了其中 90% 的内容。

三个必需字段

每个工具定义都包含：

name——唯一标识符（蛇形命名法）
description——工具的作用以及使用时机
parameters——输入内容的 JSON Schema

最小模式

一个包含一个必需字符串字段的对象：

schema = {
    'name': 'search_orders',
    'description': 'Find orders by customer email',
    'parameters': {
        'type': 'object',
        'properties': {
            'email': {
                'type': 'string',
                'description': 'Customer email address'
            }
        },
        'required': ['email']
    }
}
import json
print(json.dumps(schema, indent=2))

JSON Schema 类型

string——文本
integer、number——数字
boolean——真或假
array——列表（还需要 items）
object——字典（还需要 properties）

为封闭集合使用枚举

当允许的值恰好有 N 个时，请使用 enum：

unit_param = {
    'unit': {
        'type': 'string',
        'enum': ['C', 'F'],
        'description': 'Temperature unit'
    }
}
# The model will only ever output C or F
print(unit_param)
print("Allowed values:", unit_param['unit']['enum'])

数组参数

对于列表输入，请设置 items：

tags_param = {
    'tags': {
        'type': 'array',
        'items': {'type': 'string'},
        'description': 'List of tags to filter by'
    }
}
print(tags_param)

嵌套对象

您可以嵌套对象，但为了确保模型可靠性，请让模式保持浅层结构（最多 2 至 3 层）：

filter_param = {
    'filter': {
        'type': 'object',
        'properties': {
            'min_price': {'type': 'number'},
            'in_stock': {'type': 'boolean'}
        }
    }
}
print(filter_param)

描述字段至关重要

模型会根据 description 选择工具并填入参数。请像编写接口文档一样对待描述：

# Bad
bad = {'description': 'gets data'}

# Good
good = {'description': 'Fetch the most recent 50 orders for the given customer email. Returns order_id, status, total. Use this when the user asks about their order history or order status.'}
print("Bad description:", bad['description'])
print("Good description:", good['description'])

required 数组

请明确标记必需字段。模型始终会填写这些字段；只有相关时才会填写可选字段：

tool_params = {
    'parameters': {
        'properties': {
            'city': {'type': 'string'},
            'unit': {'type': 'string', 'enum': ['C', 'F']}
        },
        'required': ['city']
    }
}
print(tool_params)
print("Required fields:", tool_params['parameters']['required'])

Pydantic 转 JSON Schema

您可以根据 Pydantic 模型自动生成模式：

from pydantic import BaseModel, Field

class SearchArgs(BaseModel):
    email: str = Field(description='Customer email')
    limit: int = Field(50, description='Max orders to return')

schema = SearchArgs.model_json_schema()

严格模式（OpenAI 结构化输出）

添加 strict: true 和 additionalProperties: false，即可保证模型输出与模式完全匹配：

tools = [{
    'type': 'function',
    'function': {
        'name': 'get_weather',
        'strict': True,
        'parameters': {
            'type': 'object',
            'properties': {'city': {'type': 'string'}},
            'required': ['city'],
            'additionalProperties': False
        }
    }
}]
import json
print(json.dumps(tools, indent=2))

描述的重要性

为什么工具的 description 如此重要？

回顾

模式会引导模型。高质量的描述、用于封闭集合的枚举、必需数组以及严格模式，都是提高可靠性的关键手段。

常见问题解答

「定义工具模式（JSON Schema）」课时是免费的吗？

是的 — 「定义工具模式（JSON Schema）」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「定义工具模式（JSON Schema）」这节课中我会学到什么？

使用类型、描述、枚举和必填字段，为工具参数编写 JSON Schema 定义。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「定义工具模式（JSON Schema）」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents