Quick Start Guide

Get up and running with ConnectOnion in under 2 minutes.

Download

Estimated time: 2 minutes to first working agent

1
Install ConnectOnion

Terminal

$pip install connectonion

2
Create Your First Agent

Create a new agent project with automatic setup:

Terminal

$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

├──config.toml

└──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

3
Run Your Agent

Terminal

$python agent.py

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

4
Customize Your Agent

Your meta-agent can help you build ConnectOnion projects:

main.py

# Learn about ConnectOnion
result = agent.input("What is ConnectOnion and how do tools work?")
print(result)

Python REPL

Interactive

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

# Generate agent code
result = agent.input("Create a web scraper agent")
print(result[:500] + "...")  # Show first 500 chars

Python REPL

Interactive

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

# Create tool functions
result = agent.input("Generate a tool for sending emails")
print(result)

Python REPL

Interactive

>>> 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])

5
Alternative: Playwright Web Automation

For web automation tasks, use the Playwright template:

Terminal

$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

6
Create a Custom Tool Agent

You can also create agents from scratch with custom tools:

main.py

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)

Python REPL

Interactive

Let me calculate that for you.

42 * 17 = 714

714 + 25 = 739

The answer is 739.

7
Debugging with @xray

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

main.py

from connectonion import Agent
from connectonion.decorators 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)

Python REPL

Interactive

[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.

8
Interactive Debugging

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

main.py

from connectonion import Agent
from connectonion.decorators import 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()

Python REPL

Interactive

🔍 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

🔍 Why use interactive debugging?

•Pause at breakpoints - Inspect state at any tool

•Test edge cases - Modify variables to explore "what if"

•Python REPL access - Full runtime inspection

•Step through execution - See every tool call

Learn more about interactive debugging

What's Next?

Interactive Debugging

Master breakpoints, Python REPL, and "what if" scenario testing for your agents.

Master System Prompts

Learn advanced prompting techniques to create expert agents for any domain.

Deep Dive into @xray

Master debugging and get complete visibility into your agent's decision-making.

Real-World Examples

See complete agent implementations for various use cases.

Build Custom Tools

Learn how to create powerful tools for your agents.

Introduction

Vibe Coding Guide

Quick Start Guide

1Install ConnectOnion

2Create Your First Agent

Files created:

✨ The CLI handles:

3Run Your Agent

4Customize Your Agent

5Alternative: Playwright Web Automation

Stateful browser tools included:

6Create a Custom Tool Agent

7Debugging with @xray

8Interactive Debugging

🔍 Why use interactive debugging?

What's Next?

Interactive Debugging

Master System Prompts

Deep Dive into @xray

Real-World Examples

Build Custom Tools

1
Install ConnectOnion

2
Create Your First Agent

3
Run Your Agent

4
Customize Your Agent

5
Alternative: Playwright Web Automation

6
Create a Custom Tool Agent

7
Debugging with @xray

8
Interactive Debugging