Koog

https://docs.koog.ai
Admin
Koog is a Kotlin-based framework for building and running AI agents entirely in idiomatic Kotlin,...
Tokens:170,270
Snippets:1,463
Trust Score:4.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Provide examples for LLM guidance

Source: https://docs.koog.ai/structured-output

Pass a list of example objects to help the LLM understand the expected output format.

```kotlin
val exampleForecasts = listOf(
  WeatherForecast(
    news = listOf(WeatherNews(0.0), WeatherNews(5.0)),
    sources = mutableMapOf(
      "openweathermap" to WeatherSource(Url("https://api.openweathermap.org/data/2.5/weather")),
      "googleweather" to WeatherSource(Url("https://weather.google.com"))
    )
    // Other fields
  ),
  WeatherForecast(
    news = listOf(WeatherNews(25.0), WeatherNews(35.0)),
    sources = mutableMapOf(
      "openweathermap" to WeatherSource(Url("https://api.openweathermap.org/data/2.5/weather")),
      "googleweather" to WeatherSource(Url("https://weather.google.com"))
    )
  )
)
```

--------------------------------

### A2AServer Setup

Source: https://docs.koog.ai/a2a/a2a-koog-integration

Configures and starts the A2A server to make the Koog agent discoverable via the A2A protocol.

```APIDOC
## A2AServer Setup

### Description
Initializes the A2AServer with an AgentCard and starts the HTTP JSON-RPC transport to expose the agent.

### Parameters
- **agentExecutor** (KoogAgentExecutor) - Required - The executor for the Koog agent.
- **agentCard** (AgentCard) - Required - Metadata defining the agent's identity, capabilities, and skills.
```

--------------------------------

### Install OpenTelemetry Feature

Source: https://docs.koog.ai/features/open-telemetry

Initialize the AIAgent with the OpenTelemetry feature enabled.

```kotlin
val agent = AIAgent(
    promptExecutor = promptExecutor,
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = "You are a helpful assistant.",
    installFeatures = {
        install(OpenTelemetry) {
            // Configuration options go here
        }
    }
)
```

```java
var agent = AIAgent.builder()
    .promptExecutor(promptExecutor)
    .llmModel(OpenAIModels.Chat.GPT4o)
    .systemPrompt("You are a helpful assistant.")
    .install(OpenTelemetry.Feature, config -> {
        // Configuration options go here
    })
    .build();
```

--------------------------------

### Implement Few-Shot Learning

Source: https://docs.koog.ai/prompts/prompt-creation

Provide examples of expected interactions using assistant messages to guide LLM output.

```Kotlin
val prompt = prompt("article_review") {
    system("Evaluate the article.")

    // Example 1
    user("The article is clear and easy to understand.")
    assistant("positive")

    // Example 2
    user("The article is hard to read but it's clear and useful.")
    assistant("neutral")

    // Example 3
    user("The article is confusing and misleading.")
    assistant("negative")

    // New input to classify
    user("The article is interesting and helpful.")
}
```

```Java
Prompt prompt = Prompt.builder("article_review")
    .system("Evaluate the article.")

    // Example 1
    .user("The article is clear and easy to understand.")
    .assistant("positive")

    // Example 2
    .user("The article is hard to read but it's clear and useful.")
    .assistant("neutral")

    // Example 3
    .user("The article is confusing and misleading.")
    .assistant("negative")

    // New input to classify
    .user("The article is interesting and helpful.")
    .build();
```

--------------------------------

### Initialize A2A Server

Source: https://docs.koog.ai/a2a/a2a-koog-integration

Configures the AgentCard and starts the A2AServer using the HttpJSONRPCServerTransport.

```kotlin
val agentCard = AgentCard(
    name = "Koog Agent",
    url = "http://localhost:9999/koog",
    description = "Simple universal agent powered by Koog",
    version = "1.0.0",
    protocolVersion = "0.3.0",
    preferredTransport = TransportProtocol.JSONRPC,
    capabilities = AgentCapabilities(streaming = true),
    defaultInputModes = listOf("text"),
    defaultOutputModes = listOf("text"),
    skills = listOf(
        AgentSkill(
            id = "koog",
            name = "Koog Agent",
            description = "Universal agent powered by Koog. Supports tool calling.",
            tags = listOf("chat", "tool"),
        )
    )
)
// Server setup
val server = A2AServer(agentExecutor = KoogAgentExecutor(), agentCard = agentCard)
val transport = HttpJSONRPCServerTransport(server)
transport.start(engineFactory = Netty, port = 8080, path = "/chat", wait = true)
```

--------------------------------

### Initialize Chat Agent

Source: https://docs.koog.ai/predefined-agent-strategies

Basic setup for creating an AI agent using the chatAgentStrategy.

```kotlin
val chatAgent = AIAgent(
    promptExecutor = promptExecutor,
    toolRegistry = toolRegistry,
    llmModel = model,
    // Set chatAgentStrategy as the agent strategy
    strategy = chatAgentStrategy()
)
```

