Introduction to Kern 🚀

Build robust, local-first AI agents, teams, and workflows in pure Python.

Kern is a lightweight Python framework designed specifically for building AI agent systems that run efficiently on small language models (1-7B parameters).

While most agent frameworks are built with massive cloud APIs in mind, Kern is optimized for local environments—like running Ollama or llama.cpp directly on your laptop. It handles structured outputs, JSON repair, tool execution, memory storage, and real-time workflow visualizations under the hood, making smaller models behave like reliable business partners.

Here are the three core building blocks (primitives) of Kern:

1from kern.agent import Agent
2from kern.models.openai import OpenAIChat
3from kern.db.sqlite import SqliteDb
4
5# 1. Boot up a single autonomous agent 🤖
6coding_assistant = Agent(
7    name="Coding Partner",
8    model=OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1"),
9    db=SqliteDb(db_file="tmp/dev_db.db"),
10    add_history_to_context=True,
11    num_history_runs=3,
12    markdown=True,
13)
14
15coding_assistant.print_response("Write a fast Fibonacci function in Python.")

1from kern.agent import Agent
2from kern.team import Team
3from kern.models.openai import OpenAIChat
4from kern.tools.yfinance import YFinanceTools
5
6# Connect to local Ollama model
7local_model = OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1")
8
9# 2. Coordinate multiple specialized agents in a team! 🤝
10bull = Agent(
11    name="Bullish Advisor",
12    model=local_model,
13    role="Focus on positive catalysts and growth indicators",
14    tools=[YFinanceTools()],
15)
16bear = Agent(
17    name="Bearish Advisor",
18    model=local_model,
19    role="Focus on risks, competition, and macroeconomic hurdles",
20    tools=[YFinanceTools()],
21)
22
23investment_team = Team(
24    name="Investment Committee",
25    members=[bull, bear],
26    instructions="Analyze the stock from both positive and negative angles, then synthesize a recommendation.",
27)
28
29investment_team.print_response("Should I invest in NVIDIA stock?")

1from kern.agent import Agent
2from kern.models.openai import OpenAIChat
3from kern.workflow import Workflow
4from kern.tools.hackernews import HackerNewsTools
5
6# Connect to local Ollama model
7local_model = OpenAIChat(id="llama3.2:3b", base_url="http://localhost:11434/v1")
8
9# 3. Build a predictable, step-based pipeline ⛓️
10researcher = Agent(
11    model=local_model,
12    tools=[HackerNewsTools()],
13    instructions="Find the top three trending tech topics.",
14)
15
16writer = Agent(
17    model=local_model,
18    instructions="Write a summary report based on the topics provided.",
19)
20
21content_pipeline = Workflow(
22    name="Weekly Tech Digest",
23    steps=[researcher, writer]
24)
25
26content_pipeline.print_response("Generate this week's digest.", stream=True)

🧱 The Three Primitives

Primitive	What it is	When to use it
Agent 🤖	A single reasoning loop with instructions and tools.	For targeted, single-domain tasks or open-ended interactions.
Team 🤝	Multiple specialized agents coordinating under a leader.	To divide a complex task among distinct domain experts.
Workflow ⛓️	A deterministic, step-by-step execution pipeline.	When you need predictable, repeatable execution with clear steps.

⚙️ Core Capabilities

🧠 Model & Context

Models: Easy adapters for Ollama, llama.cpp, vLLM, and cloud providers.
Structured Outputs: Template-based generation and automatic JSON repair for models under 7B.
Storage & Db: Persist chat history, logs, and variables to SQLite or PostgreSQL.
Memory: Keep track of user facts across sessions.
Knowledge: Ground your responses in external files and web links using RAG.

🛠️ Execution & Safety

Tools: 120+ pre-built integrations to fetch weather, search the web, or read file workspaces.
Guardrails: Validate model outputs before returning them to users.
Human-in-the-Loop: Pause agent executions to wait for approval or manual input.
Background Runs: Spin up long-running tasks asynchronously.

🚀 Moving to Production: AgentOS

Once you've tested your agent script, you'll want to serve it. Kern includes AgentOS, a runtime framework that converts your Python agents into fully-featured web API servers (built on FastAPI) with authentication, tracing, and user interface panels out of the box.

🗺️ Where to next?

rocket

Install & Setup 🧪

Install the package, set up your model, and run your first agent.

diagram-project

Visualize Workflows 📊

Generate real-time Mermaid diagrams of your agent runs.

Note

Open Source Heritage & Credit 🤝 Kern is built as a fork of the excellent Agno framework. We are deeply grateful to the Agno team for their pioneering work on stateful agent orchestration.

While Agno is built for general cloud scale, Kern focuses specifically on local-first optimization, template-based structured output, automatic JSON repair, and real-time visualization for smaller models (1-7B parameters) running on local developer setups.