Installation and Setup

Installation and Setup

Get Agents.KT running on your machine in under 10 minutes.

---

Prerequisites

Requirement	Minimum Version	Check Command
JDK	21+	java -version
Kotlin	2.1+	Managed by Gradle (no separate install needed)
Gradle	8.5+	gradle --version or use the included gradlew wrapper
Ollama	Latest	ollama --version (only needed for LLM-driven skills)

Agents.KT uses JDK 21 features (virtual threads, pattern matching). Earlier JDK versions will not work.

If you do not have JDK 21 installed, SDKMAN is the easiest way to get it:

sdk install java 21.0.4-tem
sdk use java 21.0.4-tem
java -version   # confirm: openjdk version "21.x.x"

---

Gradle Dependency

Add Agents.KT to your project's build.gradle.kts:

plugins {
    kotlin("jvm") version "2.1.0"
}

group = "com.example"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    implementation("ai.deep-code:agents-kt:0.1.1")
}

kotlin {
    jvmToolchain(21)
}

Sync your Gradle project. The artifact is published to Maven Central -- no custom repository configuration required.

If you are using a version catalog (libs.versions.toml):

[versions]
agents-kt = "0.1.1"

[libraries]
agents-kt = { module = "ai.deep-code:agents-kt", version.ref = "agents-kt" }

// build.gradle.kts
dependencies {
    implementation(libs.agents.kt)
}

---

Building from Source

If you want to build the framework itself (to contribute or to use a snapshot build):

git clone https://github.com/Deep-CodeAI/Agents.KT.git
cd Agents.KT
./gradlew build

Run the unit test suite (no LLM required):

./gradlew test

Run integration tests that require a live Ollama instance:

./gradlew integrationTest

The built artifact is placed in build/libs/agents-kt-0.1.1.jar. You can publish it to your local Maven cache for use in other projects:

./gradlew publishToMavenLocal

---

Ollama Setup

Ollama is needed only when you use LLM-driven (agentic) skills. Pure Kotlin skills defined with implementedBy do not require Ollama.

1. Install Ollama

macOS:

brew install ollama

Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows: Download the installer from ollama.com/download.

2. Start the Ollama server

ollama serve

By default, Ollama listens on http://localhost:11434. The framework connects to this address automatically.

3. Pull a model

ollama pull qwen2.5:7b

Any model that supports tool calling works. Recommended starting points:

Model	Size	Best For
qwen2.5:7b	~4.7 GB	General purpose, good tool-call support
llama3.1:8b	~4.7 GB	Strong reasoning
qwen2.5:14b	~9 GB	Higher accuracy when hardware allows

4. Verify Ollama is running

curl http://localhost:11434/api/tags

You should see a JSON response listing your pulled models.

5. Configure the model in your agent

val myAgent = agent<MyInput, MyOutput>("my-agent") {
    model { ollama("qwen2.5:7b") }
    budget { maxTurns = 5 }

    skills {
        skill<MyInput, MyOutput>("do-work", "Performs work using the LLM") {
            tools("myTool")
        }
    }
}

The model { } block tells the agent which LLM to use. The budget { } block limits the number of agentic loop iterations to prevent runaway calls.

---

IDE Setup

IntelliJ IDEA (Community or Ultimate) is the recommended IDE.

1. Open IntelliJ IDEA.
2. File > Open and select your project's root directory (the folder containing build.gradle.kts).
3. IntelliJ will detect the Gradle project and import it automatically.
4. Wait for the Gradle sync to complete (visible in the bottom status bar).
5. Verify: open any .kt file -- syntax highlighting and code completion should work.

The Kotlin plugin is bundled with IntelliJ IDEA 2024.1+. If you are on an older version, install it via Settings > Plugins > Marketplace > Kotlin.

Tip: Enable "Reload project after changes in build scripts" under Settings > Build, Execution, Deployment > Build Tools > Gradle for automatic re-sync when you update dependencies.

---

Verify Installation

Create a minimal agent to confirm everything works. This does not require Ollama -- it uses a pure Kotlin skill.

Create a file src/main/kotlin/Main.kt:

import agents_engine.core.agent

data class Greeting(val message: String)

fun main() {
    val greeter = agent<String, Greeting>("greeter") {
        skills {
            skill<String, Greeting>("greet", "Produces a greeting") {
                implementedBy { name -> Greeting("Hello, $name!") }
            }
        }
    }

    val result = greeter("World")
    println(result)  // Greeting(message=Hello, World!)
}

Run it:

./gradlew run

Or run the main() function directly from IntelliJ by clicking the green play icon in the gutter.

If you see Greeting(message=Hello, World!) in the output, your installation is complete.

---

Next Steps

You are ready to build your first real agent. Head to Your First Agent for a hands-on tutorial that walks you through building a multi-stage pipeline from scratch.