ConnectOnionConnectOnion
Debug Agents Interactively

Debug Your AI Agents Like Code

Pause at breakpoints, inspect state, modify variables, and explore "what if" scenarios. Just like debugging regular code, but for AI agents.

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 2from connectonion.decorators import xray 3 4@xray # Tools with @xray become breakpoints 5def search_emails(query: str): 6 return api.search(query) 7 8def send_email(to: str, body: str): 9 return api.send(to, body) 10 11agent = Agent( 12 name="email_assistant", 13 tools=[search_emails, send_email] 14) 15 16# Launch interactive debug session 17agent.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
Send Email
Next
Auto Debug Exception