DebugInteractive Debugging
DocsInteractive Debugging

Interactive Debugging

Debug your AI agents like code. Pause at breakpoints, inspect state, modify variables, and explore 'what if' scenarios.

Feature Status — v0.3.2+

Available: Continue, Edit variables (Python REPL), Quit, Source display
In progress: Ask AI, View trace, Step mode, Universal commands

Most Important: Use arrow keys to navigate menus, or press c to continue. That's all you need to know to start!

60-Second Quick Start

Add @xray to tools you want to inspect, then call agent.auto_debug():

main.py
from connectonion import Agent, xray @xray # Tools with @xray become breakpoints def search_emails(query: str): return api.search(query) def send_email(to: str, body: str): return api.send(to, body) agent = Agent( name="email_assistant", tools=[search_emails, send_email] ) # Launch interactive debug session agent.auto_debug()
output
🔍 Interactive Debug Session Started
Agent: email_assistant | Tools: 2
 
💡 Quick Tips:
- Tools with @xray will pause for inspection
- Use arrow keys to navigate menus
- Press '?' anytime for help
 
Type your message to the agent:
> Send email to John
 
────────────────────────────────────────────────────
 
Iteration 1/10
→ LLM Request (o4-mini)
← LLM Response (234ms): 2 tool calls
 
→ Tool: search_emails({"query": "John"})
← Result (123ms): Found 1 email from john@company.com
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@xray BREAKPOINT: search_emails
 
Local Variables:
query = "John"
result = "Found 1 email from john@company.com"
 
Context:
User: "Send email to John"
Iteration: 1/10
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
What do you want to do?
→ Continue execution 🚀 [c or Enter]
Edit values 🔍 [e]
Quit debugging 🚫 [q]
 
💡 Coming soon (by Nov 2): Ask AI [a], View trace [v], Step mode [s]
>

The Interactive Menu

At every @xray breakpoint, you see this menu:

What do you want to do?
  → Continue execution 🚀       [c or Enter]
    Edit values 🔍             [e]
    Quit debugging 🚫          [q]

💡 Coming soon (by Nov 2): Ask AI [a], View trace [v], Step mode [s]
>

Method 1: Arrow Keys (Beginner-friendly)

  • ↑ ↓Move selection up and down
  • EnterSelect highlighted option

Method 2: Shortcuts (Power user)

  • cContinue execution
  • eEdit variables
  • qQuit debugging

Both methods do exactly the same thing - use whichever feels natural!

Available Features

Continue Execution

Available

The most common action - just press c or Enter to continue:

main.py
What do you want to do? → Continue execution [Enter or c] ... > c
output
→ Execution resumes...
→ Tool: send_email(...)
✓ Complete

Edit Variables (Python REPL)

Available

Modify variables to test "what if" scenarios. This is a full Python REPL with access to all variables:

main.py
> e ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Python Editor - Modify variables to test scenarios ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Available variables: query, result, tool_args >>> result 'Found 1 email from john@company.com' >>> # Test: What if we found 3 emails? >>> result = ["email1@ex.com", "email2@ex.com", "email3@ex.com"] >>> result ['email1@ex.com', 'email2@ex.com', 'email3@ex.com']
output
>>> # Test: What if we found no emails?
>>> result = []
 
>>> result
[]
 
>>> # Continue with modified value
>>> /continue
 
→ Resuming with modified variables...
✓ Complete

Test any scenario: Empty results, large datasets, error cases, edge cases - just modify the variables and see how your agent handles it!

Ask AI for Help

🚧 Coming Nov 2

Get context-aware help from AI about what's happening. The AI knows your code, execution state, and history:

> a

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI Help Mode - Ask questions about execution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ai> why did it only find 1 email?

🤖 AI: The search used query="John" which is broad.
The API might be limiting results, or there's actually
only 1 email from someone named John.

You can test with modified results to see how the
agent handles multiple emails.

ai> how can I test with more emails?

🤖 AI: Switch to Python mode and modify:
result = ["email1@ex.com", "email2@ex.com", "email3@ex.com"]

ai> /menu    [Back to menu]
ai> /continue [Resume execution]

View Execution Trace

🚧 Coming Nov 2

See the complete execution history with timeline, messages, and agent state:

