VS Codeでのエージェントのデバッグ¶

VS Codeでは、エージェント開発サーバーを強化するのと同じdev.pyスクリプトを実行できるため、リモートデバッガーを接続せずに、リクエストのステップ実行、変数の確認、プロンプトの再生ができます。 agent-applicationのクローンを作成した後に必要な操作は、エージェントの仮想環境でVS Codeを指定して、dev.pyをターゲットとする起動設定を作成し、デバッガーがリッスンしている間にCLIからプロンプトを実行するだけです。

このガイドはPyCharmのワークフローに準拠し、VS Codeの準備、デバッガーの起動、および一般的な問題のトラブルシューティングについて順を追って説明します。

前提条件¶

VS Codeのデバッグを設定する前に、以下が揃っていることを確認します。

VS Code + Python拡張機能：デバッグをサポートするため、Microsoft公式のPython拡張機能をインストールします。設定のガイダンスが必要な場合は、ドキュメントを参照してください。
エージェントアプリケーションの設定：インストールを完了し、task startを実行して、エージェントの仮想環境を作成します。
環境変数：.envにDATAROBOT_API_TOKEN、DATAROBOT_ENDPOINT、およびツール固有の変数を設定します。
CLIへのアクセス：デバッガーの動作中にターミナルからtask <agent>:cliコマンドを実行し、処理をトリガーできます。

Configure Python interpreter¶

Run task start first

task startは、依存関係と.venvインタプリタをプロビジョニングします。 VS Codeでインタプリタを選択する前に実行します。

VS Codeでエージェントアプリケーションフォルダー（writer_agentなど）を開きます。
Command+Shift+P（macOS）またはCtrl+Shift+P（Windows/Linux）を押してコマンドパレットを開きます。
Python: Select Interpreterを実行します。
エージェントの.venvパス内にあるインタプリタを選択します。 writer_agentの場合、エントリーは通常次のようになります。
```
$workspace/writer_agent/.venv/bin/python 
```

VS Codeでは、このインタプリタをリンティング、統合ターミナル、デバッガーに使用します。これにより、環境がtaskによって作成されたものと一致します。

Run Agentの起動設定を行う¶

VS Codeのデバッガーは、.vscode/launch.jsonを使用します。 dev.pyを指すRun Agent設定を作成することで、PyCharmガイドと同じレイアウトを再利用できます。

Run and Debugビュー（サイドバーの再生アイコン）を開き、create a launch.jsonファイルをクリックします。
デバッガーとしてPython Debuggerを選択します。
デバッグ設定としてPython Fileを選択します。
自動生成された.vscode/launch.json設定を以下のスニペットのようなものに置き換え、エージェントへのパスを調整します。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run Agent",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/writer_agent/dev.py",
            "cwd": "${workspaceFolder}/writer_agent",
            "envFile": "${workspaceFolder}/.env",
            "console": "integratedTerminal",
            "python": "${workspaceFolder}/writer_agent/.venv/bin/python",
            "justMyCode": true
        }
    ]
}

program：エージェントのdev.pyを指します。
cwd：相対インポートとファイルパスがエージェントディレクトリから解決されるようにします。
envFile：CLIが使用するのと同じ.env設定をロードします。
python：選択済みの.venvインタプリタをデバッガーで使用するように強制します。

ワークスペースに複数のエージェントが含まれている場合は、定期的にデバッグするエージェントごとに、異なる名前とパスで設定を複製します。

開発サーバーの実行¶

開発サーバーを起動するには： 1. Run and DebugビューでRun Agent設定を開きます。 2. Runをクリックし（またはF5を押し）、デバッガーで開発サーバーを起動します。 3. Debug ConsoleまたはTerminalで起動メッセージ（例：Running development server on http://localhost:8842）を確認します。

VS Codeはリクエストをリッスンするようになり、ブレークポイントを設定すると一時停止します。

Trigger agent execution from the CLI¶

開発サーバーがリッスンしている場合は、任意のターミナルセッションからプロンプトを送信できます。 CLIでwriter_agentを呼び出す例：

