Creating Prompts

Creating Prompts

Create prompts using Koog's type-safe DSL. Prompts are instances of the Prompt data class with an id, a list of messages, and optional params for LLM configuration.

Prompt Structure

Kotlin DSL

The recommended way to create prompts:

import ai.koog.prompt.dsl.prompt

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

Message Types

val conversationPrompt = prompt("conversation") {
    system("You are a senior Kotlin developer.")

    // First exchange
    user("What is a sealed class?")
    assistant("A sealed class is a class that restricts inheritance...")

    // Follow-up
    user("Can you give me an example?")
}

Tool Calls and Results

val toolPrompt = prompt("with-tools") {
    system("You are a helpful assistant with access to tools.")
    user("What's the weather in Madrid?")

    // Tool call from the LLM
    toolCall(
        id = "call_123",
        name = "get_weather",
        arguments = """{"city": "Madrid"}"""
    )

    // Tool result
    toolResult(
        callId = "call_123",
        name = "get_weather",
        content = """{"temperature": 22, "condition": "sunny"}"""
    )
}

Java Builder API

The Java equivalent uses a builder pattern:

import ai.koog.prompt.dsl.Prompt;

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

Java Message Types

var conversationPrompt = Prompt.builder("conversation")
    .system("You are a senior Kotlin developer.")
    .user("What is a sealed class?")
    .assistant("A sealed class is a class that restricts inheritance...")
    .user("Can you give me an example?")
    .build();

Prompt Parameters

Configure LLM behavior with optional parameters:

val configuredPrompt = prompt("creative") {
    system("You are a creative writer.")
    user("Write a short story about a robot.")
    params {
        temperature = 0.9
        maxTokens = 500
    }
}

Text-to-Prompt Auto-Conversion

Agents automatically convert plain text into a Prompt object. This is useful for basic agents that only need a single request:

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

// Plain text is auto-converted to a Prompt
val result = agent.run("What is Koog?")

Prompt with Attachments (Multimodal)

import ai.koog.prompt.dsl.prompt

val imagePrompt = prompt("image-analysis") {
    system("You are an image analysis assistant.")
    user {
        text("What's in this image?")
        image(Path("/path/to/photo.jpg"))
    }
}

See multimodal SKILL for full details on images, audio, video, and file attachments.

Named Prompts for Reuse

object Prompts {
    fun codeReview(language: String) = prompt("code-review") {
        system("You are a senior $language developer. Review code for best practices.")
        user("Review this code:")
    }

    fun summarize(style: String) = prompt("summarize") {
        system("Summarize content in a $style style.")
    }

    fun translate(targetLanguage: String) = prompt("translate") {
        system("You are a professional translator.")
        user("Translate to $targetLanguage:")
    }
}

// Use named prompts
val reviewPrompt = Prompts.codeReview("Kotlin")
val summaryPrompt = Prompts.summarize("concise")

Dynamic Prompt Construction

fun buildRAGPrompt(question: String, context: List<String>) = prompt("rag") {
    system("""
        Answer questions based on the provided context.
        If the context doesn't contain the answer, say so.
    """.trimIndent())

    user {
        text("Context:")
        context.forEach { doc ->
            text("- $doc")
        }
        text("\nQuestion: $question")
    }
}

// Use with vector search results
val context = vectorStore.search(question, limit = 5)
    .map { it.document.content }
val ragPrompt = buildRAGPrompt(question, context)
val answer = promptExecutor.execute(ragPrompt, model)

System Prompt Best Practices

val agentPrompt = prompt("agent-prompt") {
    system("""
        You are a customer support agent for TechCorp.

        ## Rules
        - Always be polite and professional
        - Never share internal company information
        - Escalate complex issues to human support
        - Use the provided tools to look up information

        ## Response Format
        - Greet the customer
        - Address their concern
        - Provide a solution or next steps
        - Ask if they need anything else
    """.trimIndent())

    user("I need help with my order")
}

Prompt Lifecycle in Agents

Agents maintain and manage prompts during their lifecycle in four stages:

1. Initial Setup: System message defines behavior; user message from run() forms the initial prompt
2. Automatic Updates: Predefined nodes (nodeLLMRequest, nodeLLMSendToolResult, nodeAppendPrompt) update the prompt during strategy execution
3. Context Window Management: History compression helps avoid exceeding the LLM context window
4. Manual Management: LLM sessions allow direct Prompt object manipulation via llm.writeSession

Troubleshooting