ConnectOnionDocsTools
Tools
Build powerful, reusable function tools and stateful class tools.
Pro Tip: For class-based tools, pass the instance directly! ConnectOnion automatically discovers all public methods with type hints.
Quick Start
main.py
python
from connectonion import Agent
def search(query: str) -> str:
return f"Found results for {query}"
agent = Agent("helper", tools=[search], max_iterations=5)
print(agent.input("Find Python tutorials"))output
>>> agent = Agent("helper", tools=[search], max_iterations=5)
>>> print(agent.input("Find Python tutorials"))
I'll search for Python tutorials.
Found results for Python tutorials
Based on my search, here are some excellent Python tutorials for you:
1. Official Python Tutorial - Great for beginners
2. Real Python - Comprehensive guides and examples
3. Python.org Beginner's Guide - Step-by-step introduction
4. W3Schools Python Tutorial - Interactive examples
5. Codecademy Python Course - Hands-on learning
Function Tools
Use Python type hints as your interface. Keep signatures explicit and return structures when needed.
main.py
python
from typing import List
from connectonion import Agent
def top_k(query: str, k: int = 5) -> List[str]:
"""Return the top-k result titles for a query."""
return [f"{i+1}. {query} result" for i in range(k)]
agent = Agent("helper", tools=[top_k], max_iterations=8)
print(agent.input("top_k('vector db', k=3)"))output
>>> agent = Agent("helper", tools=[top_k], max_iterations=8)
>>> print(agent.input("top_k('vector db', k=3)"))
I'll search for the top 3 results about vector databases.
['1. vector db result', '2. vector db result', '3. vector db result']
main.py
python
from typing import TypedDict, List
class SearchHit(TypedDict):
title: str
url: str
score: float
def search_hits(query: str, k: int = 3) -> List[SearchHit]:
"""Structured results for chaining and UI."""
return [
{"title": f"{query} {i}", "url": f"https://example.com/{i}", "score": 0.9 - i*0.1}
for i in range(k)
]output
>>> search_hits("machine learning", k=2)
[{'title': 'machine learning 0', 'url': 'https://example.com/0', 'score': 0.9},
{'title': 'machine learning 1', 'url': 'https://example.com/1', 'score': 0.8}]
Stateful Tools: Playwright
main.py
python
from typing import List, Optional
from connectonion import Agent
try:
from playwright.sync_api import sync_playwright, Page
except ImportError:
raise SystemExit("Install Playwright: pip install playwright && playwright install")
class Browser:
"""Persistent browser session with navigation, screenshots, and tab control."""
def __init__(self):
self._p = None
self._browser = None
self._pages: dict[str, Page] = {}
self._active_tab: Optional[str] = None
def start(self, headless: bool = True) -> str:
self._p = sync_playwright().start()
self._browser = self._p.chromium.launch(headless=headless)
self._pages["main"] = self._browser.new_page()
self._active_tab = "main"
return "Browser started"
def new_tab(self, name: str) -> str:
if not self._browser:
return "Error: Browser not started"
if name in self._pages:
return f"Tab '{name}' already exists"
self._pages[name] = self._browser.new_page()
self._active_tab = name
return f"Opened tab '{name}'"
def list_tabs(self) -> List[str]:
return list(self._pages.keys())
def switch_tab(self, name: str) -> str:
if name not in self._pages:
return f"Error: No tab named '{name}'"
self._active_tab = name
return f"Switched to tab '{name}'"
def goto(self, url: str, tab: Optional[str] = None) -> str:
if not self._pages:
return "Error: Browser not started"
target = tab or self._active_tab
page = self._pages[target]
page.goto(url)
return page.title()
def screenshot(self, path: Optional[str] = None, tab: Optional[str] = None) -> str:
if not self._pages:
return "Error: Browser not started"
target = tab or self._active_tab
page = self._pages[target]
filename = path or f"{target}_screenshot.png"
page.screenshot(path=filename)
return filename
def close(self) -> None:
for page in list(self._pages.values()):
page.close()
self._pages.clear()
if self._browser:
self._browser.close()
if self._p:
self._p.stop()
browser = Browser()
agent = Agent("helper", tools=[browser], max_iterations=15) # Pass instance directly!
# Try tools directly
print(browser.start())
print(browser.goto("https://example.com"))
print(browser.screenshot("example.png"))
print(browser.new_tab("docs"))
print(browser.goto("https://playwright.dev", tab="docs"))
print(browser.screenshot("docs.png", tab="docs"))
print(browser.list_tabs())
browser.close()output
>>> browser = Browser()
>>> browser.start()
'Browser started'
>>> browser.goto("https://example.com")
'Example Domain'
>>> browser.new_tab("docs")
'Opened tab \'docs\''
>>> browser.switch_tab("docs")
'Switched to tab \'docs\''
>>> browser.goto("https://playwright.dev")
'Fast and reliable end-to-end testing for modern web apps | Playwright'
>>> browser.list_tabs()
['main', 'docs']
Class Instance vs Individual Methods
Recommended: Class Instance
main.py
python
browser = BrowserAutomation()
# Clean & automatic - ConnectOnion discovers all methods!
agent = Agent("browser_agent", tools=[browser])output
Auto-discovers all public methods:
- start_browser()
- navigate()
- take_screenshot()
- scrape_content()
- extract_links()
- close_browser()
Verbose: Individual Methods
main.py
python
browser = BrowserAutomation()
# Verbose - must list every method manually
agent = Agent("browser_agent", tools=[
browser.start_browser,
browser.navigate,
browser.take_screenshot,
browser.scrape_content,
browser.extract_links,
browser.close_browser
# Easy to forget methods!
])output
Problems:
- Verbose and error-prone
- Easy to forget methods
- Hard to maintain
- Must update when adding methods
ConnectOnion's Smart Discovery: When you pass a class instance, ConnectOnion automatically finds all public methods with proper type hints and makes them available as tools. Much cleaner code!