ollama_agent_base

A lightweight tool-calling agent framework for Ollama.

This project provides a simple way to create AI agents that can call Python functions ("tools"), execute actions, and maintain conversation history.

Features

• Simple tool registration
• Automatic tool argument inspection
• Multi-step agent execution loop
• JSON-based tool calling
• Conversation memory
• Custom system prompts
• Configurable Ollama model and host

---

Installation

pip install ollama_base_agent

---

Quick Start

Create a Tool

from ollama_agent_base import Tool

def print_tool(message: str):
    print(message)

    return {
        "printed": message
    }

print_to_terminal_tool = Tool(
    name="print",
    func=print_tool,
    description="Send a message to the user via terminal output"
)

Register Tools

from ollama_agent_base import register_tools
import tools

register_tools([
    tools.print_to_terminal_tool
])

Create an Agent

from ollama_agent_base import Agent

agent = Agent(
    system_prompt=None,
    model="gemma3"
)

agent.reset()

Ask a Question

agent.ask(
    "What programming language is easiest to print in?"
)

---

Tool Definition

Tools are regular Python functions wrapped in a Tool object.

def add(a: int, b: int):
    return {
        "result": a + b
    }

add_tool = Tool(
    name="add",
    func=add,
    description="Add two numbers together"
)

Arguments are automatically detected from the function signature.

Example:

def greet(name: str, times: int = 1):
    ...

Produces:

{
  "name": "str",
  "times": "int (default=1)"
}

---

Tool Registration

Single tool:

register_tools(
    my_tool
)

Multiple tools:

register_tools(
    tool_a,
    tool_b,
    tool_c
)

Or:

register_tools(*tool_list)

---

Agent Configuration

agent = Agent(
    model="gemma3",
    host="http://127.0.0.1:11434",
    max_steps=10
)

Parameters

Parameter	Description
model	Ollama model name
host	Ollama server URL
max_steps	Maximum tool iterations

---

Environment Variables

Supported environment variables:

OLLAMA_MODEL=gemma3
OLLAMA_HOST=http://127.0.0.1:11434

---

Example Project Structure

project/
│
├── main.py
├── tools.py
│
└── src/
    └── ollama_agent_base/
        ├── __init__.py
        └── agent.py

---

Example

from ollama_agent_base import Agent, register_tools
import tools

register_tools(
    tools.print_to_terminal_tool
)

agent = Agent(
    system_prompt=None
)

agent.reset()

agent.ask(
    "Say hello"
)

---

How It Works

1. User sends a message.
2. Agent sends conversation history and tool definitions to Ollama.
3. Model responds with a JSON tool call.
4. Tool executes.
5. Result is added to conversation history.
6. Process repeats until completion.

---

Goals

This project aims to be:

• Lightweight
• Easy to understand
• Minimal dependencies
• Easy to extend
• Compatible with local Ollama models

It is intentionally much smaller than frameworks such as LangChain while still supporting tool-calling workflows.