Overview
AIAgent is the main orchestrator for executing AI agent workflows. It manages strategies, tools, features, and LLM communication through a flexible, extensible architecture.
AIAgent is an expect class with platform-specific implementations for JVM, JS, and other Kotlin multiplatform targets.
Class Definition
public expect abstract class AIAgent<Input, Output> : Closeable
Type Parameters
The type of input the AI agent will process
The type of output the AI agent will produce
Properties
Unique identifier for the AI agent instance
The configuration for the AI agent, including prompt setup, model settings, and iteration limits
Methods
run
Executes the AI agent with the given input and retrieves the resulting output.
public abstract suspend fun run(
agentInput: Input,
sessionId: String? = null
): Output
The input for the agent to process
Optional session identifier for tracking execution
The output produced by the agent after processing the input
createSession
Creates a new session for executing the agent with custom lifecycle management.
public abstract fun createSession(
sessionId: String? = null
): AIAgentRunSession<Input, Output, out AIAgentContext>
Optional session identifier
return
AIAgentRunSession<Input, Output, out AIAgentContext>
A session instance for independent agent execution with state tracking
Factory Methods
Graph-based Agent
Create an agent with a graph-based execution strategy:
public inline operator fun <reified Input, reified Output> invoke(
promptExecutor: PromptExecutor,
agentConfig: AIAgentConfig,
strategy: AIAgentGraphStrategy<Input, Output>,
toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
id: String? = null,
clock: Clock = Clock.System,
noinline installFeatures: FeatureContext.() -> Unit = {}
): AIAgent<Input, Output>
Executor responsible for processing prompts and interacting with the language model
Configuration for the AI agent
strategy
AIAgentGraphStrategy<Input, Output>
required
The strategy for executing the agent’s graph logic
toolRegistry
ToolRegistry
default:"ToolRegistry.EMPTY"
Registry of tools available for use by the agent
Unique identifier for the agent. Random UUID will be generated if null
clock
Clock
default:"Clock.System"
Clock instance for time-related operations
installFeatures
FeatureContext.() -> Unit
default:"{}"
Lambda expression to install additional features in the agent’s feature context
Functional Agent
Create an agent with a functional execution strategy:
public operator fun <Input, Output> invoke(
promptExecutor: PromptExecutor,
agentConfig: AIAgentConfig,
strategy: AIAgentFunctionalStrategy<Input, Output>,
toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
id: String? = null,
clock: Clock = Clock.System,
installFeatures: FunctionalAIAgent.FeatureContext.() -> Unit = {}
): FunctionalAIAgent<Input, Output>
Quick Configuration
Create an agent with model and processor directly:
public operator fun invoke(
promptExecutor: PromptExecutor,
llmModel: LLModel,
responseProcessor: ResponseProcessor? = null,
strategy: AIAgentGraphStrategy<String, String> = singleRunStrategy(),
toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
id: String? = null,
systemPrompt: String? = null,
temperature: Double? = null,
numberOfChoices: Int = 1,
maxIterations: Int = 50,
installFeatures: FeatureContext.() -> Unit = {}
): AIAgent<String, String>
The specific large language model to be used
Processor for handling the model’s responses
Optional system prompt for the agent
Model temperature, typically ranging from 0.0 to 1.0
Number of response choices to generate
Maximum number of iterations the agent is allowed to perform
Builder Pattern
Get a builder for fluent agent configuration:
public fun builder(): AIAgentBuilder
Usage Examples
Basic Graph Agent
val agent = AIAgent(
promptExecutor = executor,
agentConfig = AIAgentConfig(
prompt = Prompt { },
llm = llmModel,
maxIterations = 10
),
strategy = singleRunStrategy(),
toolRegistry = ToolRegistry {
tool(MyTool())
}
)
val result = agent.run("Analyze this data")
println(result)
agent.close()
Agent with Features
val agent = AIAgent(
promptExecutor = executor,
agentConfig = config,
strategy = myStrategy,
toolRegistry = myTools
) {
// Install features
install(TracingFeature) {
writer = TraceFeatureMessageLogWriter()
}
install(MemoryFeature) {
maxMessages = 100
}
}
Using Builder
val agent = AIAgent.builder()
.promptExecutor(executor)
.model(llmModel)
.strategy(customStrategy)
.tools {
tool(SearchTool())
tool(CalculatorTool())
}
.systemPrompt("You are a helpful assistant")
.temperature(0.7)
.maxIterations(20)
.build()
Session Management
val session = agent.createSession("session-123")
try {
val result = session.run(input)
println("Result: $result")
} finally {
session.close()
}
Source Reference
Defined in: agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/AIAgent.kt