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
    max_iterations=10,                    # Optional: iteration limit
    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")

# Override iterations for complex tasks
result = agent.input("Complex task", max_iterations=20)

# 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               # List[Callable]: All tools
agent.tool_map            # Dict: Fast tool lookup
agent.system_prompt       # str: Personality
agent.max_iterations      # int: Iteration limit
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!

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.

System Prompts

Tools