Standard Schema 1.0の導入 — AIエージェントツールからZod依存を解消

아이라

@aira

Standard Schema 1.0 도입 — AI 에이전트 도구에서 Zod 의존성 없앤다

Standard Schema 1.0の導入 — AIエージェントツールからZod依存を解消

AIエージェントに新しいツールを持たせる際、なぜ常にZodという特定のライブラリだけを使わなければならなかったのでしょうか？これまで数多くのエージェントフレームワークは、ツールの入力データ構造を定義・検証するために、Zodと密結合しすぎていました。

しかし最近、エージェントエコシステムの勢力図が大きく変わろうとしています。Model Context Protocol (MCP) TS SDK v2.0や、エージェントフレームワークであるMastra v1.2.0などが「Standard Schema v1.0」を全面的に採用したためです。

今や開発者はZodだけでなく、ValibotやArkTypeのような軽量で高速な検証ライブラリを、好みに合わせて自由に使い分けられるようになりました。エージェント開発環境をより自由で軽量にするこの新しい潮流について、これから見ていきましょう。

なぜZod一択だったのか？依存地獄の始まり

LLMが外部ツールを使用するには、入力されるデータの規格を明確に知る必要があります。AIに対し「このツールを実行するには、このようなデータ形式で値を送って」と伝えるための「JSONスキーマ」が不可欠だからです。

これまでTypeScript環境の開発者は、この複雑なスキーマの定義と入力値の検証を行うために、慣例的にZodライブラリを使用してきました。TypeScriptの型定義とランタイムのデータ検証を同時にシームレスに解決できるため、エージェントツールを作る際の事実上の標準として定着していました。

しかし、この結合は予期せぬ「依存地獄」を招きました。エージェントフレームワークやSDKが内部的に特定のZodバージョンを強制することで、開発者がプロジェクトで使用している最新バージョンと衝突する事態が頻発したのです。さらに、エッジ環境に合わせて軽量な検証ツールを使いたくても、巨大で重いZodを強制的にパッケージに含めなければならない非効率性も生じていました。

Standard Schema v1.0 — すべての検証ライブラリを一つに

Standard Schema v1.0を一言で言えば、異なる言語を使う人々が問題なく会話できるようにするための「共通の約束事」です。これは新しいデータ検証ライブラリではありません。Zod、Valibot、ArkTypeなど、それぞれ異なる方法でデータを検証していたツールたちが、一つの共通ルールでやり取りできるようにするための、非常に軽量でシンプルなインターフェース仕様です。

核となる原理は非常に単純です。標準に従うすべてのライブラリは、オブジェクト内部に~standardという約束されたスペースを用意し、共通の検証メソッドであるvalidateを提供するだけでよいのです。

ts
// Standard Schema v1.0 규격을 따르는 스키마 객체의 기본 구조
const mySchema = {
  "~standard": {
    version: 1,
    vendor: "valibot",
    validate: async (value) => {
      // 검증 라이브러리가 내부적으로 처리 후 표준화된 결과 반환
    }
  }
};

このように約束された規格があれば、エージェントフレームワークやSDKを開発する側にとっても非常に便利です。ユーザーがZodを使っていようがValibotを使っていようが、常に~standard.validate()という同一の方法で、安全にデータを検証できるからです。

特にAIエージェント環境に合わせた拡張規格は非常に有用です。LLMがツールを正しく使用するには、入力データ形式を記述したJSONスキーマを読み取る必要があります。この標準規格を活用すれば、特別な変換器を通すことなく、スキーマからLLMが理解可能なJSONスキーマを即座かつ安全に抽出できます。

MCP SDK v2.0とMastraによる標準の活用法

この標準が単なる技術提案を越え、エージェントエコシステムのデファクトスタンダードとして定着しつつあることは、最近発表された主要なツールを見れば明らかです。

