ollama-agent 0.1.3

A lightweight AI agent library powered by Ollama with built-in tools and custom tool support

Ollama Agent

A lightweight AI agent library powered by Ollama with built-in tools and custom tool support.

For example project, visit ollama-agent-cli

Features

• Simple API - Get started with just a few lines of code
• 10 Built-in Tools - Web search, calculator, weather, system info, and more
• Custom Tools - Easy registration via decorators or functions
• Configurable - Environment variables or constructor parameters
• Safe by Default - Optional user approval for dangerous operations
• Conversation Memory - Maintains context across queries

Installation

pip install ollama-agent

Prerequisites

• Python 3.10+
• Ollama installed and running
• A model pulled (e.g., ollama pull llama3.2)

Quick Start

from ollama_agent import OllamaAgent

# Create an agent
agent = OllamaAgent()

# Run a query
response = agent.run("What's the current time?")
print(response)

# Conversation history is maintained
response = agent.run("And what's the weather in New York?")
print(response)

# Reset when needed
agent.reset()

Custom Tools

Using Decorators

from ollama_agent import OllamaAgent, register_tool

@register_tool("greet", description="Greet someone by name. Input: name")
def greet(name: str) -> str:
    return f"Hello, {name}!"

agent = OllamaAgent()
response = agent.run("Greet Alice")

Using Function Registration

from ollama_agent import register_tool_func

def my_tool(input_str: str) -> str:
    return f"Processed: {input_str}"

register_tool_func(
    name="my_tool",
    func=my_tool,
    description="Process input text"
)

Instance-specific Tools

agent = OllamaAgent()

agent.add_tool(
    name="uppercase",
    func=lambda text: text.upper(),
    description="Convert text to uppercase"
)

response = agent.run("Convert 'hello' to uppercase")
agent.remove_tool("uppercase")

Configuration

Constructor Parameters

agent = OllamaAgent(
    model="llama3.2",                    # Ollama model name
    base_url="http://localhost:11434",   # Ollama API URL
    temperature=0.7,                     # Model temperature (0-1)
    max_iterations=10,                   # Max tool calls per query
    approval_callback=my_callback,       # Optional approval function
)

Environment Variables

OLLAMA_MODEL=llama3.2
OLLAMA_BASE_URL=http://localhost:11434
TEMPERATURE=0.7
MAX_ITERATIONS=10
MAX_SEARCH_RESULTS=5
REQUIRE_APPROVAL_COMMANDS=true
REQUIRE_APPROVAL_FILES=false

Approval Callback

Require user approval for dangerous operations:

def approval_callback(tool_name: str, tool_input: str) -> bool:
    print(f"Tool: {tool_name}, Input: {tool_input}")
    return input("Allow? (y/n): ").lower() == "y"

agent = OllamaAgent(approval_callback=approval_callback)

Built-in Tools

Tool	Description
web_search	Search the web using DuckDuckGo
get_current_time	Get current date and time
run_command	Run shell commands (requires approval)
system_info	Get CPU, memory, disk, uptime info
weather	Get current weather
calculator	Evaluate math expressions
read_file	Read file contents
list_directory	List directory contents
wikipedia	Search Wikipedia
ip_info	Get public IP and location

API Reference

OllamaAgent

class OllamaAgent:
    def __init__(
        self,
        model: str = None,
        base_url: str = None,
        temperature: float = None,
        max_iterations: int = None,
        approval_callback: Callable[[str, str], bool] = None,
        tools: dict = None,
        config: Config = None,
    ): ...

    def run(self, query: str, verbose: bool = False) -> str: ...
    def reset(self) -> None: ...
    def add_tool(self, name, func, description, requires_approval=None) -> None: ...
    def remove_tool(self, name: str) -> None: ...
    def get_history(self) -> list[dict]: ...

    @property
    def tools(self) -> dict: ...
    @property
    def model(self) -> str: ...

Tool Functions

# Decorator registration
@register_tool(name: str, description: str, requires_approval: str = None)
def my_tool(input: str) -> str: ...

# Function registration
register_tool_func(name, func, description, requires_approval=None)

# Management
unregister_tool(name: str)
get_tool(name: str) -> dict
get_all_tools() -> dict
list_tools() -> list[str]

Development

# Clone the repo
git clone https://github.com/aashish-thapa/ollama-agent.git
cd ollama-agent

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/

License

MIT License - see LICENSE for details.