Docs@xray Debugging

@xray Debugging

See what your AI agent is thinking. Add one decorator and unlock debugging superpowers.

Download

How @xray works

Your Function

@xray decorator

Agent Context

Full Visibility

Examples

Basic Usage

Add the @xray decorator to see inside the agent's mind. Access agent name, task, and iteration count.

main.py
python
from connectonion import xray

@xray
def my_tool(text: str) -> str:
    """Process some text."""

    # Now you can see inside the agent's mind!
    print(xray.agent.name)    # "my_assistant"
    print(xray.task)          # "Process this document"
    print(xray.iteration)     # 1, 2, 3...

    return f"Processed: {text}"
output
my_assistant
Process this document
1
 
Processed: sample data

Execution Trace

Call xray.trace() to see the complete execution flow of your agent. Perfect for understanding multi-step processes.

main.py
python
@xray
def analyze_data(text: str) -> str:
    """Analyze data and show execution trace."""

    # Show what happened so far
    xray.trace()

    return "Analysis complete"
output
Task: "Find Python tutorials and summarize them"
 
[1] • 89ms • search_database(query="Python tutorials")
    IN  → query: "Python tutorials"
    OUT ← "Found 5 results for Python tutorials"
 
[2] • 234ms • summarize_text(text="Found 5 results...", max_words=50)
    IN  → text: "Found 5 results..."
          max_words: 50
    OUT ← "5 Python tutorials found covering basics to advanced topics"
 
Total: 323ms • 2 steps • 1 iteration
 
Analysis complete

IDE Debug

Set breakpoints in your IDE and inspect the xray context. Access the full agent state including messages and previous tool calls.

main.py
python
@xray
def analyze_sentiment(text: str) -> str:
    # Set breakpoint on next line
    sentiment = "positive"  # When stopped here in debugger:
                           # >>> xray
                           # <XrayContext active>
                           #   agent: 'my_bot'
                           #   task: 'How do people feel about Python?'

    return sentiment
output
🔴 Breakpoint hit at line 3
 
>>> xray
<XrayContext active>
  agent: 'my_bot'
  task: 'How do people feel about Python?'
 
>>> xray.messages
[{'role': 'user', 'content': 'How do people feel about Python?'}, ...]
 
>>> xray.previous_tools
['search_web', 'analyze_results']
 
positive

What You Can Access

xray context object

xray.agent

Agent Instance

xray.task

User Request

xray.messages

Chat History

xray.agent

The Agent instance calling this tool

xray.task

Original request from user

xray.messages

Full conversation history

xray.iteration

Which round of tool calls (1-10)

xray.previous_tools

Tools called before this one

xray.trace()

Visual execution trace

Practical Use Cases

Understand Context

See why a tool was called and what led to it

main.py
python
@xray
def emergency_shutdown():
    print(f"Shutdown: {xray.task}")
    print(f"After: {xray.previous_tools}")

    if xray.iteration == 1:
        return "Try restarting first"

    return "System shutdown complete"
output
Shutdown: Server is not responding, please help
After: ['check_server_status', 'restart_service']
 
System shutdown complete

Adaptive Behavior

Change tool behavior based on execution context

main.py
python
@xray
def fetch_data(source: str) -> str:
    # Use cache on repeated calls
    if "fetch_data" in xray.previous_tools:
        return "Using cached data"

    # Fresh fetch on first call
    return f"Fresh data from {source}"
output
# First call:
Fresh data from database
 
# Second call (same agent session):
Using cached data

Debug Complex Flows

Get full visibility into multi-step agent processes

main.py
python
@xray
def process_order(order_id: str) -> str:
    if xray.agent:
        print(f"Agent: {xray.agent.name}")
        print(f"Request: {xray.task}")
        print(f"Messages: {len(xray.messages)}")

    return f"Order {order_id} processed"
output
Agent: sales_assistant
Request: Process order ABC123 for customer
Messages: 5
 
Order ABC123 processed

Pro Tips

Development Only

Remove @xray in production for best performance

Combine with IDE

Set breakpoints for interactive debugging

Use trace()

Call xray.trace() after runs to see full flow

Check context

Always verify xray.agent exists before using

Ready to debug like a pro?

@xray Debugging

How @xray works

Examples

Basic Usage

Execution Trace

IDE Debug

What You Can Access

xray context object

xray.agent

xray.task

xray.messages

xray.iteration

xray.previous_tools

xray.trace()

Practical Use Cases

Understand Context

Adaptive Behavior

Debug Complex Flows

Pro Tips

Development Only

Combine with IDE

Use trace()

Check context

Ready to debug like a pro?

Star us on GitHub