Debugging agents in PyCharm¶

Debugging agent code is essential for understanding execution flow, inspecting variables, and troubleshooting issues during development. After you clone the agent-application, PyCharm will automatically have a Run Agent run/debug configuration that points to the dev.py script in your agent directory. This script starts the agent development server and gives you an immediate way to run or debug your agent without wiring up a remote debug server.

This guide walks you through configuring PyCharm to use your agent's virtual environment, running the autogenerated Run Agent configuration, and attaching the debugger while you execute prompts with the CLI.

Prerequisites¶

Before setting up PyCharm debugging, ensure you have:

• PyCharm Professional: Required for full debugging support
• Agent application setup: Completed the installation and run task start to prepare your local environment
• Environment configured: Your .env file is properly configured with DATAROBOT_API_TOKEN and DATAROBOT_ENDPOINT

Configure Python interpreter¶

Before you can debug your agent, you need to configure PyCharm to use the correct Python interpreter for your agent environment.

Set up the Python interpreter¶

1. Open your agent templates repository in PyCharm.
2. Navigate to PyCharm > Settings.
3. Go to Python > Interpreter.

4. Click the Python Interpreter dropdown (it may show No interpreter) and select Add Interpreter > Add Local Interpreter.

   

5. In the Add Python Interpreter dialog, select Select existing and choose Python as the type. Select your agent's virtual environment Python executable in the .venv path of your agent framework. (The virtual environment is created by uv when you run task start or task install). For example, the interpreter path for writer_agent should look like:

   $workspace/writer_agent/.venv/bin/python
   

   

PyCharm will use this interpreter for running and debugging your agent code, ensuring all dependencies are correctly resolved.

Use the Run Agent configuration¶

The Run Agent configuration launches the agent development server with your environment variables and interpreter already wired up.

1. Open Run > Edit Configurations to review the configurations for Run Agent.
2. Ensure the configuration points to your agent's dev.py script, sets the working directory to the agent folder, and references your .env file. No additional parameters are required.

3. Select Run Agent from the configuration dropdown and click Run. PyCharm starts the development server and shows its console output (for example, Running development server on http://127.0.0.1:8842).

   

Trigger agent execution from the CLI¶

With the development server running in PyCharm, you can execute agent prompts from a terminal window.

1. Open a terminal in your agent application repository root.

2. Run the CLI command for your agent (example below for writer_agent):

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

3. Watch the PyCharm console for log output as the agent processes the request. Adjust the prompt text or CLI arguments to match your scenario.

Debug with breakpoints¶

The same Run Agent configuration supports PyCharm's debugger.

1. Set breakpoints in the files you want to inspect (for example, writer_agent/custom_model/agent.py).

2. In PyCharm, choose the Run Agent configuration and click the Debug icon (or press Shift+F9). PyCharm launches dev.py in debug mode and waits for incoming work.

   

3. Re-run your CLI command. When execution reaches your breakpoint, PyCharm pauses and opens the Debug tool window so you can inspect state, step through code, and evaluate expressions.

   

Use debug features¶

Once execution stops on a breakpoint, you can use PyCharm's debugging capabilities:

Inspect variables¶

• The Threads & Variables pane shows all variables in the current scope.
• Expand objects to see their properties and values.
• Right-click variables to add them to Watches for persistent monitoring.

Evaluate expressions¶

• Click the Evaluate Expression button in the debug toolbar (calculator icon) or right-click in the current context and select Evaluate Expression.
• Enter any Python expression to evaluate it in the current context (for example, os.environ).
• Useful for testing conditions, examining complex objects, or calling methods.

View call stack¶

• The Frames pane shows the call stack, displaying how execution reached the current point.
• Click different frames to see variables and code at each level.

Common issues¶

Run Agent configuration is missing¶

Issue: PyCharm does not show the Run Agent configuration.

Solution:

• Check that your project files (such as .idea/runConfigurations/Run Agent.run.xml) are not excluded from your VCS or workspace.
• Restart PyCharm to force it to reload project metadata.
• Re-clone the agent-application repo.

CLI command finishes without hitting breakpoints¶

Issue: The agent finishes processing and never pauses where you expect.

Solution:

• Make sure you launched the Run Agent configuration in Debug mode, not regular Run.
• Verify your breakpoint is active (solid red) and located in code that executes for the selected prompt.
• Re-run the CLI command after PyCharm shows that the debugger is listening.

Environment variables missing¶

Issue: The agent fails due to missing credentials or configuration.

Solution:

• Confirm your .env file exists at the repository root and includes DATAROBOT_API_TOKEN and DATAROBOT_ENDPOINT.
• In the Run Agent configuration, ensure the Paths to ".env" files field points to the correct file.

Wrong Python version¶

Issue: PyCharm shows "Python version mismatch" errors or modules are missing.

Solution:

• Confirm you've configured the correct Python interpreter (the one in your agent's virtual environment).
• If you recently recreated the environment, click the interpreter dropdown and re-select the .venv Python executable.

Breakpoints not working¶

Issue: Execution doesn't stop at breakpoints even in Debug mode.

Solution:

• Confirm the debugger console shows the development server restarted after you clicked Debug. If not, stop and start the configuration again.
• Check that you reran the CLI command after entering debug mode—the development server handles one request at a time.
• Ensure PyCharm mapped your project correctly. If you're using multiple agent templates, verify you're editing the same copy of the file that the development server runs.