```java
AIAgent<String, String> chatAgent = AIAgent.builder()
    .promptExecutor(PromptExecutor.builder().openAI("OPENAI_API_KEY").build())
    .llmModel(OpenAIModels.Chat.O4Mini)
    .toolRegistry(ToolRegistry.builder().build())
    // Set chatAgentStrategy as the agent strategy
    .graphStrategy(AIAgentStrategies.chatAgentStrategy())
    .build();
```

--------------------------------

### ReAct Reasoning Step

Source: https://docs.koog.ai/predefined-agent-strategies

Example of the agent's internal reasoning output.

```text
I need to follow these steps:
1. Get all transactions from last month
2. Filter out deposits (positive amounts)
3. Calculate total spending
```

--------------------------------

### Launch Unity MCP Server

Source: https://docs.koog.ai/examples/UnityMcp

Starts the Unity MCP server process from the specified project path.

```kotlin
// https://github.com/IvanMurzak/Unity-MCP
val pathToUnityProject = "path/to/unity/project"
val process = ProcessBuilder(
    "$pathToUnityProject/com.ivanmurzak.unity.mcp.server/bin~/Release/net9.0/com.IvanMurzak.Unity.MCP.Server",
    "60606"
).start()
```

--------------------------------

### Install Persistence Feature

Source: https://docs.koog.ai/features/agent-persistence

Configure the agent with the Persistence feature using an in-memory storage provider.

```kotlin
val agent = AIAgent(
    promptExecutor = executor,
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    install(Persistence) {
        // Use in-memory storage for snapshots
        storage = InMemoryPersistenceStorageProvider()
    }
}
```

```java
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(executor)
    .llmModel(OllamaModels.Meta.LLAMA_3_2)
    .install(Persistence.Feature, cfg -> {
        // Use in-memory storage for snapshots
        cfg.setStorage(new InMemoryPersistenceStorageProvider());
    })
.build();
```

--------------------------------

### Implement AgentSession for ACP

Source: https://docs.koog.ai/agent-client-protocol

Example implementation of the AgentSession interface, focusing on the prompt method to initialize and run the agent.

```kotlin
class MyAgentSession(
    override val sessionId: SessionId,
    private val promptExecutor: PromptExecutor,
    private val protocol: Protocol,
    private val clock: KoogClock
) : AgentSession {

    private var agentJob: Deferred<Unit>? = null
    private val agentMutex = Mutex()

    override suspend fun prompt(
        content: List<ContentBlock>,
        _meta: JsonElement?
    ): Flow<Event> = channelFlow {
        val agentConfig = AIAgentConfig(
            prompt = prompt("acp") {
                system("You are a helpful assistant.")
            }.appendPrompt(content),
            model = OpenAIModels.Chat.GPT4o,
            maxAgentIterations = 1000
        )

        // Ensure only one agent session runs at a time
        agentMutex.withLock {
            val agent = AIAgent(
                promptExecutor = promptExecutor,
                agentConfig = agentConfig
            ) {
                install(AcpAgent) {
                    this.sessionId = this@MyAgentSession.sessionId.value
                    this.protocol = this@MyAgentSession.protocol
                    this.eventsProducer = this@channelFlow
                    this.setDefaultNotifications = true
                }
            }

            agentJob = async { agent.run("Hello. How can you help me?") }
            agentJob?.await()
        }
    }

    private fun Prompt.appendPrompt(content: List<ContentBlock>): Prompt {
        return withMessages { messages ->
            messages + listOf(content.toKoogMessage(clock))
        }
    }

    override suspend fun cancel() {
        agentJob?.cancel()
    }
}
```

--------------------------------

### Example agent output

Source: https://docs.koog.ai/agents/graph-based-agents

The expected console output after running the math agent with the provided input.

```text
Multiplying 3 and 4...
Multiplying 12 and 5...
Adding 60 and 10...
Adding 70 and 123...
The final result is: 193
```

--------------------------------

### Create Tool Messages in Kotlin and Java

Source: https://docs.koog.ai/prompts/prompt-creation

Use these examples to pre-fill tool call history for few-shot learning scenarios.

```kotlin
val prompt = prompt("calculator_example") {
    system("You are a helpful assistant with access to tools.")
    user("What is 5 + 3?")
    // Tool call
    toolCall(
        id = "calculator_tool_id",
        tool = "calculator",
        args = """{"operation": "add", "a": 5, "b": 3}"""
    )
    // Tool result
    toolResult(
        id = "calculator_tool_id",
        tool = "calculator",
        output = "8"
    )

    // LLM response based on tool result
    assistant("The result of 5 + 3 is 8.")
    user("What is 4 + 5?")
}
```

```java
Prompt prompt = Prompt.builder("calculator_example")
    .system("You are a helpful assistant with access to tools.")
    .user("What is 5 + 3?")
    // Tool call
    .toolCall("calculator_tool_id", "calculator", "{\"operation\": \"add\", \"a\": 5, \"b\": 3}")
    // Tool result
    .toolResult("calculator_tool_id", "calculator", "8")
    // LLM response based on tool result    
    .assistant("The result of 5 + 3 is 8.")
    .user("What is 4 + 5?")
    .build();
```

