xemantic-ai-tool-schema：将 Kotlin 类型系统无缝桥接到 AI Agent 的 JSON Schema 世界

一行简介

xemantic-ai-tool-schema 是一个 Kotlin 多平台库，能够从标记了 @Serializable 的 Kotlin 数据类自动生成符合 LLM API 规范的 JSON Schema，让 AI Agent 的工具调用（Tool Use / Function Calling）开发从手动编写 Schema 的泥潭中彻底解放出来。

---

痛点故事：那些亲手写错 JSON Schema 的夜晚

做 AI Agent 开发时，你一定绕不开 Tool Use 这个环节。给 AI 定义"帮我查天气"这个工具，你需要告诉模型：

• 参数叫什么（city）
• 是什么类型（string）
• 是否有约束（最少 2 个字符）
• 哪个字段是必填的

大多数人的做法是：翻文档、查示例、手动写一段 JSON Schema。然后发现 AI 返回的数据格式对不上，一行一行对照，发现是 minLength 写成了 min_length，或者 enum 的值打错了。

更痛苦的是：你的数据模型已经用 Kotlin 定义了一份，但 AI 需要的是另一份 JSON Schema，两份要同步维护。

这就是 xemantic-ai-tool-schema 要解决的问题——你的 Kotlin 代码就是 Schema 的源头，库自动推导出 AI 能理解的 JSON Schema。

---

项目背景：来自真实 Agent 开发的倒逼

这个库由 xemantic 团队创建，他们同时维护着：

• anthropic-sdk-kotlin：Anthropic Claude SDK 的 Kotlin 多平台实现
• claudine：构建于 SDK 之上的 AI Agent 框架

在实际开发 AI Agent 的过程中，每次给工具函数添加新参数都要手动更新 JSON Schema，既繁琐又容易出错。于是团队决定：让 Kotlin 的类型系统自动生成 Schema，减少人工操作环节，降低出错概率。

项目采用 Apache 2.0 开源，托管于 GitHub，通过 Maven Central 发布。作者 Kazik Pogoda（morisil）是 xemantic 公司创始人，长期活跃在 Kotlin 社区。

---

核心功能：注解驱动的 Schema 生成

基础用法

定义 Kotlin 数据类，加上 @Serializable 和约束注解：

@Serializable
@SerialName("address")
@Title("The full address")
@Description("An address of a person or an organization")
data class Address(
    val street: String,
    val city: String,
    @Description("A postal code not limited to particular country")
    @MinLength(3)
    @MaxLength(10)
    val postalCode: String,
    @Pattern("[a-z]{2}")
    val countryCode: String,
    @Format(StringFormat.EMAIL)
    val email: String? = null,
    @OptIn(ExperimentalTime::class)
    val registeredAt: Instant,
    val status: AddressStatus
)

enum class AddressStatus {
    PENDING_VERIFICATION,
    VERIFIED,
    INVALID
}

调用生成函数：

val schema = jsonSchemaOf<Address>()

直接得到 JSON Schema 输出，可用于 OpenAI Function Calling 或 Anthropic Tool Use API：

{
  "type": "object",
  "title": "The full address",
  "description": "An address of a person or an organization",
  "properties": {
    "street": { "type": "string" },
    "city": { "type": "string" },
    "postalCode": {
      "type": "string",
      "description": "A postal code not limited to particular country",
      "minLength": 3,
      "maxLength": 10
    },
    "countryCode": { "type": "string", "pattern": "[a-z]{2}" },
    "email": { "type": "string", "format": "email" },
    "registeredAt": { "type": "string", "format": "date-time" },
    "status": {
      "type": "string",
      "title": "Address status",
      "enum": ["PENDING_VERIFICATION", "VERIFIED", "INVALID"]
    }
  },
  "required": ["street", "city", "postalCode", "countryCode", "registeredAt", "status"]
}

支持的约束注解

注解	对应 JSON Schema	适用类型
@Title / @Description	title / description	类、属性
@MinLength / @MaxLength	minLength / maxLength	String
@Pattern	pattern	String（正则）
@Format	format	String（email/uri/date-time 等）
@Min / @Max	minimum / maximum	数值类型
@MinInt / @MaxInt / @MultipleOfInt	整数约束	Integer
@ItemTitle / @ItemDescription	数组元素描述	Array
@UniqueItems	数组去重	Array

Sealed Class 与多态

Kotlin sealed class 会自动生成 oneOf 结构，AI 可以根据 discriminator 路由到具体子类。