最も象徴的な変化は、2026年7月末に正式リリースされたMCP TS SDK v2.0で起こりました。以前のバージョンまで、ツールの入力形式を定義する際は必ずZodスキーマに依存する必要がありました。しかしv2.0からはZod依存を完全に排除し、代わりにStandard SchemaベースのStandardSchemaWithJSONインターフェースを全面的に採用しました。これにより開発者は特定のライブラリに縛られず、プロジェクト環境に応じてZod v4、Valibot、ArkTypeの中から最適な検証ツールを選択して自由にツールを作成できるようになりました。

もう一つの強力なエージェントフレームワークであるMastra v1.2.0も素早く動いています。Mastraは検証ツール間の衝突問題をすっきりと解決するため、@mastra/schema-compatという互換性パッケージを導入しました。このパッケージが提供するtoStandardSchema()関数を使えば、Zod v3やv4、あるいは各種AI SDKのスキーマを、一つの統一された標準フォーマットへとシームレスに変換できます。

この技術が実際のコードでどのように使われるかは、Mastraの統合方法を見ると一目で理解できます。

ts
// Mastra v1.2.0 기반 스키마 변환 예시
import { toStandardSchema } from '@mastra/schema-compat';
import { z } from 'zod';

// 평소처럼 작성한 Zod 스키마
const userProfileSchema = z.object({
  name: z.string(),
  age: z.number().int().positive(),
});

// 스탠다드 스키마 표준 포맷으로 간편하게 변환
const standardSchema = toStandardSchema(userProfileSchema);

このように変換されたスキーマは、エージェントがLLMにツールのスペックを伝え、入力値を検証するすべてのプロセスにおいて一貫して機能します。特定のライブラリに強く縛られていた制約が消え、開発者が好みのパズルピースを自由に組み合わせられる柔軟な環境が開かれたのです。

Cloudflare Workersで遭遇する落とし穴

Cloudflare Workersのような軽量なエッジ環境にエージェントを構築する際は、予期せぬ伏兵に注意が必要です。Mastra v1.2.0の@mastra/schema-compatのように、様々な検証ツールを標準仕様に変換するコンバーターを使用する際によく発生する問題です。

代表的な落とし穴は、Zodスキーマで詳細な検証を行うために使うrefineやsuperRefineメソッドです。これらを適用すると、Zodのスキーマ型がZodObjectからZodEffectsに変化します。コンバーターは、この特殊な型を処理するために内部でAJVのようなライブラリを用い、リアルタイムでJSONスキーマを動的にコンパイルしようと試みます。

この際、JavaScriptの動的コード実行機能であるnew Function()が呼び出されますが、セキュリティが厳格なV8アイソレートベースのCloudflare Workersは、この命令を厳格にブロックします。結果として、エージェントがツールを呼び出した瞬間に停止し、エラーが吐き出されることになります。

ts
// ❌ 엣지 환경에서 에러를 일으키는 패턴
const bugSchema = z.object({
  apiKey: z.string(),
}).refine((data) => data.apiKey.startsWith("sk-"));

// ✅ 안전한 패턴: 스키마는 단순하게 유지하고, 검증은 실행 함수 안에서 처리
const safeSchema = z.object({
  apiKey: z.string(),
});

そのため、エッジ環境でツールスキーマを定義する際は、可能な限り単純な基本型のみを定義し、複雑なカスタム検証ロジックはスキーマの外側であるツールの実行関数内で処理する方がはるかに安全です。

より軽量で柔軟になるエージェントエコシステム

Standard Schema v1.0の導入は、単なるデータ検証ライブラリの入れ替え以上の意味を持ちます。特定の検証ツールに縛られない柔軟性により、今後開発されるエージェントツールの移植性は飛躍的に高まるでしょう。

これからは開発者がフレームワークの制約から脱却し、軽量で高速なエージェントを作るために必要な機能だけを厳選して盛り込めるようになります。MCP TS SDK v2.0とMastra v1.2.0が導く、よりモジュール化された軽量なエージェント開発環境に期待しましょう。