task writer_agent:cli -- execute --user_prompt "Artificial Intelligence"

すべてのCLIリクエストはVS Codeのデバッガーセッションを経由するため、問題を特定するまで同じプロンプトを繰り返したり、引数を調整したりできます。

Debug with breakpoints¶

ブレークポイントを使用したデバッグを設定するには： 1. writer_agent/custom_model/agent.pyのようなファイルにブレークポイントを設定します。 2. Run > Start Debuggingをクリックして（またはF5を押して）、デバッガーがアクティブになっていることを確認します。 3. Re-run your CLI command. 実行がブレークポイントに達すると、VS Codeは一時停止し、その行を強調表示します。 4. デバッグツールバーを使用して、ステップオーバー、ステップイン、または実行の継続を行います。

VS Codeのデバッグツールを使う¶

以下のセクションでは、VS Codeのデバッグでサポートされている各種ツールについて説明します。

Inspect variables¶

Variablesペインには、一時停止したフレームのローカル、グローバル、および環境データが表示されます。
変数を右クリックしてAdd to Watchを選択し、フレーム間で永続的に追跡します。

Evaluate expressions¶

Debug Consoleを使用して、一時停止中のコンテキストでPython式を実行します（例：import osの後にos.environ["DATAROBOT_ENDPOINT"]を実行）。
コードのステップ実行中に式を監視する必要がある場合は、Watchに式を追加します。

コールスタックの確認¶

Call Stackビューには、ブレークポイントにつながるすべてのフレームが表示されます。
フレームを選択すると、エディター、Variablesペイン、Debug Consoleのコンテキストが更新され、以前のコールを確認できるようになります。

よくある問題¶

起動設定がない¶

問題：Run Agentオプションが表示されません。

Solution:

ワークスペース内に.vscode/launch.jsonが存在し、設定が含まれていることを確認します。
ファイルが削除された場合は、コマンドパレットオプションPython Debugger: Debug using launch.jsonを使用してファイルを再生成します。

インタプリタが間違っている¶

問題：VS Codeでパッケージをインポートできません。または、Pythonのバージョンに関するエラーが表示されます。

Solution:

Python: Select Interpreterを実行し、task startによって作成された.venvインタプリタを選択します。
環境を再構築した場合は、ウィンドウをリロードし（Developer: Reload Window）、インタプリタを選択し直します。
.vscode/launch.jsonのpythonエントリーが、選択した.venv/bin/pythonパスを指していることを確認します。これにより、デバッガーが正しいランタイムで起動します。

環境変数がロードされていない¶

問題：デバッグ中に資格情報が見つからないため、エージェントが失敗します。

Solution:

リポジトリのルートに.envファイルが存在し、DATAROBOT_API_TOKENとDATAROBOT_ENDPOINTが含まれていることを確認します。
launch.jsonのenvFileエントリーが.envパスに一致することを確認します。

CLIがブレークポイントにヒットせずに終了する¶

問題：CLIコマンドは完了しますが、デバッガーが想定どおりに一時停止しません。

Solution:

CLIコマンドを起動する前に、デバッガが実行されていること（VS Codeの緑色のバー）を確認します。
ブレークポイントが赤で塗りつぶされ（白抜きではない）、選択したプロンプトに対して実行されるコード内にあることを確認します。
デバッガーを再起動した後、CLIコマンドを再実行します。開発サーバーは一度に1つのリクエストを処理します。

デバッガーがアタッチされていない¶

問題：VS Codeは起動しますが、サーバーバナーの表示やブレークポイントでの停止がありません。

Solution:

セッションを停止して再起動し、dev.pyが正常に再起動したことを確認します。
programとcwdが同じエージェントディレクトリを参照していることを確認します。パスが一致しないと、VS Codeでは、コードの間違ったコピーがデバッグされます。
Debug Consoleで、依存関係がないことを示すスタックトレースの有無を調べ、必要に応じてtask startを再実行します。