スキーマ検証

SDK は、モデルに構造化データを説明する場合にも、アプリケーション内のデータを検証する場合にもスキーマを使用します。ローカルでの検証と型推論が必要かどうかに応じて、スキーマ形式を選択してください。

スキーマ形式	ローカルでの検証と変換	TypeScript の型推論	対応箇所
Zod オブジェクト	はい	はい	関数ツールとエージェントツールの `parameters`、関数ツールの `outputSchema`、エージェントの `outputType`、ハンドオフの `inputType`
Standard JSON Schema 変換に対応した Standard Schema	はい、同期的に実行	はい、検証結果の出力型から推論	関数ツールとエージェントツールの `parameters`、エージェントの `outputType`、ハンドオフの `inputType`
元の JSON Schema	いいえ。SDK は JSON のパースのみを行います	いいえ。値の型は `unknown` です	関数ツールとエージェントツールの `parameters`、関数ツールの `outputSchema`、エージェントの `outputType`、ハンドオフの `inputType`

Zod がすでにアプリケーションに適している場合は、Zod を使用してください。別の互換性のある検証ライブラリで、同じ SDK の検証機能と出力型の推論を利用したい場合は、Standard Schema を使用してください。通信に使用するスキーマをすでに管理していて、値の検証を別の場所で行う場合は、元の JSON Schema を使用してください。

Standard Schema ライブラリの使用

互換性のある値は、Standard Schema V1 の検証と Standard JSON Schema 変換を実装している必要があります。両方の機能を直接提供するライブラリもあれば、アダプターを提供するライブラリもあります。この例では、Valibot と、@valibot/to-json-schema の toStandardJsonSchema() を使用します。

すでに @openai/agents を使用しているアプリケーションで、npm install valibot @valibot/to-json-schema を実行して、この例の依存関係をインストールしてください。

import { Agent, handoff, tool } from '@openai/agents';
import { toStandardJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const LookupOrderParameters = toStandardJsonSchema(
  v.object({
    orderId: v.pipe(v.string(), v.minLength(1)),
    includeHistory: v.optional(v.boolean(), false),
  }),
);

const lookupOrder = tool({
  name: 'lookup_order',
  description: 'Look up an order by ID.',
  parameters: LookupOrderParameters,
  // The argument type is inferred after Valibot validation and defaults run.
  execute: async ({ orderId, includeHistory }) => ({
    orderId,
    status: 'shipped',
    history: includeHistory ? ['placed', 'shipped'] : undefined,
  }),
});

const Resolution = toStandardJsonSchema(
  v.object({
    orderId: v.string(),
    message: v.string(),
  }),
);

const supportAgent = new Agent({
  name: 'Order support',
  instructions: 'Resolve order questions and return a structured summary.',
  tools: [lookupOrder],
  // The final output is converted to JSON Schema, then validated by Valibot.
  outputType: Resolution,
});

const supportAgentTool = supportAgent.asTool({
  toolName: 'resolve_order',
  toolDescription: 'Resolve an order question with the support specialist.',
  parameters: LookupOrderParameters,
  // inputBuilder receives the same validated and inferred parameter type.
  inputBuilder: ({ params }) =>
    `Resolve order ${params.orderId}. Include history: ${params.includeHistory}.`,
});

const EscalationDetails = toStandardJsonSchema(
  v.object({
    reason: v.pipe(v.string(), v.minLength(1)),
    priority: v.optional(v.picklist(['normal', 'urgent']), 'normal'),
  }),
);

const billingAgent = new Agent({
  name: 'Billing specialist',
  instructions: 'Resolve billing questions.',
});

const billingHandoff = handoff(billingAgent, {
  inputType: EscalationDetails,
  // The callback receives the validated value, including Valibot defaults.
  onHandoff: async (_context, details) => {
    if (details) {
      await recordEscalation(details.reason, details.priority);
    }
  },
});

async function recordEscalation(_reason: string, _priority: string) {}

export { billingHandoff, supportAgent, supportAgentTool };

同じスキーマ仕様でも、利用箇所ごとに役割が異なります。

tool({ parameters }) は、モデル向けにスキーマを変換し、各ツール呼び出しをローカルで検証し、ライブラリの変換やデフォルト値を適用して、型推論された検証結果を execute に渡します。
agent.asTool({ parameters }) は、同じ検証を適用し、ネストされたエージェントの実行前に、型推論された検証結果を inputBuilder に渡します。
new Agent({ outputType }) は、構造化されたモデル出力を要求し、パースされた値をローカルで検証して、型推論された検証結果を result.finalOutput を通じて公開します。
handoff(..., { inputType }) は、ハンドオフのツール呼び出しの引数を検証し、型推論された検証結果を onHandoff に渡します。

要件と制限

Standard Schema のサポートは、意図的に限定された仕様に基づいています。

値は、同期的な ~standard.validate の動作と、~standard.jsonSchema.input() および ~standard.jsonSchema.output() の両方を提供する必要があります。検証のみに対応した Standard Schema の値はサポートされません。
これらの SDK の利用箇所で使用する入力 JSON Schema は、ルートに type: "object" が必要です。スカラー値や配列値は、オブジェクトスキーマでラップしてください。
Standard Schema による関数ツールのパラメーターには、厳格モードが必要です。使用時に strict: false を設定しないでください。
非同期の Standard Schema 検証はサポートされていません。バリデーターが Promise を返すと、ツールのフォールバックや無効な最終出力を処理するハンドラーは実行されず、処理が失敗します。
生成される JSON Schema は、SDK の厳格なスキーマ正規化でサポートされている構文を使用する必要があります。サポートされていない構文があると、モデルへのリクエスト前に、ツール、ハンドオフ、またはエージェントの作成時点で失敗します。
関数ツールの outputSchema は、現在 Standard Schema を受け付けません。Zod スキーマや元の JSON Schema を使用するか、アプリケーションコードでツールの実行結果を検証してください。

独自のアダプターを作成する場合は、@openai/agents から StandardSchemaWithJSON<Input, Output> 型をインポートし、必要な検証メソッドと変換メソッドが提供されていることを確認してください。ライブラリ側で保守されているアダプターが利用できる場合は、そちらを優先してください。