Building From Source

Building Agents.KT From Source

This is the practical contributor guide. By the end of it you'll have run the test suite, the mutation tests, and (optionally) the live-LLM tests against a local Ollama. If you only want to use Agents.KT, pull it from Maven Central — see the README. This document is for people building, modifying, or contributing to the framework itself.

What you need

• JDK 21 or newer. The build uses jvmToolchain(21), so anything ≥ 21 is fine. Check with java -version. If you're on JDK 17 or older, install a 21+ build (Eclipse Temurin, Amazon Corretto, Azul Zulu — any of them work).
• Git. Clone the repo somewhere convenient.
• No global Gradle install needed. The Gradle wrapper is checked in; the build uses Gradle 9.4.1 regardless of what you have on PATH.
• Optional: Ollama. Required only for the live-LLM integration tests. Install it from ollama.com and pull at least one model (ollama pull llama3).

That's it. No Kotlin compiler install, no IDE install, nothing else mandatory.

Cross-platform commands

Throughout this guide, examples use ./gradlew (the *nix wrapper). On native Windows command prompts (PowerShell, cmd), use gradlew.bat instead — same arguments, same behavior. The wrapper scripts are functionally identical.

./gradlew <task>          # macOS / Linux / WSL / Git Bash
gradlew.bat <task>        # Windows native

Everything that follows works on all three operating systems unless explicitly noted.

First build

Clone, enter, build:

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

The first run takes a few minutes — the wrapper downloads Gradle, then Gradle downloads every dependency from Maven Central and verifies its SHA256 against gradle/verification-metadata.xml (more on that below). Subsequent builds are seconds.

If ./gradlew build succeeds, your environment is correct.

Common tasks

The project exposes the standard verification group. List them all with ./gradlew tasks --group verification:

Task	What it does	When to run
test	Default test suite. Excludes live-llm and live-mcp tags.	Before every commit.
integrationTest	Live-LLM tests (live-llm tag). Requires Ollama.	When changing the LLM client or agentic loop.
mcpIntegrationTest	Live MCP server tests (live-mcp tag). Requires MCP_REDMINE_URL env var.	When changing the MCP client/server.
pitest	Mutation testing. Mutates production code, re-runs the suite, reports survivors. Takes ~1.5 min.	When tightening test quality.
updateVerificationMetadata	Regenerates gradle/verification-metadata.xml from the live dep graph.	After bumping a dependency or the Gradle wrapper.
build	Compiles, runs test, packages the JARs.	Sanity-check before pushing.

Tests run in parallel where possible. The default test task takes seconds on a modern laptop because it doesn't talk to any external services.

The default test task

./gradlew test

This runs everything except live-llm and live-mcp tagged tests. It's what CI runs on every PR, and what you should run locally before pushing. ~600 tests, ~3 seconds on a typical laptop.

If a test fails, the report is in build/reports/tests/test/index.html. Open it in a browser for the full stack trace and the failing assertion.

Live-LLM tests

Some tests verify the framework against an actual LLM. They're tagged @Tag("live-llm") and excluded from the default test task because they need Ollama running locally and burn real model time.

To run them:

# Start Ollama if it isn't running
ollama serve   # or use the desktop app

# Pull the model the tests use
ollama pull llama3              # most tests
ollama pull gpt-oss:120b-cloud  # calculator tests use this

# Run the live-LLM suite
./gradlew integrationTest

The integrationTest task includes ONLY live-llm tests. Failures here usually mean the model is misbehaving rather than the framework breaking — a gpt-oss that decides to compute arithmetic mentally instead of calling tools, that kind of thing. Re-running often passes; if it doesn't, the test or the framework genuinely changed.

MCP integration tests

export MCP_REDMINE_URL=https://your-redmine.example.com/mcp   # whatever your MCP endpoint is
./gradlew mcpIntegrationTest

These exercise the MCP client/server against a real MCP HTTP endpoint. They exist primarily to validate that the framework's McpClient and McpServer speak the protocol correctly end-to-end.

Mutation testing

A passing test suite means tests don't throw. It does NOT mean tests catch real bugs. PIT mutation testing — ./gradlew pitest — perturbs the production code (flips operators, swaps return values, removes method calls) and re-runs the suite to see what your tests actually detect.

./gradlew pitest

