Basic Agents

Basic Agents

Learn how to create and configure AI agents using the AIAgent class in Koog 0.8.0.

Minimal Agent

The simplest agent requires only an executor and a model:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.ext.simple.simpleOpenAIExecutor
import ai.koog.agents.ext.llm.OpenAIModels

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o
)

val result = agent.run("What is the capital of France?")

System Prompt

Define the agent's personality and instructions with a system prompt:

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = """
        You are a helpful Kotlin programming assistant.
        Always provide code examples in Kotlin.
        Use coroutines for async operations.
        Follow Kotlin coding conventions.
    """.trimIndent()
)

Temperature Control

Control the creativity/randomness of responses:

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    temperature = 0.7  // 0.0 = deterministic, 2.0 = very creative
)

Max Iterations

Control how many LLM calls the agent can make per run (default: 50):

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    maxIterations = 10  // Limit to 10 LLM calls per run
)

This is especially important when using tools, as each tool call requires an additional LLM iteration.

Tool Registration

Register tools using ToolRegistry:

import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.Tool

val toolRegistry = ToolRegistry {
    tool(MyCustomTool())
    tool(AnotherTool())
}

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry
)

Annotation-Based Tools

The simplest way to create tools — use @Tool and @LLMDescription annotations:

import ai.koog.agents.core.tools.Tool
import ai.koog.agents.core.tools.annotations.LLMDescription

@Tool
@LLMDescription("Get the current weather for a location")
suspend fun getWeather(
    @LLMDescription("The city name") city: String,
    @LLMDescription("Temperature unit: celsius or fahrenheit") unit: String = "celsius"
): String {
    return "The weather in $city is 22°C and sunny"
}

// Register annotation-based tools
val toolRegistry = ToolRegistry {
    tool(getWeather)
}

Class-Based Tools

For more control, create tools by extending SimpleTool:

import ai.koog.agents.core.tools.SimpleTool
import ai.koog.agents.core.tools.ToolDescriptor

object CalculatorTool : SimpleTool<CalculatorTool.Args>() {
    override val descriptor = ToolDescriptor(
        name = "calculator",
        description = "Perform basic arithmetic"
    )

    data class Args(
        val expression: String
    ) : Tool.Args

    override suspend fun execute(args: Args): String {
        // Evaluate expression
        return evaluate(args.expression).toString()
    }
}

val toolRegistry = ToolRegistry {
    tool(CalculatorTool)
}

See Tools Overview for complete tool documentation.

Event Handling

Handle agent events using handleEvents{}:

import ai.koog.agents.core.feature.model.featureConfig

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry
)

agent.handleEvents {
    onToolCallStarted { toolName, args ->
        println("Tool called: $toolName with args: $args")
    }

    onToolCallCompleted { toolName, args, result ->
        println("Tool $toolName returned: $result")
    }

    onLLMCallStarted { model, messages ->
        println("Calling LLM: $model with ${messages.size} messages")
    }

    onLLMCallCompleted { model, messages, response ->
        println("LLM response: ${response.take(100)}...")
    }

    onError { error ->
        println("Agent error: ${error.message}")
    }

    onAgentFinished { result ->
        println("Agent finished with result: $result")
    }
}

Java Pattern

Creating agents in Java:

import ai.koog.agents.core.agent.AIAgent;
import ai.koog.agents.core.tools.ToolRegistry;
import ai.koog.agents.ext.simple.SimpleOpenAIExecutorKt;
import ai.koog.agents.ext.llm.OpenAIModels;

public class MyAgent {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("OPENAI_API_KEY");

        // Build tool registry
        var toolRegistry = ToolRegistry.builder()
            .tool(new MyCustomTool())
            .build();

        // Build agent
        var agent = AIAgent.builder(
                SimpleOpenAIExecutorKt.simpleOpenAIExecutor(apiKey),
                OpenAIModels.Chat.GPT4o
            )
            .systemPrompt("You are a helpful assistant.")
            .temperature(0.7)
            .maxIterations(10)
            .toolRegistry(toolRegistry)
            .build();

        // Run agent
        String result = agent.run("What tools do you have?");
        System.out.println(result);
    }
}

ToolSet Interface (Java)

For Java, use the ToolSet interface to group related tools:

import ai.koog.agents.core.tools.ToolSet;
import ai.koog.agents.core.tools.Tool;

public class MathTools implements ToolSet {
    @Override
    public List<Tool<?>> getTools() {
        return List.of(
            new AddTool(),
            new SubtractTool(),
            new MultiplyTool()
        );
    }
}

// Register all tools at once
var toolRegistry = ToolRegistry.builder()
    .toolSet(new MathTools())
    .build();

Complete Example

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.ext.simple.simpleOpenAIExecutor
import ai.koog.agents.ext.llm.OpenAIModels

@Tool
@LLMDescription("Get the current date and time")
suspend fun getCurrentDateTime(): String {
    return kotlinx.datetime.Clock.System.now().toString()
}

@Tool
@LLMDescription("Generate a random number")
suspend fun randomNumber(
    @LLMDescription("Minimum value (inclusive)") min: Int = 0,
    @LLMDescription("Maximum value (inclusive)") max: Int = 100
): String {
    return (min..max).random().toString()
}

suspend fun main() {
    val apiKey = System.getenv("OPENAI_API_KEY")

    val toolRegistry = ToolRegistry {
        tool(getCurrentDateTime)
        tool(randomNumber)
    }

    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.Chat.GPT4o,
        systemPrompt = "You are a helpful assistant with access to date/time and random number tools.",
        temperature = 0.5,
        maxIterations = 10,
        toolRegistry = toolRegistry
    )

    agent.handleEvents {
        onToolCallStarted { toolName, args ->
            println("[Tool] Calling $toolName")
        }
        onToolCallCompleted { toolName, _, result ->
            println("[Tool] $toolName returned: $result")
        }
    }

    val result = agent.run("What time is it? Also, give me a random number between 1 and 50.")
    println("\nAgent: $result")
}

Configuration Reference