Quick Start Guide
Get up and running with ConnectOnion in under 5 minutes. Build your first AI agent with tools and automatic behavior tracking.
Estimated time: 5 minutes to first working agent
1Installation
Terminal
$ pip install connectonion
2Your First Agent (2 minutes)
Let's create a simple calculator agent that can solve math problems:
first_agent.py
from connectonion import Agent
def calculate(expression: str) -> str:
"""Safely evaluate mathematical expressions."""
try:
# Only allow safe mathematical expressions
allowed_chars = set('0123456789+-*/()., ')
if all(c in allowed_chars for c in expression):
result = eval(expression)
return f"Result: {result}"
else:
return "Error: Invalid characters in expression"
except Exception as e:
return f"Error: {str(e)}"
# Create agent with the tool
agent = Agent(
name="calculator",
tools=[calculate]
)
# Use the agent
response = agent.input("What is 42 * 17 + 25?")
print(response)Output:
Result: 739
3Adding Personality with System Prompts
Make your agent more helpful and educational by adding a system prompt:
math_tutor.py
agent = Agent(
name="math_tutor",
system_prompt="""You are a friendly math tutor. When solving problems:
1. Show your work step by step
2. Explain the reasoning
3. Encourage the user""",
tools=[calculate]
)
response = agent.input("How do I calculate 15% of 240?")
print(response)Output:
I'd be happy to help you calculate 15% of 240! Let me break this down:
To find 15% of 240, I need to multiply 240 by 0.15 (since 15% = 15/100 = 0.15).
Let me calculate that: 240 * 0.15
Result: 36.0
So 15% of 240 is 36. Great job asking for help with percentages - they're really useful in everyday life!
To find 15% of 240, I need to multiply 240 by 0.15 (since 15% = 15/100 = 0.15).
Let me calculate that: 240 * 0.15
Result: 36.0
So 15% of 240 is 36. Great job asking for help with percentages - they're really useful in everyday life!
4Debugging with @xray
Use the @xray decorator to see what your agent is thinking:
debug_example.py
from connectonion import Agent
from connectonion.decorators import xray
@xray
def calculate(expression: str) -> str:
"""Math tool with debugging enabled."""
print(f"🔍 Agent '{xray.agent.name}' is calculating: {expression}")
print(f"🔍 User's original request: {xray.task}")
print(f"🔍 This is iteration #{xray.iteration}")
try:
allowed_chars = set('0123456789+-*/()., ')
if all(c in allowed_chars for c in expression):
result = eval(expression)
return f"Result: {result}"
else:
return "Error: Invalid characters"
except Exception as e:
return f"Error: {str(e)}"
agent = Agent("debug_calc", tools=[calculate])
response = agent.input("What's 50 + 30?")Debug Output:
🔍 Agent 'debug_calc' is calculating: 50 + 30
🔍 User's original request: What's 50 + 30?
🔍 This is iteration #1
Result: 80
🔍 User's original request: What's 50 + 30?
🔍 This is iteration #1
Result: 80