Debug with @xray

See what your AI agent is thinking

Add one decorator and unlock debugging superpowers. No more black box AI.

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

from connectonion.decorators 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}"

Python REPL

Interactive

my_assistant

Process this document

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

@xray
def analyze_data(text: str) -> str:
    """Analyze data and show execution trace."""
    
    # Show what happened so far
    xray.trace()
    
    return "Analysis complete"

Python REPL

Interactive

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

@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

Python REPL

Interactive

🔴 Breakpoint hit at line 3

>>> xray

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

@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"

Python REPL

Interactive

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

@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}"

Python REPL

Interactive

# 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

@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"

Python REPL

Interactive

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?

Trust Parameter

Tutorial: AI Agent = Prompt + Function