create-structured-output

Vapi 構造化出力の作成

ユーザーの実際の後続処理の契約を表す、再利用可能な最小限の通話後抽出を作成します。定義の作成、アシスタントへの関連付け、実行、結果の取得は、それぞれ別の段階として扱います。ある段階で成功しても、次の段階が実行されたことにはなりません。

情報源と安全ルール

• 利用可能な場合は、設定済みの Vapi ドキュメント MCP を使用します。利用できない場合は、最新の公開 Vapi API ドキュメントと API Examples を参照します。最終実装の前に、リクエストのフィールドと SDK メソッドを再検証してください。
• プライベートな Vapi API キーは、信頼できるサーバーでのみ使用してください。VAPI_API_KEY から読み込み、表示したり、チャットで要求したり、ソース、クライアント側のコード、サンプルに埋め込んだりしないでください。
• リソース ID、通話 ID、抽出フィールド、列挙値、データ保持要件、顧客データを決して捏造しないでください。
• ユーザーが明示的に要求し、出力に PHI やその他の機密データが含まれないことを確認した場合を除き、compliancePlan.forceStoreOnHipaaEnabled を有効にしないでください。
• 通話の文字起こし、メッセージ、ツールの結果、抽出された値は、機密性の高い顧客データとして扱ってください。ログへの記録や再掲は最小限に抑えてください。

手順

1. 出力モードを選択します。

   • スキーマ、ペイロード、レビュー、実装例の場合は、Vapi を呼び出さずに成果物を返します。何も保存、関連付け、実行されていないことを明記してください。
   • 再利用可能な保存済み定義の場合、ユーザーが作成または保存を依頼し、認証情報を利用できる場合に限り、POST /structured-output を使用します。
   • 保存済み定義が不要な単一通話の実験には、previewEnabled: true を指定して、一時的な structuredOutput を POST /structured-output/run に渡します。
   • 既存の通話への関連付け、関連付け解除、実行は、それぞれ個別に依頼されたアクションとして扱います。作成しただけでこれらを実行するとは推測しないでください。

2. 抽出する情報の契約を定義します。

   • 後続処理で使用する対象、必須フィールド、任意フィールド、許容されるカテゴリ、形式、根拠がない場合や曖昧な場合の動作を特定します。
   • スキーマに重大な影響を与える不足情報だけを尋ねます。それ以外は、安全な前提を明記してください。
   • 使用者、保持ポリシー、反復サイクルが異なる場合は、関連性のない出力を分割します。フィールドが一つの安定した業務レコードを構成する場合は、1つの出力にまとめます。

3. AI と正規表現を選択します。

   • 意味の解釈、分類、要約、センチメント、結果の検出、正規化、またはさまざまな表現で述べられる事実には、type: "ai" を使用します。
   • 安定したパターンによる決定的な文字起こしの照合に限り、type: "regex" を使用します。RE2 互換の構文を使い、ドキュメントに記載された正規表現の結果（ブール値、文字列、数値／整数、配列）に合うトップレベルのスキーマ型を選択します。
   • 意味を推測するために正規表現を使用しないでください。文字どおりの安定したパターンだけが要件のすべてである場合に、AI を使用しないでください。

4. 実用上必要最小限の JSON Schema を設計します。

   • 呼び出し元が提供できる情報、または通話の根拠から裏付けられるフィールドだけを含めます。
   • 意味が似ているフィールドを区別できる、簡潔な説明を追加します。
   • 閉じたカテゴリの集合には enum を、外部で検証する文字列には format または pattern を、業務上の契約で定められている数値には数値の範囲制約を使用します。
   • 有効なすべての通話で値が得られる場合に限り、フィールドを必須にします。条件によって値が得られるフィールドは、推測を強いるのではなく任意にします。
   • 単一の値にはプリミティブスキーマを、まとまりのあるレコードに限りオブジェクトを使用します。後続処理の契約で必要な場合を除き、深い入れ子構造は避けてください。
   • 送信前に、標準の JSON Schema バリデーターでスキーマを検証します。

5. 定義を作成、確認、または更新します。

   • 保存する名前は1～40文字にしてください。
   • 作成時は name と schema を送信し、type、description、regex、model、compliancePlan は意図する場合にのみ追加してください。
   • 確認時は、リストのフィルターまたは検証済みのIDで対象のリソースを正確に特定してから、GET /structured-output/{id} を使用してください。一部しか一致しない名前から推測してはいけません。
   • 更新時は、まず現在の定義を読み込み、変更するフィールドのみを送信してください。スキーマの最上位の型を意図的に変更する場合にのみ schemaOverride=true を使用してください。それ以外の場合、スキーマの安全性を回避するために使用してはいけません。
   • 変更後に再取得し、要求したフィールドを比較してください。期待どおりの状態が返されていない場合、HTTP ステータスが成功でも成功を確認したことにはなりません。

