FactVerse AI Agent トラブルシューティング
AI クライアントが FactVerse AI Agent に接続しているものの、ワークフローが期待どおり完了しない場合にこのガイドを使います。ワークフローロジックを調べる前に、endpoint、API key、scope、ソースデータ境界を確認します。
クイック確認順序
- クライアントが期待する host と endpoint を使っていることを確認します。
- リクエストが
X-API-Key を送信していることを確認します。
- 実行時にツールを一覧し、見えるツールを期待するワークフローと比較します。
- API key の scope とツール scope が一致することを確認します。
- ソースデータの鮮度、アセットマッピング、文書可用性、シーンバージョンを確認します。
- 書き込みアクションのブロックを調査する前に、承認ポリシーを確認します。
接続と認証
| 症状 | 主な原因 | 確認 | 修正 |
|---|
ゲートウェイが 403 を返す | API key header が不足している | リクエスト headers を確認 | X-API-Key で key を送信 |
ゲートウェイが 401 を返す | key が無効、失効、期限切れ、または別環境向け | 管理者に key 状態を確認 | key をローテーションまたは再発行 |
| クライアントが誤ったルートへ接続する | endpoint パスまたは host が違う | /mcp/base/、/mcp/pdm/、有効化済み module endpoint と比較 | クライアント server URL を更新 |
| TLS またはネットワーク失敗 | クライアントが顧客 host に到達できない | 同じネットワークから host をテスト | ネットワーク、プロキシ、DNS、証明書信頼を修正 |
ツール可視性と scope
| 症状 | 主な原因 | 確認 | 修正 |
|---|
| 期待するツールが見えない | endpoint 違い、module 無効、key の scope 不足 | 実行時ツールディスカバリを実行 | 正しい endpoint を使うか必要 scope を申請 |
| scope が拒否される | key が必要 scope を持っていない | ツール scope と scope リファレンスを比較 | 管理者経由で key ポリシーを更新 |
| ツール一覧が空 | endpoint は到達可能だが module 設定が使えない | デプロイ環境の module 有効化状態を確認 | module を有効化するか対応 endpoint を使う |
| 書き込みツールが見えない | key が読み取り専用、または承認ポリシーが書き込みを制限 | base.action.write とワークフローポリシーを確認 | 書き込み承認まで出力をドラフトとして保持 |
データとアセットの問題
| 症状 | 主な原因 | 確認 | 修正 |
|---|
| アセットを解決できない | Platform、Inspector、DFS、文書で名称または ID が一致しない | サイト、エリア、設備 ID、別名で検索 | 確認後にアセットマッピングを更新 |
| 回答が曖昧 | ソースデータが不足、古い、または範囲が広すぎる | データタイムスタンプとクエリ境界を確認 | 境界を絞るかデータパイプラインを修正 |
| 最近の作業記録がない | Inspector または外部作業指示記録が同期されていない | 最新同期時刻とソースシステム状態を確認 | コネクタを更新して再実行 |
| 文書を利用できない | 文書がテナント、権限、知識 scope の外にある | 文書権限とテナント割当を確認 | 文書アクセスを更新するか正しいソースを添付 |
予知保全の問題
| 症状 | 主な原因 | 確認 | 修正 |
|---|
| 健全性サマリーが弱い | 信号履歴が短い、疎である、またはマッピングされていない | 信号期間、サンプリング間隔、単位、欠損を確認 | データ準備レポートを返し、入力データを修正 |
| 異常に説明が付かない | 保全文脈または運転モードが不足している | 異常期間、作業履歴、モード変化を比較 | 作業記録、点検メモ、運転状態を添付 |
| アラートが多すぎる | アセット群またはしきい値設定が広すぎる | アセット境界としきい値ポリシーを確認 | 保全エンジニアと調整 |
| 後続アクションがブロックされる | エンジニアレビューまたは書き込み scope が不足 | 承認状態と base.action.write を確認 | アクションをドラフトとして保持 |
Physical AI とシミュレーションの問題
| 症状 | 主な原因 | 確認 | 修正 |
|---|
| シーンをシミュレーションに使えない | シーンバージョンまたは必要アセットメタデータが不足 | シーンバージョン、アセットバージョン、スケール、座標系を確認 | 計算前にシナリオパッケージを準備 |
| シミュレーション挙動が弱い | 衝突、質量、関節、摩擦、制約メタデータが不完全 | SimReady 準備レビューを実行 | メタデータを修正して再確認 |
| 結果を再利用できない | 前提、バックエンドパラメータ、検証メモが不足 | シナリオパッケージと結果記録を確認 | 前提、制限、検証メモを追加 |
| 計算リクエストがブロックされる | 計算 scope または責任者承認が不足 | base.compute.run とプロジェクト承認を確認 | エンジニアリング責任者に回す |
エスカレーション記録
製品または実装支援が必要な場合は、この記録を残します。
| フィールド | 説明 |
|---|
| 環境 | Host、endpoint、テナントまたはプロジェクト識別子、デプロイ種別。 |
| リクエスト | ユーザータスク、対象期間、アセットまたはシーン境界、クライアント種別。 |
| ツールディスカバリ | 見えるツール、不足している期待ツール、key が持つ scope。 |
| ソース状態 | アセットマッピング、データ鮮度、文書可用性、シーンバージョン、コネクタ状態。 |
| エラー | HTTP 状態、ツールエラー、検証メッセージ、ブロックされた承認状態。 |
| レビュー責任者 | 次の判断に責任を持つオペレーター、保全エンジニア、エンジニアリング責任者、管理者。 |