-
Notifications
You must be signed in to change notification settings - Fork 0
Glossary
Alphabetical reference of Agents.KT terms and types.
Agent<IN, OUT> -- the core abstraction. A typed, callable unit with a name, skills, optional model config, tools, memory, and event listeners. Created with agent<IN, OUT>("name") { }. Called with agent(input) via operator fun invoke. Each instance can participate in only one composition (see Single-Placement Rule).
Package: agents_engine.core
A skill marked with tools(...) instead of implementedBy { }. When invoked, the framework enters the Agentic Loop -- the LLM decides which tools to call and in what order. Contrast with a pure Kotlin skill.
The multi-turn execution cycle for agentic skills. The framework builds a system prompt, sends the input to the LLM, dispatches tool calls, appends results, and loops until the LLM returns a text response or the Budget is exceeded. Implemented in executeAgentic().
Package: agents_engine.model
Branch<IN, OUT> -- a composition primitive that routes the output of a source agent to different handlers based on sealed type variants. Built with .branch { on<Variant>() then handler }. All handlers must produce the same OUT type. Unhandled variants throw at invocation time.
Package: agents_engine.composition.branch
See Composition: Branch.
BudgetConfig(maxTurns: Int) -- guards against runaway agentic loops. Default is Int.MAX_VALUE (no limit). Configured via budget { maxTurns = 10 } inside the agent DSL. When exceeded, throws BudgetExceededException.
Package: agents_engine.model
BudgetExceededException(message: String) -- thrown when an agentic loop exceeds its maxTurns budget. Extends RuntimeException.
Package: agents_engine.model
ToolError.EscalationError -- a ToolError subtype indicating that a repair agent could not fix the problem and escalated it. Carries source, reason, severity, originalError, and attempts.
See Tool Error Recovery.
Forum<IN, OUT> -- a composition primitive for multi-agent deliberation. Built with A * B * C. Agents discuss across rounds; the last agent delivers the verdict. Agents see each other's reasoning (unlike Parallel).
Package: agents_engine.composition.forum
See Composition: Forum.
@Generable("description") -- annotation marking a data class or sealed interface as an LLM generation target. Enables runtime reflection artifacts: toLlmDescription(), jsonSchema(), promptFragment(), and fromLlmOutput().
Package: agents_engine.generation
See Generable and Guide.
@Guide("description") -- annotation providing per-field or per-sealed-variant guidance for the LLM. On constructor parameters, describes the range, format, or constraints. On sealed subclasses, tells the LLM when to choose that variant.
Package: agents_engine.generation
implementedBy { input -> output } -- marks a skill as a pure Kotlin skill. The lambda is called directly with no LLM involvement. The skill's isAgentic flag is set to false.
ToolError.InvalidArgs -- a ToolError subtype for malformed tool call arguments (e.g., trailing commas, markdown fencing around JSON). Carries rawArgs, parseError, and expectedSchema.
A named, lazily-evaluated context provider attached to a skill via knowledge("key", "description") { content }. In agentic skills, knowledge entries are exposed as callable tools -- the LLM reads the description and fetches content on demand. In non-agentic skills, content is loaded eagerly into toLlmContext().
KnowledgeTool(name: String, description: String, call: () -> String) -- the tools-model representation of a knowledge entry. Returned by Skill.knowledgeTools(). The call lambda is lazy -- content is loaded only when invoked.
Package: agents_engine.core
Internal parser that handles common LLM output formatting issues: markdown code fences (```json ... ```), trailing commas, and extra explanation text before or after the JSON block. Used by fromLlmOutput() and OllamaClient.
Package: agents_engine.generation
@LlmDescription("text") -- annotation that overrides the auto-generated toLlmDescription() for a @Generable class. When present, the provided text is returned verbatim.
Package: agents_engine.generation
Loop<IN, OUT> -- a composition primitive for iterative execution. Built with agent.loop { output -> nextInput? }. Runs until the feedback function returns null. Fully composable with then.
Package: agents_engine.composition.loop
See Composition: Loop.
MemoryBank(maxLines: Int = Int.MAX_VALUE) -- an in-memory key-value store for persistent agent memory. When attached to an agent via memory(bank), three tools (memory_read, memory_write, memory_search) are auto-injected. Multiple agents can share the same bank. Thread-safe via ConcurrentHashMap.
Package: agents_engine.core
See Agent Memory.
fun interface ModelClient { fun chat(messages: List<LlmMessage>): LlmResponse } -- the LLM integration point. The framework ships OllamaClient; pass any lambda or class implementing this interface for custom backends or mocks.
Package: agents_engine.model
ModelConfig(name, provider, temperature, host, port, client) -- configuration for the LLM backend. Built via model { ollama("name"); temperature = 0.7 } inside the agent DSL.
Package: agents_engine.model
The built-in ModelClient implementation that communicates with an Ollama server via HTTP. Handles both native Ollama tool calls and inline JSON tool calls from models without native tool support.
Package: agents_engine.model
DSL block for tool error recovery. Provides three handlers: invalidArgs { }, deserializationError { }, executionError { }. Each handler can apply deterministic fixes (fix { }, sanitize { }), LLM-driven repair (fix(agent = fixer, retries = N)), or retry logic (retry(maxAttempts, backoff)).
See Tool Error Recovery.
Parallel<IN, OUT> -- a composition primitive for concurrent fan-out. Built with A / B / C. All agents receive the same input and execute concurrently via coroutines. The result is List<OUT>. All agents must share the same <IN, OUT> types.
Package: agents_engine.composition.parallel
PartiallyGenerated<T> -- an immutable accumulator for incremental/streaming LLM generation. Fields arrive one at a time via withField(). Use toComplete() to attempt full construction, has() to check field presence, and get() to access values.
Package: agents_engine.generation
Pipeline<IN, OUT> -- a composition primitive for sequential execution. Built with A then B then C. The output of each stage feeds into the next. Callable via pipeline(input). All then overloads produce a Pipeline.
Package: agents_engine.composition.pipeline
The rule that each Agent instance can participate in exactly one composition. Enforced by markPlaced(context), which throws IllegalArgumentException on reuse. Prevents shared mutable state. Create new instances or use factory functions when the same logic is needed in multiple places.
Skill<IN, OUT> -- a named, described capability attached to an agent. Each skill has its own typed contract, optional knowledge entries, and either a pure Kotlin implementation (implementedBy) or an LLM-driven one (tools()). Skills can be defined inline inside skills { } or pre-defined with the top-level skill() function and added with +.
Package: agents_engine.core
See Skills and Knowledge.
skillSelection { input -> "skillName" } -- predicate-based routing for multi-skill agents. When set, it runs before LLM routing and returns the skill name directly. Deterministic and zero LLM cost.
See Skill Selection and Routing.
ToolDef(name: String, description: String, executor: (Map<String, Any?>) -> Any?) -- a tool definition registered via tools { tool("name", "desc") { args -> result } }. Tools are callable by the LLM during agentic execution. The executor receives arguments as a map and returns any value.
Package: agents_engine.model
sealed interface ToolError -- base type for tool execution errors. Four variants: InvalidArgs, DeserializationError, ExecutionError, EscalationError. Used by the onError DSL for error recovery.
Package: agents_engine.model
See Tool Error Recovery.
transformOutput { llmString -> parsedType } -- skill-level function that transforms the raw LLM text response into the skill's OUT type. Used when the agent's output is not String and you need custom parsing beyond @Generable deserialization.
See also: API Quick Reference | Architecture Overview | Type Algebra
Getting Started
Core Concepts
Composition Operators
LLM Integration
- Model & Tool Calling
- Tool Error Recovery
- Skill Selection & Routing
- Budget Controls
- Observability Hooks
Guided Generation
Agent Memory
Reference