--------------------------------

### Configure Transport Layer

Source: https://docs.koog.ai/a2a/a2a-server

Sets up the HTTP JSON-RPC transport and starts the server on a specified port.

```kotlin
// HTTP JSON-RPC transport
val transport = HttpJSONRPCServerTransport(server)
transport.start(
    engineFactory = CIO,
    port = 8080,
    path = "/agent",
    wait = true
)
```

--------------------------------

### Example output for cached execution

Source: https://docs.koog.ai/prompts/llm-response-caching

Demonstrates the performance difference between an initial request and a cached retrieval.

```text
First response: Hello! It seems like we're starting a new conversation. What can I help you with today?
First execution took: 48ms
Second response: Hello! It seems like we're starting a new conversation. What can I help you with today?
Second execution took: 1ms
```

--------------------------------

### Configure Named Tool Choice

Source: https://docs.koog.ai/llm-parameters

Examples of initializing LLM parameters with a specific tool choice using the Named strategy.

```kotlin
val specificToolParams = LLMParams(
    toolChoice = LLMParams.ToolChoice.Named(name = "calculator")
)
```

```java
LLMParams specificToolParams = new LLMParams(
    null,        // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    new LLMParams.ToolChoice.Named("calculator"), // toolChoice
    null,        // user
    null         // additionalProperties
);
```

--------------------------------

### Install a custom feature in an agent

Source: https://docs.koog.ai/features/custom-features

Demonstrates how to register the custom logging feature during agent initialization with a specific configuration.

```kotlin
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o
) {
    install(LoggingFeature) {
        loggerName = "my-custom-logger"
    }
}

agent.run("What is Kotlin?")
```

--------------------------------

### Example Chat Session Output

Source: https://docs.koog.ai/features/chat-memory/chat-agent-with-memory

A sample interaction demonstrating the agent's ability to recall previous context.

```text
You: My name is Alice.
Assistant: Nice to meet you, Alice! How can I help you today?

You: What's my favorite color? It's blue.
Assistant: Got it — your favorite color is blue!

You: What's my name?
Assistant: Your name is Alice!
```

--------------------------------

### Enable Langfuse Exporter in AIAgent

Source: https://docs.koog.ai/features/open-telemetry/opentelemetry-langfuse-exporter

Basic setup to install the OpenTelemetry feature and add the Langfuse exporter to an agent.

```kotlin
fun main() = runBlocking {
    val agent = AIAgent(
        promptExecutor = promptExecutor,
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addLangfuseExporter()
        }
    }

    println("Running agent with Langfuse tracing")

    val result = agent.run("Tell me a joke about programming")
    println("Result: $result\nSee traces on the Langfuse instance")
}
```

```java
public static void main(String[] args) {
    var agent = AIAgent.builder()
        .promptExecutor(promptExecutor)
        .llmModel(OpenAIModels.Chat.GPT4oMini)
        .systemPrompt("You are a code assistant. Provide concise code examples.")
        .install(OpenTelemetry.Feature, config ->
            LangfuseKt.addLangfuseExporter(config)
        )
        .build();

    System.out.println("Running agent with Langfuse tracing");

    var result = agent.run("Tell me a joke about programming");
    System.out.println("Result: " + result + "\nSee traces on the Langfuse instance");
}
```

--------------------------------

### Initialize and run an AIAgent

Source: https://docs.koog.ai/prompts

Demonstrates setting up an agent with a system prompt and executing a user query using a prompt executor.

```kotlin
// Create an agent
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    systemPrompt = "You are a helpful assistant.",
    llmModel = OpenAIModels.Chat.GPT4o
)

// Run the agent
val result = agent.run("What is Koog?")
```

```java
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .systemPrompt("You are a helpful assistant. Answer user questions concisely.")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .build();

var result = agent.run("What is Koog?");
```

--------------------------------

### Configure and Initialize the AIAgent

Source: https://docs.koog.ai/examples/VaccumAgent

Sets up the environment, tool registry, and agent configuration including the system prompt and model selection.

```kotlin
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.reflect.asTools
import ai.koog.agents.ext.agent.chatAgentStrategy
import ai.koog.agents.ext.tool.AskUser
import ai.koog.agents.ext.tool.SayToUser
import ai.koog.prompt.dsl.prompt
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
import ai.koog.prompt.params.LLMParams


val env = VacuumEnv()
val apiToken = System.getenv("OPENAI_API_KEY") ?: error("OPENAI_API_KEY environment variable not set")
val executor = simpleOpenAIExecutor(apiToken = apiToken)

val toolRegistry = ToolRegistry {
    tool(SayToUser)
    tool(AskUser)
    tools(VacuumTools(env).asTools())
}

val systemVacuumPrompt = """
    You are a reflex vacuum-cleaner agent living in a two-cell world labelled A and B.
    Your goal: make both cells clean, using the provided tools.
    First, call sense() to inspect where you are. Then decide: if dirty → clean(); else moveLeft()/moveRight().
    Continue until both cells are clean, then tell the user "done".
    Use sayToUser to inform the user about each step.
""".trimIndent()

val agentConfig = AIAgentConfig(
    prompt = prompt("chat", params = LLMParams(temperature = 1.0)) {
        system(systemVacuumPrompt)
    },
    model = OpenAIModels.Chat.GPT4o,
    maxAgentIterations = 50,
)

val agent = AIAgent(
    promptExecutor = executor,
    strategy = chatAgentStrategy(),
    agentConfig = agentConfig,
    toolRegistry = toolRegistry
)
```