---

技术架构：Kotlin 多平台的力量

核心模块

项目只有约 4 个核心源文件，代码量极小但设计精妙：

• JsonSchema.kt：Schema 模型定义。用密封类（sealed class）建模 JSON Schema 的所有节点类型（Object、Array、String、Number、Integer、Boolean），符合 Kotlin 的类型安全理念
• generator/JsonSchemaGenerator.kt：核心生成器。遍历 SerialDescriptor（kotlinx.serialization 的类型元数据）构建 Schema 树
• meta/JsonSchemaAnnotations.kt：自定义约束注解，全部标记 @MetaSerializable，确保在多平台编译时不被擦除
• serialization/JsonSchemaSerializer.kt：Schema → JSON 序列化器

多平台目标

这是 Kotlin 多平台（Kotlin Multiplatform / KMP）的典型应用。项目编译目标覆盖：

• JVM（Java 11+）：生产环境主力
• JavaScript（浏览器 + Node.js）：前端 AI 应用
• WebAssembly（wasmJs + wasmWasi）：高性能 Web 计算
• Native：macOS（Intel/Apple Silicon）、iOS、Linux、Windows、watchOS、tvOS、Android Native

这意味着：一份 Kotlin 代码，编译后可以在服务器、移动端、浏览器、WebAssembly 环境使用，同步为 AI Agent 提供 Schema 生成能力。

测试覆盖

每个 Schema 类型都有独立测试文件（ObjectSchemaTest.kt、ArraySchemaTest.kt 等），主测试套件 JsonSchemaGeneratorTest.kt 覆盖了 60+ 测试场景。使用 kotest 断言库配合 shouldEqualJson 做 Schema 对比验证。

---

部署门槛：零部署的库

这不是一个需要"部署"的应用，而是一个需要"引入"的库。

使用方式：在 build.gradle.kts 中添加一行依赖：

plugins {
    kotlin("multiplatform") version "2.2.20"
    kotlin("plugin.serialization") version "2.2.20"
}

dependencies {
    implementation("com.xemantic.ai:xemantic-ai-tool-schema:1.2.0")
}

然后就可以在代码里调用 jsonSchemaOf<T>()。所需环境仅为 JDK 11+ 和 Gradle（或 Maven），无需 GPU，无需 Docker。

适合人群：已经在用 Kotlin 构建后端服务或移动应用的团队，想要为 AI Agent 层提供类型安全的 Schema 生成能力。

---

局限性：不完美但诚实的评估

1. 仅生成，不消费：库可以生成 JSON Schema，但不能反向从 JSON Schema 生成 Kotlin 类（Pydantic 可以做双向），README 明确标注了这个"非推荐用法"
2. 强依赖 kotlinx.serialization：使用本库需要引入 kotlinx.serialization，这在纯 Java 项目中增加了迁移成本
3. Kotlin 专属：对于 Python/TypeScript 为主的 AI Agent 项目没有直接价值
4. 社区规模较小：51 Stars，当前生态（xemantic 周边 SDK）在 AI 领域的影响力还在建立中

---

行业意义：类型安全 AI 的小而美实践

随着 AI Agent 从 demo 走向生产，工具调用的可靠性成为制约因素。传统做法（手动写 Schema + 字符串拼接）在大规模工具集场景下难以维护。

xemantic-ai-tool-schema 代表了一种方向：用静态类型语言的优势来约束 AI 交互层。类型系统天然具备验证能力，Schema 生成自动化后，人工出错的窗口被大幅压缩。

这一思路与 Pydantic（P）、Zod（TS）、TypeScript 类型系统等前端/后端实践一脉相承，只是将舞台搬到了 AI Agent 层。Kotlin 开发者如果已经在用 kotlinx.serialization，引入这个库几乎是零成本的升级。

---

总结

维度	评分
技术创新	⭐⭐⭐（场景聚焦，思路清晰）
工程质量	⭐⭐⭐⭐（多平台、测试覆盖、文档完善）
实用价值	⭐⭐⭐⭐（解决真实痛点，集成成本低）
社区活跃	⭐⭐（Stars 少，更新频率一般）
部署门槛	⭐⭐⭐⭐⭐（纯库，零部署）

适合引入的项目：Kotlin/Kotlin Multiplatform 后端或跨平台应用，想要构建 AI Agent 能力，且已在用 kotlinx.serialization。

可替代方案：手动编写 JSON Schema + 字符串模板，或切换到 Pydantic（Python）。