ConnectOnionConnectOnion
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 - Updated Oct 20, 2025)

Available now: Continue, Edit variables (Python REPL), Quit, Source display
Coming Nov 2: 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
1from connectonion import Agent, xray 2 3@xray # Tools with @xray become breakpoints 4def search_emails(query: str): 5 return api.search(query) 6 7def send_email(to: str, body: str): 8 return api.send(to, body) 9 10agent = Agent( 11 name="email_assistant", 12 tools=[search_emails, send_email] 13) 14 15# Launch interactive debug session 16agent.auto_debug()
Python REPL
Interactive
๐Ÿ” 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
1What do you want to do? 2 โ†’ Continue execution [Enter or c] 3 ... 4 5> c
Python REPL
Interactive
โ†’ 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
1> e 2 3โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” 4Python Editor - Modify variables to test scenarios 5โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” 6 7Available variables: query, result, tool_args 8 9>>> result 10'Found 1 email from john@company.com' 11 12>>> # Test: What if we found 3 emails? 13>>> result = ["email1@ex.com", "email2@ex.com", "email3@ex.com"] 14 15>>> result 16['email1@ex.com', 'email2@ex.com', 'email3@ex.com']
Python REPL
Interactive
>>> # 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
1@xray 2def search_products(query: str): 3 return api.search(query) 4 5def filter_results(products: list, criteria: dict): 6 return [p for p in products if matches(p, criteria)] 7 8def rank_by_popularity(products: list): 9 return sorted(products, key=lambda p: p['sales'], reverse=True) 10 11agent = Agent( 12 name="shop_assistant", 13 tools=[search_products, filter_results, rank_by_popularity] 14) 15 16agent.auto_debug()
Python REPL
Interactive
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
Providers
Next
Auto Debug Exception