--------------------------------

### Agent output example

Source: https://docs.koog.ai/agents/functional-agents

Example output generated by the functional agent.

```text
The answer to 12 × 9 is 108.
```

--------------------------------

### Configure and Initialize Banking Agent

Source: https://docs.koog.ai/examples/Banking

Sets up the agent configuration with specific prompts and models, then initializes the agent with the defined strategy.

```kotlin
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.prompt.dsl.prompt

val agentConfig = AIAgentConfig(
    prompt = prompt(id = "banking assistant") {
        system("$bankingAssistantSystemPrompt\n$transactionAnalysisPrompt")
    },
    model = OpenAIModels.Chat.GPT4o,
    maxAgentIterations = 50  // Allow for complex multi-step operations
)

val agent = AIAgent<String, String>(
    promptExecutor = openAIExecutor,
    strategy = strategy,
    agentConfig = agentConfig,
    toolRegistry = toolRegistry,
)
```

--------------------------------

### Agent output example

Source: https://docs.koog.ai/agents/graph-based-agents

Example of the text output generated by the calculator agent.

```text
To calculate this, I'll follow the order of operations:

1. Multiply 3 by 4: 3 * 4 = 12
2. Multiply the result by 5: 12 * 5 = 60
3. Add 10: 60 + 10 = 70
4. Add 123: 70 + 123 = 193

The final answer is 193.
```

--------------------------------

### Initialize Basic LLM Parameters

Source: https://docs.koog.ai/llm-parameters

Configure standard parameters like temperature, max tokens, and tool choice.

```kotlin
// A basic set of parameters with limited length
val basicParams = LLMParams(
    temperature = 0.7,
    maxTokens = 150,
    toolChoice = LLMParams.ToolChoice.Auto
)
```

```java
// A basic set of parameters with limited length
LLMParams basicParams = new LLMParams(
    0.7,         // temperature
    150,         // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
    null,        // user
    null         // additionalProperties
);
```

--------------------------------

### Configure Basic Tracing to Logger

Source: https://docs.koog.ai/features/tracing

Demonstrates how to install the Tracing feature with a log writer to capture agent execution events.

```kotlin
// Create a logger
val logger = KotlinLogging.logger { }

// Create an agent with tracing
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    install(Tracing) {
        addMessageProcessor(TraceFeatureMessageLogWriter(logger))
    }
}

// Run the agent
agent.run("Hello, agent!")
```

```java
// Create a logger
var logger = LoggerFactory.getLogger("tracing");

// Create an agent with tracing
var agent = AIAgent.builder()
    .promptExecutor(PromptExecutor.builder().ollama().build())
    .llmModel(OllamaModels.Meta.LLAMA_3_2)

    .install(Tracing.Feature, config -> {
        config.addMessageProcessor(TraceFeatureMessageLogWriter.create(logger));
    })
    .build();

// Run the agent
agent.run("Hello, agent!");
```

--------------------------------

### install(A2AAgentServer)

Source: https://docs.koog.ai/a2a/a2a-koog-integration

Installs the A2AAgentServer feature into the Koog agent, requiring a RequestContext and SessionEventProcessor.

```APIDOC
## install(A2AAgentServer)

### Description
Installs the A2AAgentServer feature into the Koog agent to enable A2A protocol communication.

### Parameters
- **context** (RequestContext) - Required - The request context for the agent.
- **eventProcessor** (SessionEventProcessor) - Required - The event processor for handling session events.
```

--------------------------------

### Install ChatMemory Feature in Agent

Source: https://docs.koog.ai/spring-ai-integration

Inject the auto-configured ChatHistoryProvider into your agent service and install the ChatMemory feature.

```kotlin
import ai.koog.agents.chatMemory.feature.ChatMemory
import ai.koog.agents.chatMemory.feature.ChatHistoryProvider
import ai.koog.agents.core.agent.AIAgent
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.model.PromptExecutor
import org.springframework.stereotype.Service

@Service
class MyAgentService(
    private val promptExecutor: PromptExecutor,
    private val chatStorage: ChatHistoryProvider,
) {

    suspend fun askAgent(userMessage: String, sessionId: String): String {
        val agent = AIAgent(
            promptExecutor = promptExecutor,
            llmModel = OpenAIModels.Chat.GPT5Nano,
            systemPrompt = "You are a helpful assistant.",
        ) {
            install(ChatMemory) {
                chatHistoryProvider = chatStorage
            }
        }

        return agent.run(userMessage, sessionId)
    }
}
```

--------------------------------

### Initialize and run a DeepSeek agent

Source: https://docs.koog.ai/quickstart

