Debug Mode

Debug mode provides detailed trace output for troubleshooting agent behavior. No sidecar is required.

Enabling Debug Mode

secure_agent = SecureAgent(
    agent=agent,
    policy="policy.yaml",
    mode="debug",
)

Trace Output Options

secure_agent = SecureAgent(
    agent=agent,
    mode="debug",
    trace_format="console",  # "console" or "json"
    trace_file="trace.jsonl", # Optional file output
    trace_colors=True,        # ANSI colors (console only)

Console Output Example

When running in debug mode with console output, you'll see detailed step-by-step traces:

============================================================
[predicate-secure] Session Start
  Framework: browser_use
  Mode: debug
  Policy: policy.yaml
  Principal: agent:default
============================================================

[Step 1] navigate → https://amazon.com
  └─ OK (45ms)

[Step 2] search → wireless headphones
  └─ OK (120ms)

[Step 3] click → add-to-cart-button
  ├─ Policy: ALLOWED
  │  Action: browser.click
  │  Resource: add-to-cart-button
  ├─ Cart Update:
  │  + cart_item_1
  │  ~ cart_count
  │    Before: 0
  │    After:  1
  ├─ Verification: PASS
  │  Predicate: cart_not_empty
  │  Message: Cart has 1 item
  └─ OK (85ms)

============================================================
[predicate-secure] Session End: SUCCESS
  Total Steps: 3
  Duration: 250ms
============================================================

JSON Trace Output

For programmatic processing, use JSON format:

secure_agent = SecureAgent(
    agent=agent,
    mode="debug",
    trace_format="json",
    trace_file="trace.jsonl",
)

Output (one JSON object per line):

{"event_type": "session_start", "timestamp": "2024-01-01T00:00:00Z", "data": {"framework": "browser_use", "mode": "debug"}}
{"event_type": "step_start", "timestamp": "2024-01-01T00:00:01Z", "step_number": 1, "data": {"action": "navigate", "resource": "https://amazon.com"}}
{"event_type": "step_end", "timestamp": "2024-01-01T00:00:02Z", "step_number": 1, "duration_ms": 1000, "data": {"success": true}}

Manual Tracing

You can add custom trace points in your code:

# Trace a step
step = secure_agent.trace_step("custom_action", "custom_resource")
# ... do something ...
secure_agent.trace_step_end(step, success=True)

# Trace a state change
secure_agent.trace_snapshot_diff(
    before

Using the DebugTracer Directly

For advanced use cases, you can create and configure the tracer directly:

from predicate_secure import DebugTracer, create_debug_tracer

tracer = create_debug_tracer(
    format="console",  # or "json"
    use_colors=True,
    verbose=True,
)

tracer.trace_session_start("browser_use"

Trace Event Types

Debugging Tips

1. Start with debug mode during development

Use debug mode to understand what your agent is doing before deploying with strict mode.

2. Check policy decisions

Look for policy_decision events to see which rules are matching (or not matching).

3. Inspect state changes

Use snapshot_diff to see what changed after each action.

4. Export traces for analysis

Use JSON format and write to a file for post-hoc analysis:

# View recent trace events
tail -f trace.jsonl | jq .

# Filter by event type
cat trace.jsonl | jq 'select(.event_type == "policy_decision")'

# Count events by type
cat trace.jsonl | jq -r '.event_type' | sort | uniq -c