Home

Agents.KT Wiki

Typed Kotlin DSL framework for AI agent systems. Define Freely. Compose Strictly. Ship Reliably.

Every agent is Agent<IN, OUT>. One input type, one output type, one job. Type mismatches and wrong compositions are caught by the compiler.

Quick Start

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: Loop             ─── iterative refinement
9. Composition: Branch           ─── conditional routing
10. Model & Tool Calling         ─── LLM integration
11. Tool Error Recovery          ─── resilient tool calls
12. Skill Selection & Routing    ─── multi-skill agents
13. Generable & Guide            ─── typed LLM output
14. Agent Memory                 ─── persistent state
15. Best Practices               ─── production readiness
16. 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	model {}, ToolDef, agentic loop, mock testing
Tool Error Recovery	onError {} DSL, deterministic & LLM-driven repair, escalation
Skill Selection & Routing	Predicate, LLM, and first-match routing strategies
Budget Controls	maxTurns, BudgetExceededException
Observability Hooks	onToolUse, onKnowledgeUsed, onSkillChosen

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