Setting Up Your Lab 🧪

Let's get your local agent laboratory ready. 🧪 We will:

1. Create a Python virtual environment.
2. Install the kern-ai SDK.
3. Configure your local model connection (Ollama, llama.cpp, etc.).
4. Run your first file-inspector agent.
5. Boot up an API service using AgentOS.

📦 1. Create a Virtual Environment

Kern requires Python 3.10 or newer. We recommend uv for lightning-fast package management, but standard venv works great too.

1# Create and activate
2uv venv --python 3.12
3source .venv/bin/activate

1# Create and activate
2python3 -m venv .venv
3source .venv/bin/activate

1# Create and activate
2python -m venv .venv
3.venv\Scripts\activate

💾 2. Install Kern

Install the core SDK along with the standard client dependencies:

1uv pip install -U kern-ai openai

1pip install -U kern-ai openai

🔌 3. Connect to a Model

Kern is designed around the OpenAI-compatible completions API, making it easy to point to local model servers or cloud providers.

Local Servers (Recommended) 💻

Boot up a local model runner and note its endpoint. Here are the default endpoints for popular local managers:

Cloud Providers (Optional) ☁️

If you want to use cloud APIs, export your credentials to your shell environment:

1export OPENAI_API_KEY=sk-***

1setx OPENAI_API_KEY sk-***

🎩 4. Run Your First Agent

Save the script below as sorting_hat.py. It uses a local Ollama model to scan its own directory and organize it:

1from pathlib import Path
2from kern.agent import Agent
3from kern.models.openai import OpenAIChat
4from kern.tools.workspace import Workspace
5
6# Determine current script folder
7folder = Path(__file__).parent
8
9# 1. Spawn the sorting hat agent! 🎩
10sorting_hat = Agent(
11    model=OpenAIChat(
12        id="llama3.2:3b",
13        base_url="http://localhost:11434/v1",  # Connecting to Ollama
14    ),
15    tools=[Workspace(root=str(folder), allowed=["read", "list"])],
16    instructions="Inspect the files in this folder, group them by type, and print a tidy summary tree.",
17    markdown=True,
18)
19
20# 2. Tell the agent to inventory the workspace
21sorting_hat.print_response(f"Inventory and organize the files in: {folder}", stream=True)

Run your script:

1python sorting_hat.py

You should see your local model read the folder, execute the workspace tool, and print a formatted directory breakdown in your terminal! 🚀

🌐 5. Serve Your Agent with AgentOS

To go from a local test script to a production service with chat UI interfaces, session histories, and telemetry, run your agent using AgentOS.

Install the OS runtime extras:

1uv pip install -U 'kern-ai[os]'

1pip install -U 'kern-ai[os]'

Save the script below as workbench.py:

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.os import AgentOS
4from kern.models.openai import OpenAIChat
5
6# Build our agent
7workbench = Agent(
8    name="Workbench Agent",
9    model=OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1"),
10    db=SqliteDb(db_file="tmp/workbench.db"),
11    add_history_to_context=True,
12    num_history_runs=3,
13)
14
15# Wrap it in AgentOS to expose it as an API
16agent_os = AgentOS(agents=[workbench], tracing=True)
17app = agent_os.get_app()

Run your FastAPI server:

1fastapi dev workbench.py

Your API is now live at http://localhost:8000. You can inspect the Swagger specs at http://localhost:8000/docs, or head over to the visual console at os.kern.ndx.rocks to add your server and start chatting!

🗄️ Running a Postgres Database

If you want to use PostgreSQL + pgvector for long-term production storage, you can run pgvector locally using Docker:

1docker run -d \
2  --name kern-postgres \
3  -e POSTGRES_USER=ai \
4  -e POSTGRES_PASSWORD=ai \
5  -e POSTGRES_DB=ai \
6  -p 5432:5432 \
7  -v kern-pgdata:/var/lib/postgresql/data \
8  pgvector/pgvector:pg16  # Standard official pgvector image 🐳

Once running, point your database adapter in Python to the local container: db = PostgresDb(db_url="postgresql://ai:ai@localhost:5432/ai")

📚 Let's Start Building!

Explore the main sections: