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
Interactive Demo
basic_example.py
Python
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}"output
live
Click "Run Demo" to see xray in action...
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
@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"Adaptive Behavior
Change tool behavior based on execution context
@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}"Debug Complex Flows
Get full visibility into multi-step agent processes
@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"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