Workshop: Tool-Using Agent (Research Assistant)

Build a Research Assistant that takes a question, searches for information (mocked), summarizes the findings, and cites its sources. This brings together tools, system prompts, and the agent loop.

What You Will Build

• A mocked search tool that returns a few results with titles, snippets, and URLs
• A single agent that calls the tool, then writes a summary with numbered citations
• A test for the tool logic

Diagram: The Research Assistant flow.

Loading diagram...

Step 1: Define the Data Model

Model one search result as a data class. Return it as a readable string so the LLM can use it.

data class SearchResult(
    val title: String,
    val snippet: String,
    val url: String
) {
    override fun toString() = "[$title] $snippet ($url)"
}

Step 2: Define the Mocked Search Tool

Implement ToolSet. The tool returns a few hardcoded results. Later you can replace the body with a real HTTP call.

class ResearchTools : ToolSet {

    private val mockIndex = mapOf(
        "kotlin coroutines" to listOf(
            SearchResult(
                "Coroutines overview",
                "Coroutines are lightweight threads for async work.",
                "https://kotlinlang.org/coroutines"
            ),
            SearchResult(
                "Structured concurrency",
                "Each async operation runs inside a scope.",
                "https://kotlinlang.org/structured-concurrency"
            )
        )
    )

    @Tool
    @LLMDescription("Search the web for relevant pages. Use this before answering.")
    fun search(
        @LLMDescription("The search query") query: String
    ): String {
        val key = mockIndex.keys.firstOrNull { query.contains(it, ignoreCase = true) }
        val results = mockIndex[key].orEmpty()
        if (results.isEmpty()) return "No results for '$query'."
        return results.mapIndexed { i, r -> "${i + 1}. $r" }.joinToString("\n")
    }
}

Step 3: Create the Agent

The system prompt is the key. It tells the LLM to search first, then summarize with numbered citations.

import kotlinx.coroutines.runBlocking

fun researchAgent() = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY") ?: error("Set OPENAI_API_KEY")),
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = """
        You are a research assistant.
        1. Always call the 'search' tool before answering.
        2. Summarize what you found in 3-4 sentences.
        3. Add a 'Sources:' section with numbered citations matching the results.
    """.trimIndent(),
    toolRegistry = ToolRegistry { tools(ResearchTools()) },
    maxIterations = 8
)

fun main() = runBlocking {
    val agent = researchAgent()
    println(agent.run("How do Kotlin coroutines work?"))
}

Expected output:

Kotlin coroutines are lightweight units of async work that run on a few
real threads. Each operation belongs to a scope, which keeps concurrent
work structured and easy to cancel.

Sources:
1. Coroutines overview (https://kotlinlang.org/coroutines)
2. Structured concurrency (https://kotlinlang.org/structured-concurrency)

Step 4: Test the Tool

Test the tool logic directly, without the LLM. This is fast and deterministic.

import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue

class ResearchToolsTest {
    private val tools = ResearchTools()

    @Test
    fun `known query returns results`() {
        val out = tools.search("kotlin coroutines")
        assertTrue(out.contains("Coroutines overview"))
        assertTrue(out.contains("1."))
    }

    @Test
    fun `unknown query returns no results`() {
        assertEquals("No results for 'mars rovers'.", tools.search("mars rovers"))
    }
}

Run with ./gradlew test. To test the full agent without spending tokens, mock the promptExecutor (Koog lets you inject a fake executor that returns canned responses).

Step 5: Try It

1. Set OPENAI_API_KEY.
2. Run main.
3. Watch the agent call search, then produce a cited summary.

Bonus Challenges

• Add more tools: a fetchPage(url) tool that returns more text from a URL, or a calculator tool for numeric questions.
• Improve prompting: make the agent ask a clarifying question first when the query is vague.
• Add conversation memory: keep a list of past questions so the agent can answer follow-ups.
• Stream the answer: switch to streaming mode so the summary prints token by token.
• Go live: replace the mocked search body with a real HTTP call to a search API.

What You Learned

• How to model tool results with data classes
• How a system prompt drives agent behavior
• How to test tools independently of the LLM
• How to extend the agent with more tools and memory

You now have a complete, testable tool-using agent in Koog.