Demonstrates agent creation for DeepSeek V4 Flash using Kotlin.

```kotlin
fun main() = runBlocking {
    // Get the DeepSeek API key from the DEEPSEEK_API_KEY environment variable
    val apiKey = System.getenv("DEEPSEEK_API_KEY")
        ?: error("The API key is not set.")

    // Create an agent
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(DeepSeekLLMClient(apiKey)),
        llmModel = DeepSeekModels.DeepSeekV4Flash
    )

    // Run the agent
    val result = agent.run("Hello! How can you help me?")
    println(result)
}
```

```java
// Get the DeepSeek API key from the DEEPSEEK_API_KEY environment variable
String apiKey = System.getenv("DEEPSEEK_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("The API key is not set.");
}
```

--------------------------------

### Configure ReAct Strategy for AI Agents

Source: https://docs.koog.ai/predefined-agent-strategies

Demonstrates initializing an AIAgent with the reActStrategy and a tool registry.

```kotlin
val bankingAgent = AIAgent(
    promptExecutor = promptExecutor,
    llmModel = model,
    // Use reActStrategy as the agent strategy
    strategy = reActStrategy(
        reasoningInterval = 1,
        name = "banking_agent"
    ),
    // Add tools the agent can use
    toolRegistry = ToolRegistry {
        tool(getTransactions)
        tool(calculateSum)
    }
)

suspend fun main() { 
    // Run the agent with a user query
    val result = bankingAgent.run("How much did I spend last month?")
}
```

```java
// Add tools the agent can use
ToolRegistry toolRegistry = ToolRegistry.builder()
    .tools(new BankingTools())
    .build();

AIAgent<String, String> bankingAgent = AIAgent.<String, String>builder()
    .promptExecutor(PromptExecutor.builder().openAI("OPENAI_API_KEY").build())
    .llmModel(OpenAIModels.Chat.O4Mini)
    // Use reActStrategy as the agent strategy
    .graphStrategy(AIAgentStrategies.reActStrategy(1, "banking_agent"))
    .toolRegistry(toolRegistry)
    .build();

// Run the agent with a user query
String result = bankingAgent.run("How much did I spend last month?");
```

--------------------------------

### Install a custom feature into an agent

Source: https://docs.koog.ai/features/custom-features

Uses the install method within the AIAgent builder to register the feature and configure its properties.

```kotlin
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    systemPrompt = "You are a helpful assistant. Answer user questions concisely.",
    llmModel = OpenAIModels.Chat.GPT4o
) {
    install(MyFeature) {
        configProperty = "value"
    }
}
```

--------------------------------

### Execute prompts with OpenAILLMClient

Source: https://docs.koog.ai/prompts/llm-clients

Demonstrates creating an OpenAI client, defining a prompt with system and user messages, and executing it against the GPT-4o model.

```kotlin
fun main() = runBlocking {
    // Create an OpenAI client
    val apiKey = System.getenv("OPENAI_API_KEY")
    val client = OpenAILLMClient(apiKey)

    // Create a prompt
    val prompt = prompt("prompt_name", LLMParams()) {
        // Add a system message to set the context
        system("You are a helpful assistant.")

        // Add a user message
        user("Tell me about Kotlin")

        // You can also add assistant messages for few-shot examples
        assistant("Kotlin is a modern programming language...")

        // Add another user message
        user("What are its key features?")
    }

    // Run the prompt
    val response = client.execute(prompt, OpenAIModels.Chat.GPT4o)
    // Print the response
    println(response)
}
```

```java
// Create an OpenAI client
String apiKey = System.getenv("OPENAI_API_KEY");
OpenAILLMClient client = openAIClient(apiKey);

// Create a prompt
Prompt prompt = Prompt.builder("prompt_name")
    // Add a system message to set the context
    .system("You are a helpful assistant.")

    // Add a user message
    .user("Tell me about Kotlin")

    // You can also add assistant messages for few-shot examples
    .assistant("Kotlin is a modern programming language...")

    // Add another user message
    .user("What are its key features?")
    .build();

// Run the prompt
List<Message.Response> response = client.execute(prompt, OpenAIModels.Chat.GPT4o, Collections.emptyList());
// Print the response
System.out.println(response);

client.close();
```

--------------------------------

### Create a tool registry from client

Source: https://docs.koog.ai/model-context-protocol

Initializes a tool registry using an existing MCP client instance.

```kotlin
// Create a tool registry from an existing MCP client
val toolRegistry = McpToolRegistryProvider.fromClient(
    mcpClient = existingMcpClient,
    serverInfo = McpServerInfo(url = "http://localhost:8931")
)
```

--------------------------------

### Install Koog plugin and define routes

Source: https://docs.koog.ai/ktor-plugin

Install the Koog plugin in the Ktor application module and utilize aiAgent within routing blocks.

```kotlin
fun Application.module() {
    install(Koog) {
        // You can also configure providers programmatically (see below)
    }

    routing {
        route("/ai") {
            post("/chat") {
                val userInput = call.receiveText()
                // Create and run a default single‑run agent using a specific model
                val output = aiAgent(
                    strategy = reActStrategy(),
                    model = OpenAIModels.Chat.GPT4_1,
                    input = userInput
                )
                call.respond(HttpStatusCode.OK, output)
            }
        }
    }
}
```

