Agent

The heart of ConnectOnion. Give it tools, and it figures out the rest.

Quick Start (60 Seconds)

main.py
python
from connectonion import Agent

# Define what your agent can do
def calculate(expression: str) -> str:
    """Do math calculations."""
    return str(eval(expression))

# Create agent
agent = Agent("math_bot", tools=[calculate])

# Use it
result = agent.input("What is 42 * 17?")
output
To calculate 42 * 17, I'll use the calculator tool.
The result is 714.

That's it. Your first AI agent in 5 lines.

What Agent Can Do — Full API Overview

After that simple example, here's everything an Agent can do:

Creating an Agent

main.py
python
Agent(
    name="my_bot",                        # Required: agent identifier
    tools=[func1, func2],                 # Optional: functions agent can call
    system_prompt="You are helpful",      # Optional: personality/behavior
    model="co/gemini-2.5-pro",            # Optional: LLM model (default: co/gemini-2.5-pro)
    max_iterations=10,                    # Optional: max tool calls per turn (default: 10)
    api_key="sk-...",                     # Optional: override env var
    llm=custom_llm,                       # Optional: custom LLM instance
    trust="tested",                       # Optional: security verification
    on_events=[after_llm(handler)],       # Optional: event hooks for this agent
    plugins=[re_act, logger],             # Optional: reusable event handler bundles
    quiet=False,                          # Optional: suppress console output
    log=True                              # Optional: logging config (bool or file path)
)

Using Your Agent

main.py
python
# Give it a task
result = agent.input("Do something")

# Execute a tool directly (for testing)
result = agent.execute_tool("tool_name", {"arg": "value"})

Managing Tools

main.py
python
agent.add_tool(new_function)    # Add tools after creation
agent.remove_tool("name")       # Remove tools
agent.list_tools()              # See available tools

Conversations & State

main.py
python
agent.input("What is 10 + 5?")     # Turn 1: "15"
agent.input("Multiply that by 2")  # Turn 2: "30" (remembers!)

agent.reset_conversation()         # Start fresh
session = agent.current_session    # Access internal state

Attributes You Can Access

main.py
python
agent.name                # str: Agent identifier
agent.tools               # ToolRegistry: All tools
agent.tools.names()       # list[str]: Tool names
agent.tools.get("name")   # Tool: Get by name
agent.system_prompt       # str: Personality
agent.current_session     # dict | None: Runtime state

# Token & cost tracking (after agent.input())
agent.context_percent     # float: Context window used (0-100)
agent.total_cost          # float: Total USD cost this session
agent.last_usage          # dict: Last call token usage

That's the complete API.

Now let's dive into each feature below. Jump to any section that interests you!

max_iterations

Quick Facts: Default is 10 iterations (works for most tasks!). Fully customizable per-agent or per-task.

What Are Iterations?

Think of iterations as "attempts" - how many times your agent can use tools to complete a task.

main.py
python
# Your agent tries to complete the task
# Iteration 1: "I need to search for info" -> calls search tool
# Iteration 2: "Now I'll calculate something" -> calls calculate tool
# Iteration 3: "Let me save the result" -> calls save tool
# Done! Task completed in 3 iterations

The Basics (90% of cases)

main.py
python
from connectonion import Agent

# Default: 10 iterations (works for most tasks!)
agent = Agent("my_bot", tools=[search, calculate])

# That's it! Just use it:
result = agent.input("What's 2+2?")  # Uses 1 iteration
result = agent.input("Search for Python tutorials")  # Uses 1-2 iterations

When You Need More Power

main.py
python
# Complex tasks need more iterations
research_agent = Agent(
    "researcher",
    tools=[search, analyze, summarize],
    max_iterations=25  # I need more attempts for complex research
)

Quick Override for One Task

main.py
python
# Override max_iterations for a specific task
agent = Agent("assistant", tools=[search])  # Default: 10

# Most tasks use default
result = agent.input("Simple question")

# But this one needs more
result = agent.input(
    "Complex multi-step task",
    max_iterations=30  # Override just for this task
)

When to Adjust max_iterations

Increase it when:

Your agent runs complex, multi-step workflows
Tasks require multiple tool calls (research, analysis, etc.)
You see "reached max iterations" in logs

Decrease it when:

Agent loops unnecessarily (calls same tool repeatedly)
You want faster failures for debugging
Simple tasks that should complete quickly

Best Practices

Start with default (10) - it works for most use cases
Monitor your logs - check how many iterations tasks actually use
Set per-agent for specialized agents (researcher=25, calculator=5)
Override per-task when you know a specific task needs more/less

Complete Documentation

This page provides a quick overview of the Agent class. For comprehensive documentation including:

Creating Agents

Managing Tools

Multi-Turn Conversations

Iteration Control

Common Patterns

Testing Strategies

Use the "Copy" button above to get the full markdown documentation with all details, examples, and patterns.

Agents

Everything the Agent class can do, in depth.

System Prompts

Give your agent a personality and behavior

Tools

Create functions your agent can call

Models

GPT-4o, Gemini, Claude, and managed co/ models

LLM Function

Call LLMs directly without an agent loop

Event System

Hooks into agent lifecycle: before/after LLM, tools, errors

Plugin System

Reusable event handler bundles for your agents

Real-World Examples

Open-source agents built with ConnectOnion.

browser-agent

Stateful web automation — navigate, screenshot, scrape with Playwright

github.com/openonion ↗

oo-chat

Open-source chat UI for AI agents — self-hostable, React-based

github.com/openonion ↗

Philosophy

"Keep simple things simple, make complicated things possible"

Simple Case

agent = Agent("bot", tools=[search])
agent.input("Find Python docs")

Complex Case

trust_agent = Agent("verifier", ...)

agent = Agent(
    name="production",
    llm=custom_llm,
    tools=[deploy, rollback],
    system_prompt=Path("ops.md"),
    max_iterations=30,
    trust=trust_agent,
    log="/var/log/production.log"
)

Both are valid. Start simple, add complexity only when needed.

ConnectOnion: AI Agent = Prompt + Function

That's it. That's the framework. Now go build something useful.

Agent

Quick Start (60 Seconds)

What Agent Can Do — Full API Overview

Creating an Agent

Using Your Agent

Managing Tools

Conversations & State

Attributes You Can Access

max_iterations

What Are Iterations?

The Basics (90% of cases)

When You Need More Power

Quick Override for One Task

When to Adjust max_iterations

Best Practices

Complete Documentation

Agents

System Prompts

Tools

Models

LLM Function

Event System

Plugin System

Real-World Examples

browser-agent

oo-chat

Philosophy

Simple Case

Complex Case

Star us on GitHub