このページでは、Agent Framework の使用時に発生する一般的な問題の診断と解決について説明します。
目次:
インストールとセットアップ
一般的な問題: インストールの失敗、インポート エラー、API 認証の問題。
確認:
- Python と pip のバージョン
.whlファイルの整合性とパス.envファイルの構成（API キー、プロジェクトの詳細）gcloud authの設定（Vertex AI の場合）- 依存関係のインストール（
requirements.txt） - 仮想環境の有効化
エージェントの定義に関する問題
一般的な問題: エージェントが想定どおりに動作しない、ツールが呼び出されない、agent.py でエラーが発生する。
確認:
agent.pyコードの構文（リンティング）- エージェント
instructionの明確性と正確性 - ツールの定義（名前、説明、パラメータ）
- エージェント属性（
name、model、tools、flow）- スペルミス、有効性 agent.py内のコードロジック - デバッグに print ステートメントを使用する
実行に関する問題
一般的な問題: CLI コマンドが失敗する（af run、af web、af test）、ウェブ UI エラー、API サーバーの問題。
確認:
- CLI コマンドの構文と引数（
--help） - 作業ディレクトリ（エージェント プロジェクトのルート）
- ターミナルのエラー メッセージ（エラーの全文をコピー）
- ポートの競合（ウェブ UI/API サーバーの場合 - 別のポートを試す）
- ブラウザの互換性（ウェブ UI の場合）
- ブラウザ コンソール エラー（ウェブ UI の場合）
評価に関する問題
一般的な問題: テストの失敗、予期しない評価結果。
確認:
*.test.jsonファイルの構文（有効な JSON）- テストファイルの内容（クエリ、
expected_tool_use、referenceの精度） af testコマンドまたはpytestコードのファイルパスtest_config.jsonの評価基準（使用する場合）- ウェブ UI でテストを実行して視覚的なフィードバックを確認する
一般的なエラー メッセージ
- インストールに関する問題
- API キーまたは認証の問題
model属性が正しくない- ウェブサーバーまたは API サーバーでポート競合が発生する
一般的なトラブルシューティングのヒント:
- 簡素化と分離: シンプルなものから始めて、徐々に複雑さを追加します。
- ログを確認する: ターミナル、Cloud Logging、ブラウザ コンソール。
- ドキュメントを参照し、関連するセクションを読み直します。
- オンラインで検索: Stack Overflow、フォーラム。
- サポートを依頼する際は詳細情報を提供してください。コード、エラー、手順、環境。