Timeline:
  [0] user_input: "Send email to John"
  [1] llm_call: 234ms → 2 tool calls requested
  [2] tool: search_emails ✓ 123ms ← YOU ARE HERE
  [3] (pending) tool: send_email

Total: 323ms • 2 steps • 1 iteration

Toggle Step Mode

🚧 Coming Nov 2

Pause at EVERY tool, not just @xray tools:

Press s in menu to enable:

✓ Step mode enabled - will pause at EVERY tool

→ Tool: validate_input(...)    [No @xray, but pauses!]
← Result: Valid
[BREAKPOINT]

→ Tool: fetch_data(...)
← Result: 50 records
[BREAKPOINT]

Complete User Journey

Let's walk through a full debugging session:

main.py
@xray def search_products(query: str): return api.search(query) def filter_results(products: list, criteria: dict): return [p for p in products if matches(p, criteria)] def rank_by_popularity(products: list): return sorted(products, key=lambda p: p['sales'], reverse=True) agent = Agent( name="shop_assistant", tools=[search_products, filter_results, rank_by_popularity] ) agent.auto_debug()
output
Type your message to the agent:
> Find popular purple shoes under $100
 
────────────────────────────────────────────────────
 
→ Tool: search_products({"query": "purple shoes"})
← Result: Found 15 products
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@xray BREAKPOINT: search_products
 
Local Variables:
query = "purple shoes"
result = [15 product objects]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
What do you want to do?
→ Continue execution 🚀 [c or Enter]
Edit values 🔍 [e]
Quit debugging 🚫 [q]
 
> e [Test empty result scenario]
 
>>> result = [] [What if no products found?]
 
>>> /continue
 
→ Tool: filter_results({"products": [], "criteria": ...})
← Result: []
 
→ Tool: rank_by_popularity({"products": []})
← Result: []
 
Agent: "Sorry, no purple shoes under $100 are available."
 
✓ Task complete - Agent handled empty results correctly!

Best Practices

1. Strategic @xray Placement

Add @xray to:

  • API calls and database operations
  • Complex business logic
  • Tools that often fail or have important side effects

Skip simple utilities and pure functions. Or use step mode to see everything!

2. Test Edge Cases in Python Mode

>>> # Empty results >>> result = [] >>> # Large dataset >>> result = [item for item in range(10000)] >>> # Error responses >>> result = {"error": "API timeout", "retry_after": 60} >>> # Unicode/special characters >>> result = {"name": "用户名", "emoji": "🎉"}

Time-travel debugging: Change one variable, see entire agent behavior change.

3. Use Step Mode for Complex Workflows

When you don't know which tool is causing problems:

# Normal: Only @xray breakpoints agent.auto_debug() # Deep dive: See every tool agent.auto_debug(step=True) # Or toggle during session > s [Enable step mode] > s [Disable step mode]

When to Use

Perfect For

  • ✓Development - Building and testing agents
  • ✓Debugging - Finding unexpected behavior
  • ✓Learning - Understanding agent decisions
  • ✓Testing edge cases - "What if" scenarios
  • ✓Prompt engineering - Discover what works

Not For

  • ✗Production - Requires human interaction
  • ✗Automated tests - Use assertions instead
  • ✗CI/CD pipelines - Not non-interactive
  • ✗Simple scripts - Overkill for basic tasks

Frequently Asked Questions

How do I continue execution?

Press 'c' or Enter from the menu, or type '/continue' from any mode.

What's the difference between @xray and step mode?

@xray breakpoints pause only at marked tools (selective). Step mode pauses at EVERY tool (comprehensive).

Can I still use agent.input() directly?

Yes - .auto_debug() is optional. Use it only when you need interactive debugging.

Is this slow?

No - execution speed is the same. Pausing only happens at breakpoints.

Works in Jupyter notebooks?

Yes! Works in any Python environment with terminal support.

Ready to Debug Like a Pro?

Just call agent.auto_debug() and explore!

The tips will guide you through - no memorization needed. 🔍

Previous
TUI
Chat Interface
Next
Debug
Auto Debug Exception

Star us on GitHub

If ConnectOnion saves you time, a ⭐ goes a long way — and earns you a coffee chat with our founder.