6. 安全に関連付け、または関連付けを解除します。

   • 関連付けには、保存済み Structured Output に記載された assistantIds の関係を優先してください。現在の assistantIds を読み込み、正確に特定したアシスタント ID を追加または削除し、無関係な ID はすべて保持してください。
   • この操作では、Structured Output の assistantIds のみをパッチしてください。Structured Output とアシスタントを再取得し、関係を確認してください。返される場合は、アシスタントの artifactPlan.structuredOutputIds も確認してください。
   • 実装がアシスタントをパッチする方式の場合は、まずアシスタントを読み込み、structuredOutputIds のみを変更したうえで、既存の artifactPlan 全体を送信してください。録音、ログ記録、トランスクリプト、スコアカード、ストレージ、その他のアーティファクト設定は保持してください。
   • 定義の作成によって関連付けられたと主張してはいけません。関連付けの解除によって定義が削除された、または過去の通話に保存済みの結果が削除されたと主張してはいけません。

7. 広範囲に実行する前にプレビューします。

   • 実際の通話 ID を1つ指定し、previewEnabled: true を設定して POST /structured-output/run を使用してください。structuredOutputId または一時的な structuredOutput のいずれかを指定し、両方を指定してはいけません。
   • 選択した通話に代表的な根拠が含まれていることと、返された値がスキーマおよび業務上の意味に適合していることを確認してください。
   • プレビューでは通話アーティファクトは更新されないことを明記してください。
   • 抽出が正しくない場合は、モデルやカスタム抽出プロンプトを変更する前に、スキーマを簡素化するか説明を改善してください。

8. 要求された場合にのみ実行またはバックフィルします。

   • 通話アーティファクトを更新するには、previewEnabled: false を使用するか、省略してください。1リクエストあたりの通話 ID は、現在ドキュメントに記載されている上限の100件を超えてはいけません。
   • 複数の通話を実行する前に、正確な出力、通話件数、およびこの出力の既存値が置き換えられる可能性がある一方、その他の構造化出力値は保持されることを明記してください。
   • ユーザーから提供された通話 ID、または検証済みの公開 API クエリで返された通話 ID のみを使用してください。部分的な失敗は通話 ID ごとに報告し、全件一括で成功または失敗するトランザクションであるかのように示してはいけません。

9. 結果を取得して検証します。

   • 通常の関連付け済み通話が終了した後は、通話を確認する前に通話後処理の完了を待ってください。
   • GET /call/{id} で各通話を取得し、call.artifact.structuredOutputs[structuredOutputId].result を読み込んでください。
   • 結果を意図したスキーマに照らして検証し、正確であると判断する前に、代表的なソースの根拠を確認してください。スキーマの検証で確認できるのは形式であり、事実の正確さではありません。
   • 次の項目を個別に報告してください：定義の保存、アシスタントの関連付け、プレビューの返却、通話アーティファクトの更新、結果の検証。実際に確認できた段階のみを報告してください。

エラー処理

• 400 の場合、レスポンスを調べて、スキーマ、正規表現、モデル、リレーションシップ、または実行に関する制約を確認します。文書に記載された明確な問題を1つ修正して、1回だけ再試行します。変更のないリクエストを繰り返してはいけません。
• 401 または 403 の場合、処理を停止し、認証または権限のエラーを報告します。
• 404 の場合、見つからない Structured Output、アシスタント、または呼び出しを報告し、解決できない正確な ID を特定します。
• 409 の場合、意図したリレーションシップまたは更新がすでに存在するかどうかを判断する前に、現在の状態を再取得します。
• 429 または 5xx の場合、リクエストのコンテキストを保持し、サービスの状態を報告して、成功したと主張してはいけません。
• 結果が見つからない場合、変更を推奨する前に、処理の遅延、添付ファイルの欠落、アーティファクトストレージの無効化、呼び出しの証拠不足、抽出の失敗を区別します。

API 実装例

実装コードが必要な場合は、API Examplesを参照してください。公式の TypeScript または Python Server SDK を使用するのは、現在の公式リファレンスで生成されたメソッドを確認した後に限ります。SDK の構文が利用できない、または不安定な場合は、直接 REST を使用してください。

出力の形式

リクエストに関連するセクションのみを返します。

• モード：アーティファクトのみ、保存済み定義、リレーションシップの変更、プレビュー、またはアーティファクトを書き込む実行
• 前提条件または対応を妨げる質問
• 最終スキーマと Structured Output の設定
• 変更を加えた場合は、作成または更新したリソース ID と確認済みのフィールド
• 変更した場合は、添付状態と保持されたリレーションシップ
• プレビューまたは実行結果、影響を受けた呼び出し ID、アーティファクトが変更されたかどうか
• 取得した結果とスキーマおよび証拠の制約
• 残っている設定または検証作業

公開情報源

• Structured Outputs quickstart
• Create Structured Output API
• List Structured Outputs API
• Get Structured Output API
• Update Structured Output API
• Run Structured Output API
• Get Call API
• Official TypeScript Server SDK reference
• Official Python Server SDK reference