--------------------------------

### Initialize A2AServer

Source: https://docs.koog.ai/a2a/a2a-server

Instantiates the server by providing the agent executor and card.

```kotlin
val server = A2AServer(
    agentExecutor = EchoAgentExecutor(),
    agentCard = agentCard
)
```

--------------------------------

### Filter agent events in feature installation

Source: https://docs.koog.ai/features/custom-features

Use setEventFilter within the install block to restrict which agent lifecycle events a feature processes.

```kotlin
install(MyFeature) {
    setEventFilter { context ->
        context.eventType is AgentLifecycleEventType.LLMCallStarting ||
            context.eventType is AgentLifecycleEventType.LLMCallCompleted
    }
}
```

--------------------------------

### Perform basic LLM requests

Source: https://docs.koog.ai/sessions

Demonstrates how to execute requests with and without tool support inside a write session.

```kotlin
llm.writeSession {
    // Make a request with tools enabled
    val response = requestLLM()

    // Make a request without tools
    val responseWithoutTools = requestLLMWithoutTools()
}
```

```java
ctx.getLlm().writeSession(session -> {
    // Make a request with tools enabled
    var response = session.requestLLM();

    // Make a request without tools
    var responseWithoutTools = session.requestLLMWithoutTools();

    return null;
});
```

--------------------------------

### Tool Result Data

Source: https://docs.koog.ai/predefined-agent-strategies

Example of raw data returned by a tool execution.

```json
[
  {date: "2025-05-25", amount: -100.00, description: "Grocery Store"},
  {date: "2025-05-31", amount: +1000.00, description: "Salary Deposit"},
  {date: "2025-06-10", amount: -500.00, description: "Rent Payment"},
  {date: "2025-06-13", amount: -200.00, description: "Utilities"}
]
```

--------------------------------

### Initialize Notebook Descriptors

Source: https://docs.koog.ai/examples/Langfuse

Configure the notebook environment for Koog usage.

```text
%useLatestDescriptors
//%use koog
```

--------------------------------

### Create a SimpleLLMPlanner agent

Source: https://docs.koog.ai/agents/planner-agents/llm-based-planners

Initialize a planner agent using SimpleLLMPlanner to execute tasks based on a predefined prompt and model configuration.

```kotlin
// Create the planner
val planner = SimpleLLMPlanner()

// Wrap it in a planner strategy
val strategy = AIAgentPlannerStrategy(
    name = "simple-planner",
    planner = planner
)

// Configure the agent
val agentConfig = AIAgentConfig(
    prompt = prompt("planner") {
        system("You are a helpful planning assistant.")
    },
    model = OpenAIModels.Chat.GPT4o,
    maxAgentIterations = 50
)

// Create the planner agent
val agent = PlannerAIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    strategy = strategy,
    agentConfig = agentConfig
)

suspend fun main() {
    // Run the agent with a task
    val result = agent.run("Create a plan to organize a team meeting")
    println(result)
}
```

```java
// Create the planner strategy with LLM-based planner
AIAgentPlannerStrategy<String, String> strategy =
    Planners.llmBased("simple-planner")
        .build();

// Create the OpenAI executor
var promptExecutor = PromptExecutor.builder()
    .openAI("OPENAI_API_KEY")
    .build();

// Create the planner agent using AIAgent builder
AIAgent<String, String> agent = AIAgent.builder()
    .plannerStrategy(strategy)
    .promptExecutor(promptExecutor)
    .llmModel(OpenAIModels.Chat.GPT4o)
    .systemPrompt("You are a helpful planning assistant.")
    .maxIterations(50)
    .build();

// Run the agent with a task
String result = agent.run("Create a plan to organize a team meeting");
System.out.println(result);
```

--------------------------------

### Initialize ReAct Strategy

Source: https://docs.koog.ai/predefined-agent-strategies

Configure an AI agent with the ReAct strategy using Kotlin or Java.

```kotlin
val reActAgent = AIAgent(
    promptExecutor = promptExecutor,
    toolRegistry = toolRegistry,
    llmModel = model,
    // Set reActStrategy as the agent strategy
    strategy = reActStrategy(
        // Set optional parameter values
        reasoningInterval = 1,
        name = "react_agent"
    )
)
```

```java
AIAgent<String, String> reActAgent = AIAgent.builder()
    .promptExecutor(PromptExecutor.builder().openAI("OPENAI_API_KEY").build())
    .llmModel(OpenAIModels.Chat.O4Mini)
    .toolRegistry(ToolRegistry.builder().build())
    // Set reActStrategy as the agent strategy
    .graphStrategy(AIAgentStrategies.reActStrategy(
        // Set optional parameter values
        1, // reasoningInterval
        "react_agent" // name
    ))
    .build();
```

--------------------------------

### Transaction Analysis Output

Source: https://docs.koog.ai/examples/Banking

