Agent Design Patterns

Choose the Right Shape

Not every task needs one agent. As work gets complex, you arrange agents and steps into a pattern. Koog supports all of these. A basic AIAgent covers the first; the rest are compositions you build with Kotlin coroutines and Koog's strategy graphs.

Diagram: Four common patterns side by side.

Loading diagram...

When to Use Each

Start with a single agent. Only split into multiple agents when one model prompt gets too big or too slow.

Pattern 1: Single Agent

One AIAgent with all tools. Simple, fast to build. See 02-defining-tools-and-functions.md.

Pattern 2: Router

A small "router" agent reads the input and picks a category. Then you run the matching specialist agent.

suspend fun routeAndAnswer(question: String): String {
    val router = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.Chat.GPT4o,
        systemPrompt = "Reply with exactly one word: MATH, WEATHER, or OTHER."
    )
    val category = router.run(question).trim().uppercase()

    return when (category) {
        "MATH" -> mathAgent.run(question)
        "WEATHER" -> weatherAgent.run(question)
        else -> generalAgent.run(question)
    }
}

Pattern 3: Sequential Pipeline

Chain agents so each output feeds the next. This is also expressible as a Koog strategy graph (nodeStart -> nodeA -> nodeB -> nodeFinish), but a plain function chain is clear and easy to test:

suspend fun pipeline(topic: String): String {
    val research = researchAgent.run("Find facts about: $topic")
    val summary  = summaryAgent.run("Summarize: $research")
    return translationAgent.run("Translate to Thai: $summary")
}

Pattern 4: Parallel Execution

When subtasks are independent, run them with async and collect with awaitAll. Koog itself uses this for parallel tool calls and parallel strategy nodes.

import kotlinx.coroutines.*

suspend fun parallelAnswer(question: String): String = coroutineScope {
    val parts = listOf(
        async { agent.run("Part 1: $question") },
        async { agent.run("Part 2: $question") },
        async { agent.run("Part 3: $question") }
    ).awaitAll()
    parts.joinToString("\n---\n")
}

All three calls run at the same time. Total time is close to the slowest call, not the sum.

Guidance

• Prefer one agent until you have a reason to split
• Use router when inputs belong to clear, separate types
• Use pipeline for ordered steps where each depends on the last
• Use parallel only for truly independent work
• Measure latency and token cost before and after splitting

Practice

1. Build a router that sends MATH questions to a calculator agent and everything else to a general agent.
2. Turn the router into a pipeline: route, answer, then a final "reviewer" agent that checks the answer.
3. Run three independent research questions in parallel and print the total elapsed time.