Takes about 1.5 minutes. The report lands at build/reports/pitest/index.html.

The current baseline mutation score is ~64%; areas with weak coverage are tracked as separate issues (#839, #840, #841, #842, #843 — each follow-up adds targeted mutation-killer tests).

If you're submitting a PR that adds production code, run pitest afterwards and check that your new code's mutation score is reasonable (>80% is a healthy target). Surviving mutants almost always indicate weak tests.

Dependency verification (supply-chain hygiene)

Agents.KT pins every dependency byte via SHA256 in gradle/verification-metadata.xml. This stops a supply-chain attack where a malicious upstream pushes a backdoored 2.3.22 in place of the locked 2.3.21: the bytes won't match, the build fails before any malicious code runs.

The runtime jars, POMs, and module files are all verified. Sources and javadoc jars are exempt by regex (<trusted-artifacts> block) — they're IDE-only, never on the runtime classpath, and including them would force every IDE sync to update the metadata.

When you need to refresh the metadata

Whenever you:

• Bump a dependency version in build.gradle.kts
• Bump the Gradle wrapper (./gradlew wrapper --gradle-version=X.Y)
• Add or remove a plugin
• See a Checksums are missing from verification metadata report

run:

./gradlew updateVerificationMetadata

This task wraps --write-verification-metadata sha256 with the right task list to cover the runtime classpath, build classpath, test classpath, and Kotlin-compiler-plugin classpaths in one shot. It also defends the <trusted-artifacts> block against accidental loss.

After running it:

git diff gradle/verification-metadata.xml   # review the changes
git add gradle/verification-metadata.xml    # commit alongside your dep bump

If the diff shows anything unexpected (entries removed, weird new components, the trust block missing), git restore gradle/verification-metadata.xml to revert and investigate.

IDE setup

The project works out of the box in IntelliJ IDEA (Community or Ultimate) and VS Code with the Kotlin extension. Open the project root, let the IDE import the Gradle build, and you're ready.

A note on first import: IntelliJ resolves source jars for navigation, which can trigger Gradle's verification report. The <trusted-artifacts> regex covers sources jars — but if you see a report about sources, run ./gradlew updateVerificationMetadata once and the false alarm should clear.

Troubleshooting

"Checksums are missing from verification metadata"

You bumped a dep (or the IDE pulled a new transitive). Run ./gradlew updateVerificationMetadata, review the diff, commit. See the Dependency verification section above.

unable to find valid certification path during a fresh checkout

Your JVM's CA bundle is out of date. Update your JDK to a recent build, or import the Maven Central / Gradle plugin portal certs into your cacerts truststore.

Gradle daemon weirdness ("could not lock cache", random hangs)

Stop all daemons and start fresh:

./gradlew --stop
rm -rf .gradle/   # or `Remove-Item -Recurse -Force .gradle\` on Windows
./gradlew build

Tests pass locally but fail in CI

Most often a timing-sensitive test (the live-llm ones can flake on slow CI runners). Re-trigger CI; if it consistently fails, the test is genuinely flaky and worth investigating.

IDE shows "unresolved reference" errors but Gradle build succeeds

The IDE's Gradle import is stale. In IntelliJ: View → Tool Windows → Gradle → hit the "Reload All Gradle Projects" refresh icon.

Publishing

If you're a maintainer cutting a release to Maven Central, see PUBLISHING.md. Regular contributors don't need to think about this.

Reporting security issues

Don't open a public issue for security findings. See SECURITY.md for the responsible-disclosure path.

Where to ask questions

• Bugs and feature requests: GitHub Issues on the repo.
• Implementation questions: open a draft PR with your work-in-progress — reviewers are happy to weigh in early.
• General "how do I?" questions about agents: the README examples cover most patterns. If they don't, that's worth a documentation issue.

What's next after a green build

Read the README for the positioning and design philosophy. Then poke around agents_engine/'s major subpackages:

• core/ — Agent, Skill, MemoryBank (the framework's spine).
• composition/ — pipeline, parallel, branch, loop, forum operators.
• model/ — the agentic loop, the LLM client, tool execution boundary.
• mcp/ — MCP client + server (Streamable HTTP transport).
• generation/ — @Generable, lenient JSON parsing, prompt fragments.

Each of these has a clear *Test.kt file or two right beside it; read the tests to understand the contracts. Welcome aboard.