Debugging Your Agent

Before diving into policies and authentication, let's learn the debugging tools you'll need throughout your AgentVisor™ journey.

What You'll Learn

• Using standard Python logging instead of print()
• Controlling host and agent log levels
• Reading access logs for policy decisions

Agent Logging

Inside the AgentVisor sandbox, stdout is reserved for result data — any print() output is captured internally and never shown in normal operation. Use standard Python logging instead:

import logging

logger = logging.getLogger(__name__)

def my_node(state):
    logger.info("Processing query")
    logger.debug("State: %s", state)
    # ...

The logger writes to stderr, which is captured and forwarded to the host — no agentvisor import or setup required. See Agent Logging for details on how this capture works.

Host Log Levels

Control the host runtime's verbosity with AGENTVISOR_LOG_LEVEL:

# See detailed host-level logs (proxy, policy, lifecycle)
AGENTVISOR_LOG_LEVEL=debug agentvisor serve .

This is useful for seeing what's happening under the hood — internal calls, sandbox lifecycle, proxy requests, and more.

Level	What You'll See
error	Only errors
warn	Warnings and errors
info	Normal operation (default)
debug	Detailed internal operations
trace	Everything, including raw data

Agent Log Levels

Control your agent code's log verbosity using the agent component override:

# Show DEBUG-level logs from your Python agent code, keep everything else at INFO
AGENTVISOR_LOG_LEVEL=info,agent=debug agentvisor serve .

This only affects your Python agent code's logs. To make everything verbose at once:

# Set all components (host + agent) to debug
AGENTVISOR_LOG_LEVEL=debug agentvisor serve .

Access Logs

When you add policies later, you'll want to see allow/deny decisions. Enable pretty-printed access logs:

agentvisor serve . --access-log-pretty-print

Or via environment variable:

AGENTVISOR_AUTHZ_EMBEDDED_ACCESS_LOG_FORMAT=pretty agentvisor serve .

This produces indented JSON showing the full policy evaluation for each request — the principal, resource, decision, and which policy rules matched. You'll use this extensively when debugging policy rules.

Example output (you'll see this in action in the Adding Policies tutorial):

{
  "decision": "DENY",
  "operation": "agentvisor:http:request",
  "principal": {
    "subject": "anonymous"
  },
  "resource": "mrn:agentvisor:http:example.com/"
}

note

HTTP MRNs strip the default port for the scheme (:443 for HTTPS, :80 for HTTP) — a request to https://example.com/ becomes mrn:agentvisor:http:example.com/, not ...example.com:443/. A non-default port (e.g. :8443) is preserved. If you write a policy selector with an explicit default port, it won't match.

Interactive Debugging with IDE

For step-by-step debugging with breakpoints and variable inspection, AgentVisor supports remote debugging via pluggable debug providers. This works with VS Code, PyCharm, and other IDEs.

Interactive debugging requires running your agent in --sandbox=none mode with a local Python environment. This bypasses container isolation to enable debugger attachment.

Choosing a Debug Provider

AgentVisor supports multiple debug providers. Choose based on your IDE and preferences:

Feature	debugpy (default)	pydevd
Protocol	DAP (Debug Adapter Protocol)	pydevd
Default IDE	VS Code	PyCharm
Install	pip install debugpy	pip install pydevd-pycharm
Cython speedups	No	Yes
Use when	VS Code or any DAP client	PyCharm with native features

Quick start:

# Default (debugpy) - works with VS Code and PyCharm
agentvisor run ./my-agent --sandbox=none --debug

# PyCharm native (pydevd) - better PyCharm integration
agentvisor run ./my-agent --sandbox=none --debug --debug-provider=pydevd

Provider-Specific Guides

• Local Development Setup — Python environment setup, VS Code and PyCharm debugging (DAP and native pydevd)

Next Steps

• Configuring AgentVisor: Runtime configuration with agentvisor.yaml and environment variables
• See Agent Logging for structured logging, JSON output, custom fields, and log file configuration
• See Local Development Setup for setting up --sandbox=none mode