Example output returned by the transaction analysis assistant.

```text
Transaction Analysis Assistant started





You have spent a total of $517.64 on restaurants this month.

Task completed successfully.
```

--------------------------------

### Agent Execution Output

Source: https://docs.koog.ai/agents/graph-based-agents

Example output generated by the agent during a multi-step calculation.

```text
Multiplying 3 and 4...
The output from the first operation was multiplied by 5:
5 * 12 = 60

Then, 10 was added to the result:
60 + 10 = 70

Finally, 123 was added to the result:
70 + 123 = 193
```

--------------------------------

### Initialize a Prompt Object

Source: https://docs.koog.ai/prompts/prompt-creation

Create a new prompt instance with a unique identifier.

```Kotlin
val prompt = prompt("unique_prompt_id") {
    // List of messages
}
```

```Java
Prompt prompt = Prompt.builder("unique_prompt_id")
    // List of messages
    .build();
```

--------------------------------

### Define Markdown Structure

Source: https://docs.koog.ai/streaming-api

Use MarkdownStructureDefinition to specify the expected schema and provide examples.

```Kotlin
fun markdownBookDefinition(): MarkdownStructureDefinition {
    return MarkdownStructureDefinition("bookList", schema = {
        markdown {
            header(1, "title")
            bulleted {
                item("author")
                item("description")
            }
        }
    }, examples = {
        markdown {
            header(1, "The Great Gatsby")
            bulleted {
                item("F. Scott Fitzgerald")
                item("A novel set in the Jazz Age that tells the story of Jay Gatsby's unrequited love for Daisy Buchanan.")
            }
        }
    })
}
```

```Java
// TODO not yet supported in Java
```

--------------------------------

### Initialize and run a Gemini agent

Source: https://docs.koog.ai/quickstart

Demonstrates agent creation for Gemini 2.5 Pro using both Kotlin and Java.

```kotlin
fun main() = runBlocking {
    // Get the Gemini API key from the GOOGLE_API_KEY environment variable
    val apiKey = System.getenv("GOOGLE_API_KEY")
        ?: error("The API key is not set.")

    // Create an agent
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(GoogleLLMClient(apiKey)),
        llmModel = GoogleModels.Gemini2_5Pro
    )

    // Run the agent
    val result = agent.run("Hello! How can you help me?")
    println(result)
}
```

```java
// Get the Gemini API key from the GOOGLE_API_KEY environment variable
String apiKey = System.getenv("GOOGLE_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("The API key is not set.");
}

// Create an agent
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(googleClient(apiKey)))
    .llmModel(GoogleModels.Gemini2_5Pro)
    .build();

// Run the agent
String result = agent.run("Hello! How can you help me?");
System.out.println(result);
```

--------------------------------

### Discover MCP Tools

Source: https://docs.koog.ai/examples/GoogleMapsMcp

Create a tool registry from the running process and output the available tools and their descriptors.

```kotlin
val toolRegistry = McpToolRegistryProvider.fromTransport(
    transport = McpToolRegistryProvider.defaultStdioTransport(process)
)
toolRegistry.tools.forEach {
    println(it.name)
    println(it.descriptor)
}
```

--------------------------------

### Implement the ToolSet interface

Source: https://docs.koog.ai/tools/annotation-based-tools

Examples of implementing the ToolSet interface with @Tool annotated methods.

```kotlin
class MyToolSet : ToolSet {
    @Tool
    fun myTool(): String {
        // Tool implementation
        return "Result"
    }

    @Tool(customName = "customToolName")
    fun anotherTool(): String {
        // Tool implementation
        return "Result"
    }
}
```

```java
public class MyToolSet implements ToolSet {
    @Tool
    public String myTool() {
        // Tool implementation
        return "Result";
    }

    @Tool(customName = "customToolName")
    public String anotherTool() {
        // Tool implementation
        return "Result";
    }
}
```

--------------------------------

### Configure Serializer in AIAgentConfig

Source: https://docs.koog.ai/serialization

Examples of setting the serializer during AIAgentConfig construction in Kotlin and Java.

```kotlin
val agentConfig = AIAgentConfig(
    prompt = prompt("assistant") {
        system("You are a helpful assistant.")
    },
    model = OpenAIModels.Chat.GPT4o,
    maxAgentIterations = 10,
    serializer = JacksonSerializer()
)
```

```java
var agentConfig = AIAgentConfig.builder()
    .model(OpenAIModels.Chat.GPT4o)
    .prompt(
        Prompt.builder("assistant")
            .system("You are a helpful assistant")
            .build()
    )
    .maxAgentIterations(10)
    .serializer(new JacksonSerializer())
    .build();
```

--------------------------------

### Setting up Event Handlers during Agent Initialization

Source: https://docs.koog.ai/features/agent-event-handlers

Uses the handleEvents extension function within the agent constructor to install and configure handlers.

```kotlin
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
){
    handleEvents {
        // Handle tool calls
        onToolCallStarting { eventContext ->
            println("Tool called: ${eventContext.toolName} with args ${eventContext.toolArgs}")
        }
        // Handle event triggered when the agent completes its execution
        onAgentCompleted { eventContext ->
            println("Agent finished with result: ${eventContext.result}")
        }

        // Other event handlers
    }
}
```

