Home

Agents.KT Wiki

AI agents with boundaries. Through typed Kotlin. One input. One output. Allowed tools only.

Agents.KT is a local-first Kotlin/JVM runtime for typed agent pipelines. Every agent is Agent<IN, OUT>: one input type, one output type, one job. Composition is typed, tool access is explicit per skill, and agents can run as library code, MCP endpoints, standalone runners, or same-JVM swarms.

Primary Links

Link	Purpose
Website	Product tour: typed contracts, constrained tools, local-first runtime, swarm, install, docs
Repository	Source code, README, issues, releases
Maven Central	Published JVM artifact versions
Release notes	Current release details

Product Shape

Site scene	Runtime surface
Typed by design	Agent<IN, OUT> values compose with then, /, forum, loops, and sealed branches
Tools with limits	Tools are registered on the agent and authorized per skill; typed tool handles catch allowlist mistakes early
Local first	Start with Ollama on the JVM; add MCP when an agent needs external tools or should become one
Swarm when needed	A captain discovers sibling agent JARs and absorbs them as delegated tools in the same JVM
Start with one dependency	Pin the Maven artifact, build one typed agent, then add memory, budgets, and observability deliberately

Quick Start

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

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

val result = greet("World")  // "Hello, World!"

Chain agents into a type-safe pipeline:

val pipeline = parse then generate then review
val result = pipeline(RawText("build a calculator"))  // ReviewResult

Learning Path

1. Installation & Setup          --- get the project running
2. Your First Agent              --- hands-on tutorial
3. Architecture Overview         --- mental model
4. Agent & Type Contract         --- the core abstraction
5. Skills & Knowledge            --- building blocks
6. Composition: Pipeline         --- sequential chains
7. Composition: Parallel         --- fan-out
8. Composition: Forum            --- multi-agent synthesis
9. Composition: Loop             --- iterative refinement
10. Composition: Branch          --- conditional routing
11. Model & Tool Calling         --- LLM integration and typed tools
12. MCP Integration              --- consume and expose tools
13. Agent Deployment Modes       --- library, hosted MCP, standalone runner
14. Swarm                        --- same-JVM sibling-agent delegation
15. Tool Error Recovery          --- resilient tool calls
16. Skill Selection & Routing    --- multi-skill agents
17. Budget Controls              --- turns, tools, time, tokens, repeated-tool caps
18. Observability Hooks          --- skill, tool, knowledge, error, budget events
19. Generable & Guide            --- typed LLM output
20. Agent Memory                 --- persistent state
21. Best Practices               --- production readiness
22. Cookbook                     --- real-world patterns

Tutorials

Article	What You'll Learn
Installation & Setup	Prerequisites, Gradle dependency, Ollama setup, IDE tips
Your First Agent	Build a 3-stage pipeline from scratch

Core Concepts

Article	What You'll Learn
Architecture Overview	Package structure, execution flow, protocol stack
Agent & Type Contract	Agent<IN, OUT> deep dive, DSL configuration, validation
Skills & Knowledge	Skill definition, implementedBy, tools(), knowledge entries
Single-Placement Rule	Why agents are single-use and how to work with it

Composition Operators

Operator	Syntax	Article
Pipeline	A then B	Composition: Pipeline
Parallel	A / B	Composition: Parallel
Forum	A * B	Composition: Forum
Loop	A.loop { }	Composition: Loop
Branch	A.branch { }	Composition: Branch
While	while (cond) { }	Composition: While Loops

LLM Integration

Article	What You'll Learn
Model & Tool Calling	Ollama, Anthropic, OpenAI, typed tools, agentic loop, authorization, testing
MCP Integration	Bidirectional — mcp { server() } consumes external MCP servers (HTTP/stdio/TCP, Bearer auth, namespacing); McpServer.from(agent) exposes skills as tools; McpRunner.serve(agent, args) is a one-line main for standalone agent JARs callable from Claude Code, Cursor, or any MCP client
Agent Deployment Modes	Three ways to ship the same agent: library (in-process function), hosted (in your JVM, plus MCP endpoint), autonomous (its own process / JAR / Docker / native binary). The progression from embedded helper to ejected entity.
Tool Error Recovery	onError {} DSL, deterministic & LLM-driven repair, escalation
Skill Selection & Routing	Predicate, LLM, and first-match routing strategies
Budget Controls	maxTurns, maxToolCalls, maxDuration, perToolTimeout, maxTokens, maxConsecutiveSameTool
Observability Hooks	onSkillChosen, onToolUse, onKnowledgeUsed, onError, onBudgetThreshold, observe { }

Guided Generation

Article	What You'll Learn
@Generable & @Guide	Annotations, runtime artifacts, lenient parsing
Sealed Types & Branching	Sealed @Generable types, JSON schema, branch integration

Agent Memory

Article	What You'll Learn
MemoryBank	Persistent memory, auto-injected tools, shared memory

Reference

Article	Description
API Quick Reference	All DSL functions in compact tables
Type Algebra Cheat Sheet	Complete type algebra with all overloads
Glossary	~30 framework terms defined
Best Practices	DOs, DONTs, and anti-patterns
Cookbook & Recipes	11 ready-to-use patterns
Troubleshooting & FAQ	Common errors and solutions
Roadmap	Phase 1-4 development plan