DocsQuick Start

Quick Start Guide

Get up and running with ConnectOnion in under 2 minutes.

3-step quick start · optional guides after

1Install ConnectOnion10s 2Create Your First Agent20s 3Run Your Agent10s 4Customize Your Agent5 min 5Browser 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# Project settings and provider credentials

├──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:

•Credential discovery - Uses environment, project .env, or your global ConnectOnion login
•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
# List the bundled skills, then copy one into this project
co skills list
co skills copy co-browser --to-project
output
Copied co-browser to .co/skills/co-browser
 
Run it from co ai as /co-browser.

main.py
python
# Connect Google in the browser once
co auth google

# Use the supported command instead of embedding an SMTP password
co gmail send alice@example.com "Hello" "Sent with ConnectOnion"
output
Email sent successfully.
 
Use co doctor to inspect the OAuth source and expiry without printing tokens.

Going Further

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

altBrowser Web Automation

The default co-ai project already includes browser automation:

Terminalbash

$co create my-agent

$cd my-agent

Stateful browser tools included:

•go_to() - Navigate to a URL

•click() - Click by description (vision LLM, no selectors)

•keyboard_type() - Type text

•get_text() - Extract page content

•select_option() / check_checkbox() - Complete forms

•take_screenshot() - Capture pages

•scroll() / wait_for_element() - Scroll and wait

•run_page_script() - Run JS on the page

Note: Built on Patchright (a stealth-patched Playwright fork). If no browser is found, ConnectOnion installs Chromium in the user cache with no admin rights. The manual fallback is python -m patchright install chromium.

5Create a Custom Tool Agent

You can also create agents from scratch with custom tools:

main.py
python
from connectonion import Agent

def convert_celsius(celsius: float) -> float:
    """Convert Celsius to Fahrenheit."""
    return round(celsius * 9 / 5 + 32, 1)

# Create agent with the tool
agent = Agent(
    name="converter",
    tools=[convert_celsius],
    system_prompt="Use the conversion tool for temperature questions.",
    max_iterations=5  # Simple calculations need few iterations
)

# Use the agent
response = agent.input("Convert 23 Celsius to Fahrenheit")
print(response)
output
23°C is 73.4°F.

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 convert_celsius(celsius: float) -> float:
    """Temperature tool with debugging enabled."""
    print(f"Agent '{xray.agent.name}' is converting: {celsius}°C")
    print(f"User request: {xray.task}")
    print(f"Iteration: {xray.iteration}")
    return round(celsius * 9 / 5 + 32, 1)

agent = Agent("debug_converter", tools=[convert_celsius], max_iterations=5)
response = agent.input("Convert 20 Celsius to Fahrenheit")
print(response)
output
Agent 'debug_converter' is converting: 20.0°C
User request: Convert 20 Celsius to Fahrenheit
Iteration: 1
 
20°C is 68.0°F.

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