DocsQuick Start

Quick Start Guide

Get up and running with ConnectOnion in under 2 minutes.

7 steps · ~2 minutes

1Install ConnectOnion10s 2Create Your First Agent20s 3Run Your Agent10s 4Customize Your Agent5 min 5Playwright Web Automation5 min 6Create a Custom Tool Agent5 min 7Debugging with @xray2 min

1Install ConnectOnion

Terminalbash

$pip install connectonion

2Create Your First Agent

Create a new agent project with automatic setup:

Terminalbash

$co create my-agent

$cd my-agent

Files created:

my-agent/

├──🐍agent.py# Ready-to-run agent with example tools

├──.env# API keys (auto-configured)

├──co-vibecoding-principles-docs-contexts-all-in-one.md# Complete framework docs

├──.gitignore# Git config

└──.co/# ConnectOnion config

├──host.yaml

└──docs/

└──co-vibecoding-principles-docs-contexts-all-in-one.md

The CLI handles:

•API key setup - Automatic detection from environment or interactive input
•Project structure - All files created and configured
•Documentation - Complete framework docs included
•Git configuration - .gitignore ready for version control

3Run Your Agent

Terminalbash

$python agent.py

Your agent is ready to use! The minimal template includes example tools to get you started.

4Customize Your Agent

Your meta-agent can help you build ConnectOnion projects:

main.py
python
# Learn about ConnectOnion
result = agent.input("What is ConnectOnion and how do tools work?")
print(result)
output
>>> result = agent.input("What is ConnectOnion and how do tools work?")
>>> print(result)
ConnectOnion is a Python framework for building AI agents with a focus on simplicity.
Here's how it works:
 
1. **Agent Creation**: Create agents with a name, tools, and optional system prompt
2. **Tools**: Functions that agents can call. Any Python function can be a tool!
3. **Automatic Schema Generation**: Type hints are converted to OpenAI function schemas
4. **Iteration Control**: Use max_iterations to prevent infinite loops
5. **Built-in Logging**: All agent interactions are automatically logged to `.co/logs/`
 
Tools work by:
- Converting Python functions to OpenAI-compatible schemas
- The agent decides when to call tools based on the task
- Tool results are fed back to the agent for further processing
- Multiple tools can be called in sequence to complete complex tasks

main.py
python
# Generate agent code
result = agent.input("Create a web scraper agent")
print(result[:500] + "...")  # Show first 500 chars
output
>>> result = agent.input("Create a web scraper agent")
>>> print(result[:500] + "...")
Here's a complete web scraper agent using ConnectOnion:
 
```python
from connectonion import Agent
import requests
from bs4 import BeautifulSoup
 
def scrape_url(url: str) -> str:
    """Scrape content from a URL."""
    response = requests.get(url)
    soup = BeautifulSoup(response.text, 'html.parser')
    return soup.get_text()[:1000]
 
def extract_links(url: str) -> list[str]:
    """Extract all links from a webpage."""
    response = requests.get(url)
    soup = BeautifulSoup(response.text, 'html.parser')
    return [a['href'] for a in soup.find_all('a', href=True)]...

main.py
python
# Create tool functions
result = agent.input("Generate a tool for sending emails")
print(result)
output
>>> result = agent.input("Generate a tool for sending emails")
>>> print(result)
Here's an email sending tool for your agent:
 
```python
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
 
def send_email(to: str, subject: str, body: str, from_email: str = "agent@example.com") -> str:
    """Send an email to the specified recipient.
    
    Args:
        to: Recipient email address
        subject: Email subject line
        body: Email body content
        from_email: Sender email address
        
    Returns:
        Status message indicating success or failure
    """
    try:
        msg = MIMEMultipart()
        msg['From'] = from_email
        msg['To'] = to
        msg['Subject'] = subject
        msg.attach(MIMEText(body, 'plain'))
        
        # Configure your SMTP server
        server = smtplib.SMTP('smtp.gmail.com', 587)
        server.starttls()
        server.login(from_email, 'your_app_password')
        server.send_message(msg)
        server.quit()
        
        return f"Email sent successfully to {to}"
    except Exception as e:
        return f"Failed to send email: {str(e)}"
```
 
Usage: agent = Agent("mailer", tools=[send_email])

Going Further

Steps 5–7 are optional specialization paths — pick what matches your use case.

altPlaywright Web Automation

For web automation tasks, use the Playwright template:

Terminalbash

$co create my-browser-bot --template playwright

$cd my-browser-bot

Stateful browser tools included:

•start_browser() - Launch browser

•navigate() - Go to URLs

•scrape_content() - Extract content

•fill_form() - Complete forms

•take_screenshot() - Capture pages

•extract_links() - Get all links

•click() - Click elements

•execute_javascript() - Run JS

Note: Requires pip install playwright && playwright install

5Create a Custom Tool Agent

You can also create agents from scratch with custom tools:

main.py
python
from connectonion import Agent

def calculate(expression: str) -> str:
    """Safely evaluate mathematical expressions."""
    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)}"

# Create agent with the tool
agent = Agent(
    name="calculator", 
    tools=[calculate],
    system_prompt="You are a helpful math tutor.",
    max_iterations=5  # Simple calculations need few iterations
)

# Use the agent
response = agent.input("What is 42 * 17 + 25?")
print(response)
output
Let me calculate that for you.
 
42 * 17 = 714
714 + 25 = 739
 
The answer is 739.

6Debugging with @xray

Use the @xray decorator to see what your agent is thinking:

main.py
python
from connectonion import Agent
from connectonion import xray

@xray
def calculate(expression: str) -> str:
    """Math tool with debugging enabled."""
    print(f"[SEARCH] Agent '{xray.agent.name}' is calculating: {expression}")
    print(f"[SEARCH] User's original request: {xray.task}")
    print(f"[SEARCH] This is iteration #{xray.iteration}"

    result = eval(expression)
    return f"Result: {result}"

agent = Agent("debug_calc", tools=[calculate], max_iterations=5)
response = agent.input("What's 50 + 30?")
print(response)
output
[SEARCH] Agent 'debug_calc' is calculating: 50 + 30
[SEARCH] User's original request: What's 50 + 30?
[SEARCH] This is iteration #1
Result: 80
 
The result is 80.

7Interactive Debugging

Debug your agents interactively - pause at breakpoints, inspect state, and test "what if" scenarios:

main.py
python
from connectonion import Agent, xray

@xray  # Breakpoint: pause here for inspection
def search_database(query: str) -> str:
    results = db.search(query)
    return f"Found {len(results)} results"

agent = Agent(
    name="search_bot",
    tools=[search_database],
    system_prompt="You are a helpful search assistant"
)

# Launch interactive debug session
agent.auto_debug()
output
🔍 Interactive Debug Session Started
Agent: search_bot | Tools: 1
 
💡 Quick Tips:
  - Tools with @xray will pause for inspection
  - Use arrow keys to navigate menus
  - Press 'c' to continue
 
Type your message to the agent:
> Find recent Python tutorials
 
→ Tool: search_database({"query": "Python tutorials"})
← Result: Found 5 results
 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@xray BREAKPOINT: search_database
 
Local Variables:
  query = "Python tutorials"
  result = "Found 5 results"
 
What do you want to do?
  → Continue execution 🚀       [c or Enter]
    Edit values 🔍             [e]  ← Test "what if" scenarios
    Quit debugging 🚫          [q]
 
> c
 
✓ Task complete