kora-agent 0.1.7.1

A lightweight, layered Agent framework for Python

Kora is a lightweight Python framework for building AI agents. Use it as a Python SDK to integrate agents into your applications, or launch the Kora Code CLI for an interactive AI coding partner.

from kora import Agent, tool
from kora.providers import get_provider_registry

@tool
def calculate(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression, {"__builtins__": {}}, {}))

model = get_provider_registry().get_model("deepseek", "deepseek-v4-flash")
agent = Agent(name="assistant", tools=[calculate], model=model)

result = agent.run_sync("What is 3 + 5?")
print(result)  # The model calls calculate(3+5) and responds with the answer

Installation

# Kora SDK — integrate agents into your Python applications
pip install kora-agent

# Kora Code — interactive AI coding assistant (CLI)
pip install kora-agent kora-code

Requires Python 3.12+. Zero required runtime dependencies.

Features

• Minimal API. Agent, Session, @tool, and you're done.
• 26 built-in model providers. OpenAI, Anthropic, DeepSeek, DashScope, and more — one registry, one API.
• 8 core tools out of the box. Filesystem, shell, Python sandbox, and user interaction — all workspace-scoped.
• Security by code, not by prompt. SSRF protection, command filtering, import restrictions, and workspace isolation are enforced in implementation.
• Observable by default. Every run emits structured events (RunStarted, ToolExecuted, RunCompleted, ...) for streaming and debugging.

Quick Start

SDK — Build agents in Python

from kora import Agent, tool
from kora.providers import get_provider_registry
from kora.tools import get_core_tools
import asyncio

@tool
def echo(message: str) -> str:
    """Echo back a message."""
    return f"Echo: {message}"

model = get_provider_registry().get_model("deepseek", "deepseek-v4-flash")

agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant.",
    tools=[echo, *get_core_tools(".")],
    model=model,
)

async def main():
    session = agent.open_session()
    result = await session.send("What files are in this directory?")
    print(result)

asyncio.run(main())

📖 Kora Agent SDK Tutorials — 8 chapters covering agents, tools, providers, sessions, events, and more.

CLI — Launch an AI coding assistant

# Interactive REPL
kora code

# One-shot task
kora code "Refactor src/main.py to use async/await"

# Custom agent
kora run --agent /path/to/AGENT.md

📖 Kora Code CLI Tutorials — 5 chapters on commands, modes, customization, and best practices.

Documentation

Model Providers

Kora ships with 26 built-in providers covering 300+ models. Set the corresponding environment variable and go:

Full provider list →

Custom provider? Register one in 5 lines:

from kora.providers import ProviderSpec, ModelSpec, get_provider_registry

registry = get_provider_registry()
registry.register(ProviderSpec(
    id="my-provider", name="My Provider",
    base_url="https://api.example.com/v1", api="openai-completions",
    api_key="${MY_API_KEY}",
    models=(ModelSpec(id="my-model", name="My Model", tool_calling=True),),
))

Built-in Tools

Use get_core_tools(workspace) to get the 8 essential tools for a coding agent:

Full tool reference →

Architecture

Interface → Host → Runtime → Kernel

Each layer depends only on the layer inside it. The Kernel is fully testable with fake models — no network required.

Contributing

Kora is intentionally small. Before making a change, read CLAUDE.md and the ADR records.

1. Identify which architectural layer owns the change.
2. Prefer the smallest complete change; add tests with behavior changes.
3. Do not cross established layer boundaries.

pip install -e ".[dev]"   # editable install with dev tooling
pytest                    # run tests
ruff check src/kora       # lint

License

MIT