Agent

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

Quick Start (60 Seconds)

main.py

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?")

Python REPL

Interactive

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

Agent(
    name="my_bot",                        # Required: agent identifier
    tools=[func1, func2],                 # Optional: functions agent can call
    system_prompt="You are helpful",      # Optional: personality/behavior
    model="o4-mini",                      # Optional: LLM model
    api_key="sk-...",                     # Optional: override env var
    llm=custom_llm,                       # Optional: custom LLM instance
    trust="tested",                       # Optional: security verification
    log=True                              # Optional: logging config
)

Using Your Agent

# 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

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

Conversations & State

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

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

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

# 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

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

# 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

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

Learn More

Tools

Learn how to create powerful tools for your agents

max_iterations

Control how many tool calls your agent can make

System Prompts

Give your agent a personality and behavior

Debug with @xray

See what your agent is thinking during execution

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.

CLI Reference

System Prompts