jbaruch/koog

Koog 1.3 idioms, gotchas, and skills for Kotlin agents on the JVM.

This plugin targets Koog 1.3.0, released 2026-09-24. Resolve API and module-coordinate questions against the tagged source and each artifact's Maven metadata.

Install

tessl install jbaruch/koog

How this plugin is shaped

Two always-on rules carry the gotchas every Koog project hits — module coordinates and agent construction. Everything else is an on-demand skill — load only when you reach for that surface.

Rules

Rule	Concept
`module-coordinates`	Two version lines — umbrella `ai.koog:koog-agents:1.3.0`, a wide satellite set only at `1.3.0-beta`; bare coordinates for Gradle, `-jvm` suffix for Maven only; pull planner / MCP / Spring / Ktor / Google modules explicitly; JDK 17 + Kotlin 2.3.10 minimum
`agent-construction`	Top-level `AIAgent(...)` factory; `installFeatures` trailing lambda; `singleRunStrategy()` default; `AgentMemory` removed

Skills

Foundations

Skill	What it does
`scaffold-agent`	Bootstrap a new Koog 1.3 Kotlin project from scratch
`add-tool`	Add a tool — annotated `@Tool` / typed `Tool<TArgs,TResult>` / sub-agent-as-tool
`define-prompt`	Author prompts beyond `systemPrompt = "..."` — DSL, few-shot, augmenters
`use-functional-agent`	Use `FunctionalAIAgent` — single suspending block, no graph, no planner

Orchestration

Skill	What it does
`author-strategy`	Custom graph strategy with subgraphs and verify/fix loops
`domain-model-subtask-pipeline`	Integrated pattern — tools sliced by access, typed `@LLMDescription` handoff classes, `subgraphWithTask<In, Out>` chained by compile-time types
`use-planner`	LLM-based planner or GOAP when topology depends on runtime context
`model-planner-subtasks`	Planner's tree of subtasks — `PlannerNode` composition, parallel vs sequential, retries
`use-llm-node-variants`	Streaming, multiple-choice, moderation, force-one-tool nodes
`add-structured-output`	Typed JSON output via `responseProcessor` or `nodeLLMRequestStructured`

State and durability

Skill	What it does
`manage-state`	`AIAgentStorage`, history compression, `LongTermMemory` (replaces removed `AgentMemory`)
`add-persistence`	Automatic durable checkpoints + `Persistence.runFromCheckpoint` replay
`snapshot-and-restore`	Manual Persistence save points for explicit fork/replay
`persist-chat-history`	`ChatMemory` with JDBC, AgentCore, or SQL-backed providers — resume conversations by session

Integrations

Skill	What it does
`wire-mcp-server`	Connect to an MCP server — Streamable HTTP / SSE / stdio
`wire-spring-boot`	Spring Boot autoconfig — `ai.koog.<provider>.*` keys + `MultiLLMAutoConfiguration`
`wire-ktor-server`	Ktor plugin — agent over HTTP, MCP-block config
`wire-a2a`	Agent-to-Agent protocol — serve or consume
`wire-acp-server`	Agent Client Protocol — fine-grained client control with cancellation
`use-cli-agents`	Drive Claude Code / Codex via `CliAIAgent` on subscription auth, composed with `.asNode()`
`query-sql-from-agent`	Typed JDBC lookup tools with prepared queries, database grants, row caps and timeouts

Quality and cost

Skill	What it does
`add-observability`	OpenTelemetry feature — Langfuse / OTLP / Datadog / Weave backends
`handle-agent-events`	Per-step event handlers for human-readable trace surfaces
`trace-agent-internals`	Deep diagnostic trace — node entries, edge predicate evaluations, planner decisions
`enable-prompt-caching`	Anthropic prompt caching — automatic + explicit `cacheControl` breakpoints
`cache-llm-calls`	In-process LLM-response cache (in-memory, file, Redis) — distinct from provider-side caching
`add-token-budgeting`	Hard run budget + soft history compression on overrun
`test-koog-agents`	Deterministic testing — scripted executor, fake clock, event-handler recorder

Advanced

Skill	What it does
`add-rag`	Embedder + vector store + retrieval as tool or augmenter
`use-attachments`	Multimodal — images, files, audio in user turns
`use-agent-skills`	Runtime-discovered capability bundles — `discoverSkills` / `generateSkillsPrompt` over SKILL.md files

Migration

Skill	What it does
`migrate-from-0-x`	Bump a 0.x codebase to 1.x — 14-step checklist covering every breaking change

Scope

This plugin teaches Kotlin consumption of Koog 1.3 on the JVM. Java-interop surface (AIAgentService, *Blocking variants from #2005) is deferred to a future jbaruch/koog-java. Other Kotlin targets (Kotlin/JS, Kotlin/Native, Compose Multiplatform) are not covered — the rules and skills assume kotlin("jvm"), JDK 17, and JVM-specific exporter/metrics configuration and JDBC backends. OpenTelemetry shutdown follows agent close.

Source of authority

Where this plugin and docs.koog.ai disagree, this plugin follows the Koog 1.3.0 source and the v1.3.0 release notes.

Verification

With JDK 21 and Gradle 9.2.1, run gradle -p tests/examples check. The check compiles marked examples directly from the published skills against Koog 1.3.0 / 1.3.0-beta and runs deterministic behavioral regressions. See tests/examples/README.md for coverage and dependency renewal.