koaks

0.0.1-preview6indexed

Connect tools, compose logic, and manage agents with capabilities for chat, memory, streaming responses, and tool integration. Supports interaction with large language models.

JSJVMNative·koaks-ai/koaks

Stars

—

Used by

dependents

—

Health

/ 100

Koaks

🌐 English | 中文

The name "Koaks" is homophonic with "coax".

🧩 Connect your tools, compose your logic, rule your agents.

✨ Highlights

One declarative DSL: agent { } assembles an immutable, reusable agent.
First-class tools: define a tool inline with a typed input; its JSON Schema is derived from your @Serializable class. Class-based tools, JVM @Tool annotations, and lazy MCP discovery are all supported.
Pluggable memory: sliding-window, summarizing, or vector memory, committed atomically per turn (a failed or cancelled run won't corrupt history).
Structured output: agent.run<T>() returns a typed, decoded result.
Resilient by design: model fallbacks, retry/substitute error policies, step & token budgets, typed hooks, guardrails, and human approval.
Kotlin Multiplatform: JVM, JS, and macOS (Apple Silicon) from a single codebase.

🚀 Quick Start

1. Prerequisites

Kotlin 2.x / JDK 21 or higher
Gradle or Maven
An LLM endpoint + API key (any OpenAI-compatible provider, e.g. Qwen / DeepSeek, or a local Ollama)

Warning: The project is in a rapid iteration phase — the API may change at any time.

2. Add Dependencies

The current published group is org.koaks.framework. Pick the koaks-core runtime plus the provider module(s) you need.

Gradle (Kotlin DSL)

// For Gradle projects — JVM or Kotlin Multiplatform — just add the artifact below.
// Gradle resolves the right platform variant automatically.
implementation("org.koaks.framework:koaks-core:0.0.1-snapshot1")
implementation("org.koaks.framework:koaks-model-qwen:0.0.1-snapshot1")

// Optional add-ons:
// implementation("org.koaks.framework:koaks-model-ollama:0.0.1-snapshot1")
// implementation("org.koaks.framework:koaks-memory-summarizing:0.0.1-snapshot1")
// implementation("org.koaks.framework:koaks-memory-vector:0.0.1-snapshot1")

Maven

3. Your First Agent

import kotlinx.coroutines.runBlocking
import org.koaks.framework.loop.agent
import org.koaks.framework.loop.use
import org.koaks.provider.qwen.qwen

fun main() = runBlocking {
    val agent = agent {
        name = "assistant"
        instructions = "You are a concise, helpful assistant."
        model {
            qwen(
                baseUrl = ,
                apiKey = ,
                modelName = ,
            )
        }
    }

    agent.use {
         result = it.run()
        println(result.text)
    }
}

run drives the agent to a terminal state and returns an AgentResult (.text, .usage, .isSuccess). agent.use { } closes the transport the agent owns when you're done.

Multi-segment & dynamic instructions. The instructions = "..." shorthand is fine for a fixed prompt. When you need several pieces — or parts that depend on run-time context — use the instructions { } block instead. Each dynamic { } segment is a suspend provider resolved once per run (returning null/blank omits it); all non-blank segments are joined with a blank line into the single system prompt.

agent {
    instructions {
        +"You are a concise, helpful assistant."     // static
        text("Always answer in English.")            // static (explicit form)
        dynamic { "Today is ${LocalDate.now()}." }    // resolved per run
        dynamic { lookupUserProfile(userId)?.let { "User prefs: $it" } }  // null → skipped
    }
    model { qwen(baseUrl = "...", apiKey = , modelName = ) }
}

Both forms coexist; if you set instructions = "..." and an instructions { } block on the same agent, the block wins. See DynamicInstructions.kt.

KV-cache tip: keep the resolved instructions stable across the turns of a conversation. Changing them mid-conversation invalidates the provider's prompt cache, since the system prompt sits at the front of every request.

4. Streaming Events

stream emits the loop's events as they happen — assistant text, the model's reasoning trace, tool calls, and lifecycle markers.

5. Tools

Define a tool inline with a typed input — its JSON Schema is generated from the @Serializable class, so the model knows exactly what arguments to send.

You can also register class-based tools (Tool<In>), JVM @Tool annotated functions, or connect an MCP server whose tools are discovered lazily:

tools {
    tool(MyClassBasedTool())   // implements Tool<In>
    mcp(myMcpGateway)          // tools discovered on first run via tools/list
}

6. Memory (Multi-Turn Conversations)

Attach memory to the agent, then talk through a thread(id). History is loaded on each turn and committed atomically only when the turn finishes — a failure or cancellation leaves persisted history untouched.

val agent = agent {
    model { qwen(baseUrl = "base-url", apiKey = "api-key", modelName = "qwen3-235b-a22b-instruct-2507") }
    memory {
        window(40)   // sliding-window; or none() / custom(summarizingOrVectorMemory)
    }
}

agent.use {
    val chat = it.thread("user-1001")
    println(chat.run("My name is Ada.").text)
    println(chat.run("What's my name?").text)   // remembers across turns
}

7. Structured Output

Ask for a typed result and Koaks constrains the final step to valid JSON (native JSON mode when the model supports it, otherwise a schema-in-prompt fallback) and decodes it.

import org.koaks.framework.loop.run

@Serializable
data class CityWeather(val city: String, val tempC: Int)

agent.use {
    val w: CityWeather = it.run<CityWeather>("What's the weather in Shanghai right now?")
    println("${w.city}: ${w.tempC}°C")
}

8. Model Fallback & Resilience

agent {
    model {
        // try Qwen first; fall back to Ollama only if the primary fails before any output
        qwen(baseUrl = "...", apiKey = "...", modelName = "qwen3-235b-a22b-instruct-2507")
            .fallback(ollama(baseUrl = "http://localhost:11434", modelName = "llama3.1"))
    }
    onError(org.koaks.framework.policy.ErrorPolicy.retryRetriable(maxRetries = 2))
    runBudget(maxTotalSteps = 30, maxTotalTokens = 100_000)   // whole-run global guard
}

Typed hooks can transform model requests/streams and tool calls/results. Push-style listeners (Tracing) remain observe-only:

agent {
    hook {
        onModelCall {
            before { ctx -> ctx.request }
        }
        onToolCall {
            before { ctx -> if (ctx.call.name == "danger") Deny("blocked") else Proceed }
        }
    }
    install(org.koaks.framework.middleware.Tracing)
    // install(Guardrail(...)); install(HumanApproval(...))
}

🧱 Modules

🤝 Contributing Guide

Thank you for your interest in contributing! Code, documentation improvements, and issues are all welcome.

Fork the repository
Create a new branch (git checkout -b feature-xxx)
Commit your changes (git commit -m 'Add new feature')
Push your branch (git push origin feature-xxx)
Open a Pull Request

Building from source requires JDK 21. Quick check: ./gradlew :tests:jvmTest.

💖 Acknowledgements

This project makes use of, but is not limited to, the following open-source projects:

Project	Description
Kotlin	The Kotlin Programming Language.
kotlin-logging	Lightweight multiplatform logging framework for Kotlin. A convenient and performant logging facade.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

koog★ 4.4k

JetBrainsFramework designed for building AI agents with tool interaction, complex workflows, semantic search, and persistent memory. Offers modular architecture, real-time processing, and comprehensive tracing.Shared: llm

xef★ 193

xebia-functionalIntegrates modern AI capabilities, including large language models and image generation, into applications. Offers core libraries for essential AI services and complementary library integrations, inspired by LangChain and Hugging Face projects.Shared: llm

mcp4k★ 70

ondrshCompiler-driven framework builds clients and servers using the Model Context Protocol, implementing JSON-RPC handlers, schema metadata, and lifecycle management. Features resource exposure, parameterized prompts, and transport logging.Shared: llm

xemantic-ai-tool-schema★ 51

xemanticGenerates JSON Schema for serializable classes, enabling seamless integration with AI agents and large language models. Supports automatic instantiation from JSON input, facilitating complex data structure development.Shared: llm

ampere★ 39

socket-linkObservability-first multi-agent framework emitting structured, queryable events for each cognitive phase, enabling real-time reactive coordination, auditable reasoning, memory-as-events, and human escalation on low confidence.Shared: llm

langchain4kt★ 28

CJGroupFacilitates development of applications powered by large language models, offering interfaces for chat API providers, respondents, and chat models, with streaming capabilities and context-building tools.Shared: llm

core	`koaks-core`	The agent runtime: DSL, loop, tools, memory, hooks/listeners, transport
qwen	`koaks-model-qwen`	Qwen / OpenAI-compatible provider
ollama	`koaks-model-ollama`	Local Ollama provider (NDJSON)
memory: summarizing	`koaks-memory-summarizing`	Summarizing long-conversation memory
memory: vector	`koaks-memory-vector`	Vector-store-backed memory
graph	`koaks-graph`	Graph orchestration (in progress)