--------------------------------

### Registering Built-in Tools

Source: https://docs.koog.ai/tools/built-in-tools

Example of how to initialize a ToolRegistry with built-in tools and assign it to an AIAgent.

```APIDOC
val toolRegistry = ToolRegistry {
    tool(SayToUser)
    tool(AskUser)
    tool(ExitTool)
    tool(ReadFileTool(JVMFileSystemProvider.ReadOnly))
    tool(ListDirectoryTool(JVMFileSystemProvider.ReadOnly))
    tool(WriteFileTool(JVMFileSystemProvider.ReadWrite))
}

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiToken),
    systemPrompt = "You are a helpful assistant.",
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry
)
```

--------------------------------

### Initialize an AIAgent with a system prompt

Source: https://docs.koog.ai/agents/basic-agents

Define an agent's role and instructions using a system prompt. Requires an API key provided via environment variables.

```Kotlin
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("YOUR_API_KEY")),
    systemPrompt = "You are an expert in internet memes. Be helpful, friendly, and answer user questions concisely, showing your knowledge of memes.",
    llmModel = OpenAIModels.Chat.GPT4o
)
```

```Java
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))
    .systemPrompt("You are an expert in internet memes. Be helpful, friendly, and answer user questions concisely, showing your knowledge of memes.")
    .llmModel(OpenAIModels.Chat.GPT4o)
    .build();
```

--------------------------------

### Bedrock Agent Execution Output

Source: https://docs.koog.ai/examples/BedrockAgent

Example console output for the agent execution interaction.

```text
🎉 Bedrock Agent with Switch Tools - Ready to Go!
💬 You can ask me to:
   • Turn the switch on/off
   • Check the current switch state
   • Ask questions about the switch

💡 Example: 'Please turn on the switch' or 'What's the current state?'
📝 Type your request:



The execution was interrupted
```

--------------------------------

### Configure Chat Memory

Source: https://docs.koog.ai/features/chat-memory

Customize the chat history provider and message preprocessors during installation.

```kotlin
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    llmModel = OpenAIModels.Chat.GPT4oMini
) {
    install(ChatMemory) {
        chatHistoryProvider = MyDatabaseChatHistoryProvider()
        windowSize(20)
        filterMessages { it is Message.User || it is Message.Assistant }
    }
}
```

```java
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(executor)
    .llmModel(OpenAIModels.Chat.GPT4oMini)
    .install(ChatMemory.Feature, config -> config
            .chatHistoryProvider(new MyDatabaseChatHistoryProvider())
            .windowSize(20)
            .filterMessages(msg -> msg instanceof Message.User || msg instanceof Message.Assistant))
    .build();
```

--------------------------------

### Start Jaeger with Docker Compose

Source: https://docs.koog.ai/features/open-telemetry

Command to initialize the Jaeger all-in-one container environment.

```bash
docker compose up -d
```

--------------------------------

### Creating a Prompt

Source: https://docs.koog.ai/prompts

Demonstrates how to instantiate a Prompt object using the Kotlin DSL or the Java builder API.

```APIDOC
## Prompt Creation

### Description
Prompts are defined using the `Prompt` data class, which contains an `id`, a list of `messages`, and optional `params` for LLM configuration.

### Kotlin DSL Example
```kotlin
val myPrompt = prompt("hello-koog") {
    system("You are a helpful assistant.")
    user("What is Koog?")
}
```

### Java Builder Example
```java
var myPrompt = Prompt.builder("hello-koog")
    .system("You are a helpful assistant.")
    .user("What is Koog?")
    .build();
```
```

--------------------------------

### Agent Tool Call Output

Source: https://docs.koog.ai/agents/basic-agents

Example of the console output generated when the agent invokes a tool.

```text
Tool called: askUser with args {"question":"Which meme would you like me to explain?"}
```

--------------------------------

### Configure and Run the GOAP Agent

Source: https://docs.koog.ai/agents/planner-agents/goap-agents

Sets up the agent configuration and executes the planning process.

```kotlin
// Create and run the agent
val agentConfig = AIAgentConfig(
    prompt = prompt("writer") {
        system("You are a professional content writer.")
    },
    model = OpenAIModels.Chat.GPT4o,
    maxAgentIterations = 20
)

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    strategy = planner,
    agentConfig = agentConfig
)

suspend fun main() {
    val result = agent.run("The Future of AI in Software Development")
    println("Final state: $result")
}
```

--------------------------------

### Start Google Maps MCP Server

Source: https://docs.koog.ai/examples/GoogleMapsMcp

Launch the Google Maps MCP Docker container as a process to enable communication over stdio.

```kotlin
// Start the Docker container with the Google Maps MCP server
val process = ProcessBuilder(
    "docker",
    "run",
    "-i",
    "-e",
    "GOOGLE_MAPS_API_KEY=$googleMapsApiKey",
    "mcp/google-maps"
).start()
```
Tokens:
Raw