Headless APIのトラブルシューティング
このページを使用して、一般的なHeadless APIの失敗を解決します。
401 auth_failed
エラー: ランタイム呼び出しで401が次の内容とともに返されます。
{ "error_code": "auth_failed", "error_message": "Authentication failed.", "request_id": "<uuid>" }原因と解決策: ゲートウェイがGenieに到達する前に認証情報を拒否しました。次の項目を順番に確認します。
- トークンのタイプが間違っている: ランタイム呼び出しでは、プロビジョニング専用の
wrkaus-…Developer APIトークンではなく、GenieクライアントAPIキーまたはOAuthアクセストークンを使用します。 - データセンターが間違っている: 認証情報はデータセンターごとにスコープ設定されます。ワークスペースが実行されているデータセンターと同じデータセンターの
genie-apiホストを呼び出します。 - 期限切れまたはローテーション済みのキー: APIキーを再生成すると、以前のAPIキーは無効になります。再生成し、更新されたAPIキーを使用するようにバックエンドを更新します。
- 形式が正しくないヘッダー:
Authorization: Bearer <token>を正確に送信します。
401 user_nonactive_or_missing
エラー: APIキー呼び出しでerror_code: "user_nonactive_or_missing"とともに401が返されます。
原因: X-IDP-User-Idがアクティブで許可リストに登録されたユーザーに解決されません。ユーザーが存在しない場合、Genieで許可リストに登録されたユーザーグループに属していない場合、またはまだアクティブでない場合のいずれでも、ランタイムは同じコードを返します。ユーザーは招待済みであっても、招待を承諾してWorkato Identityの設定を完了していない場合は非アクティブです。
解決策: ユーザーがアクティブであることを確認します。招待されたユーザーは、アサートできるようになる前にメール招待を承諾し、Workato Identityの設定を完了する必要があります。そのため、設定が完了していない場合は、ユーザーにメールを確認するよう依頼してください。次に、ユーザーがGenieで許可リストに登録されたユーザーグループに属していることを確認し、必要に応じて先にユーザーを作成します。ランタイム呼び出しの前に、サーバー側でGET /api/iam/users?query=<email>を使用してユーザーを検索します。レスポンスにはstatusフィールド(activeまたはinvited)が含まれます。これにより、不明なユーザーと許可リスト未登録のユーザーに対して異なるメッセージを表示することもできます。
クライアントの作成またはアタッチに失敗する
エラー: ほとんどのDeveloper API呼び出しは成功しますが、Genieクライアントの作成、再生成、またはアタッチが権限エラーで失敗します。
原因: Developer APIクライアントのロールに、クライアント管理を制御するGenie building配下のCustom chat interface権限がありません。これはHeadlessの設定で最も見落とされやすい権限です。
解決策: 少なくともCreateの権限を持つCustom chat interfaceアクセスをロールに付与します。権限を追加した後にトークンをローテーションする必要はありません。
関連: Genieには複数のクライアントを設定できますが、各クライアントは1つのGenieにしか接続できません。まず、そのクライアントを現在のGenieからDetachします。
空のストリームまたは空白イベントの繰り返し
エラー: SSEストリームは開いたままですが待機中のように見え、genieが応答しません。
原因と解決策:
- キープアライブイベント: 長時間実行中または一時停止中のターンでは、ランタイムが定期的なキープアライブイベントを出力します。例: 約30秒ごとの
system.ping。ハンドラーが認識しないイベントタイプは無視します。 - Genieが開始されていない: Genieはアクティブである必要があります。
POST /api/agentic/genies/:id/startで開始します。 - ユーザーの操作待ち(スキル確認):
skill.confirmation_requiredイベントにより、スキルを承認または拒否で判断を投稿するまでターンが一時停止します。解決結果を送信すると、同じストリームが再開されます。再接続する必要はありません。複数のスキルを並行実行している場合、確認が必要な各スキルは、それぞれ固有のcall_idを持つskill.confirmation_requiredイベントを発行します。保留中の各call_idごとに解決結果を送信してください。 - ユーザーによる操作待ち(ランタイムコネクション):
runtime_connection.auth_requiredイベントが発生すると、ユーザーが上流のコネクションを帯域外で認証している間、そのターンはいったん一時停止します。クライアントが投稿する内容はなく、元のストリームは再開されません。キープアライブを出力し、その後system.stream_interruptedを出力します。statusがauthorizedになるまでランタイムコネクションリンクを取得をポーリングして完了を検出し、その後メッセージ履歴から再開された応答を読み取ります。
複数のスキルで確認が必要な場合にターンがハングする
問題: 複数のスキルを並行して実行し、複数のスキルが確認を必要とする場合に、ターンが一時停止したままになります。
原因: 以前のランタイムバージョンでは、このシナリオでターンが一時停止したままになることがありました。この問題は修正されています。
解決方法: 各skill.confirmation_requiredイベントからのすべてのcall_idに対して、解決結果を送信したことを確認してください。すべてのcall_idを解決した後もターンがハングしたままの場合は、request_idを含めてサポートに連絡してください。
イベントまたはイベントIDの重複
問題: 同じevent_idを持つ同じイベントを複数回受信します。
原因: ストリームへの再接続やGet eventsは、指定したポイントからイベントを再生します。再生されたイベントは、特にライブストリームと復旧したイベントをマージする場合、クライアントですでに処理済みのイベントと重複することがあります。
解決方法: 一意キーとしてevent_idを使用し、既に処理したイベントは破棄してください。 Genieラン内のイベントを並べ替えるには、seq_num を使用します。重複がある場合は、副作用を繰り返さないでください。同じ call_id に対して確認プロンプトをもう一度表示したり、承認をもう一度送信したりしないようにします。
切断されたストリームへの再接続
問題: processing.finishedを受信する前にSSEストリームが閉じます。
解決方法: genieランに再接続し、最後に受信したイベントから再開します。次のいずれかを使用します。
Last-Event-IDヘッダー: 最後に受信したイベントのevent_idを渡します。since_seq_numクエリパラメータ: 最後に受信したイベントのseq_numを渡します。
GET /api/v1/genies/:genie_handle/chat/conversations/:conversation_id/genie-runs/:genie_run_id?since_seq_num=<last_seq_num>system.stream_interruptedイベントを受信した場合は、last_seq_numを使用し、retry_after_msだけ待ってから再接続します。理由がbusiness_approval_pendingのprocessing.finishedイベントを受信した後は再接続しないでください。 Processing finished reasonsを参照してください。再生されたイベントはevent_idで重複排除してください。詳細については、Duplicate events or event IDsを参照してください。
イベントリカバリで何も返されない
エラー: 切断後にイベントを取得でイベントが返されません。
原因: このエラーは、誤ったパラメータまたはウィンドウを使用した場合に発生します。パラメータはsince_created_at(RFC3339タイムスタンプ)です。ページングするには、前回のレスポンスのnext_since_created_atを渡します。イベントは24時間保持されます。
ファイルアップロードが拒否される
エラー: アップロードエンドポイントへの呼び出しが失敗するか、genieが添付ファイルを受け取りません。
原因と解決策:
- ファイルが大きすぎる: 各アップロードで受け付けるファイルは1個で、最大サイズは 20 MB です。ファイルを縮小するか分割します。
- リクエスト形式が間違っている: 単一の
fileフィールドを使用して、ファイルをmultipart/form-dataとして送信します。Content-Typeを手動で設定しないでください。 HTTPクライアントがmultipart境界を設定します。 - 添付ファイルが参照されていない: ファイルをアップロードしても、それだけでは添付されません。返された
file_idを、メッセージを送信のfile_idパラメータで渡します。
会話トピックでテキストではなく数値が返される
問題: GET /conversations/:conversation_idで、読み取り可能なタイトルではなく5951のような数値のtopicが返されます。
原因: Genieは、ユーザーの最初のメッセージから会話のtopicを自動生成しますが、これには少し時間がかかります。生成が完了する前にGET /conversations/:conversation_idを呼び出すと、topicはまだ数値のプレースホルダーです。会話を一覧表示エンドポイントは、準備が完了すると生成されたtopicを返します。
解決策: 表示には会話を一覧表示エンドポイントを使用するか、topicが数値の場合は会話の最初のユーザーメッセージにフォールバックします。
リロード後またはストリーム切断後に会話タイムラインを再構築する
問題: ページのリロード後またはSSEストリームの切断後に、skill.*イベントやprocessing.*イベントを含む完全なターンが必要ですが、ライブストリームで到着したものしかありません。
原因: ライブストリームだけでなく、すべての会話イベントが永続化されます。 skill.*やprocessing.*を含むすべてのイベントタイプは、発生後24時間、イベントを取得から取得できます。
解決策: GET /conversations/events?conversation_id=<conversation_id>&since_created_at=<RFC3339>で永続化されたイベントを取得し、順番に再生して完全なタイムラインを再構築します。 skill.*イベントとprocessing.*イベントをライブストリーム中にのみ利用可能なものとして扱わないでください。
例外が1つあります: runtime_connection.auth_requiredによる一時停止後に再開されたターンは、イベントを取得ではキャプチャされません。永続化されたイベントは一時停止時点で停止します。その応答をメッセージ履歴からリカバリしてマージし、message_idで重複排除します。
ヘルプを利用する
すべてのランタイムレスポンスには、request_idとx-request-idヘッダーが含まれます。 Workatoサポートに問い合わせる際は、ゲートウェイでリクエストを追跡できるように、これらの値を含めてください。
最終更新日: