# jetbrains/koog architecture

> Architecture diagram of the GitHub repository jetbrains/koog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jetbrains/koog
- Repository: https://github.com/jetbrains/koog

## Overview

##### Project type and purpose
- This is a Kotlin Multiplatform framework/library (not an end‐user application) designed to build AI agents in idiomatic Kotlin.
- It exposes modular components (subprojects) for core agent logic, tool integration, features (memory, tracing, event handling, etc.), embeddings, prompt modeling/execution, and prompt caching.

##### File structure
- Top‐level Gradle multiproject: `agents`, `embeddings`, `prompt`, `prompt-executor`, `prompt-cache`, `examples`, `integration-tests`, plus numerous submodules under each.
- `agents/agents-core`: core domain model (agents, contexts, state graph, engine).
- `agents/agents-ext`, `agents/agents-features-*`, `agents/agents-tools`, `agents/agents-utils`, `agents/agents-test`, `agents/agents-mcp`: extension points, feature implementations, tool registry, testing helpers, MCP integration.
- `embeddings/*`: base vector abstraction and LLM‐backed embeddings.
- `prompt/*`: DSLs, models, markdown/XML helpers, structured prompts.
- `prompt-executor/*`: abstract executor model, caching wrapper, LLM client adapters (OpenAI, Anthropic, Google, Ollama, OpenRouter), multi‐LLM orchestrator.
- `prompt-cache/*`: in-memory, file, Redis caches.
- Build scripts (`build.gradle.kts`, `settings.gradle.kts`), `buildSrc` with shared Gradle logic.
- `examples/` and `integration-tests/` illustrate usage and validate end-to-end behavior.

##### README for additional insights
- Confirms modularity and multiplatform support (JVM, JS).
- Highlights core domains: agent, tool, memory, trace, embeddings, prompt‐execution.
- Mentions external services: OpenAI, Anthropic, Google, OpenRouter, Ollama via a “Model Control Protocol (MCP)” adapter.

##### Elements
- **Labels** for each component/module group
- Core modules (Agent Core, Prompt Model)
- Feature modules (Memory, Tracing)
- External services (OpenAI, Redis)
- Platform‐specific code

##### Detailed capture of essential architecture
- Do not overpartition: cluster related modules (e.g., all prompt-executor‐clients together).
- Both static structure (module clusters) and dynamic flow (sequence of calls).
- Extension points: “ToolRegistry” interface, “Feature” hook interfaces, “LLMClient” interface.
- Build‐time vs runtime: Gradle multiproject boundaries vs in‐process modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External user
    User["User"]:::external

    %% Agent Core
    subgraph "Agent Core"
        AIAgent["AIAgent"]:::core
        Context["Context & State Graph"]:::core
        Engine["Engine & Pipeline"]:::core
    end

    %% Tool Registry & MCP
    subgraph "Tool & MCP"
        ToolRegistry["ToolRegistry"]:::extension
        MCP["MCP Adapter"]:::extension
    end

    %% Features Layer
    subgraph "Features Layer"
        Memory["AgentMemory"]:::feature
        Tracing["Tracing"]:::feature
        EventHandler["EventHandler"]:::feature
    end

    %% Embeddings Layer
    subgraph "Embeddings Layer"
        BaseEmbedder["Embedder"]:::embeddings
        LLMEmbedder["LLMEmbedder"]:::embeddings
    end

    %% Prompt Layer
    subgraph "Prompt Layer"
        PromptDSL["PromptDSL"]:::prompt
        Markdown["Markdown Helpers"]:::prompt
        Xml["XML Helpers"]:::prompt
        Structured["StructuredPrompts"]:::prompt
    end

    %% Executor Layer
    subgraph "Executor Layer"
        AbstractExecutor["PromptExecutor"]:::executor
        CachedExecutor["CachedPromptExecutor"]:::executor
        MultiLLMExecutor["DefaultMultiLLMPromptExecutor"]:::executor
    end

    %% LLM Client Layer
    subgraph "LLM Clients"
        OpenAI["OpenAILLMClient"]:::client
        Anthropic["AnthropicLLMClient"]:::client
        Google["GoogleLLMClient"]:::client
        Ollama["OllamaClient"]:::client
        OpenRouter["OpenRouterLLMClient"]:::client
    end

    %% Prompt Cache
    subgraph "Prompt Cache"
        InMemory["InMemoryPromptCache"]:::cache
        FileCache["FilePromptCache"]:::cache
        Redis["RedisPromptCache"]:::cache
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        Examples["Examples"]:::examples
        IntegrationTests["Integration Tests"]:::examples
    end

    %% Flow
    User -->|"run()"| AIAgent
    AIAgent -->|"builds prompt"| PromptDSL
    PromptDSL --> Markdown
    PromptDSL --> Xml
    PromptDSL --> Structured

    PromptDSL -->|"prepare"| AbstractExecutor
    AbstractExecutor -->|"decorate"| CachedExecutor
    CachedExecutor -->|"orchestrate"| MultiLLMExecutor
    CachedExecutor -->|"cache lookup"| InMemory
    CachedExecutor -->|"cache lookup"| FileCache
    CachedExecutor -->|"cache lookup"| Redis

    MultiLLMExecutor --> OpenAI
    MultiLLMExecutor --> Anthropic
    MultiLLMExecutor --> Google
    MultiLLMExecutor --> Ollama
    MultiLLMExecutor --> OpenRouter

    OpenAI -->|"response"| AIAgent
    Anthropic -->|"response"| AIAgent
    Google -->|"response"| AIAgent
    Ollama -->|"response"| AIAgent
    OpenRouter -->|"response"| AIAgent

    AIAgent -->|"invoke"| ToolRegistry
    AIAgent --> MCP
    AIAgent --> Memory
    AIAgent --> Tracing
    AIAgent --> EventHandler

    Memory --> BaseEmbedder
    Memory --> LLMEmbedder

    AIAgent --> Examples
    AIAgent --> IntegrationTests

    %% Click Events
    click AIAgent "https://github.com/jetbrains/koog/blob/develop/agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/AIAgent.kt"
    click Context "https://github.com/jetbrains/koog/tree/develop/agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/context"
    click Engine "https://github.com/jetbrains/koog/tree/develop/agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/engine"
    click ToolRegistry "https://github.com/jetbrains/koog/blob/develop/agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/ToolRegistry.kt"
    click MCP "https://github.com/jetbrains/koog/blob/develop/agents/agents-mcp/src/jvmMain/kotlin/ai/koog/agents/mcp/McpToolRegistryProvider.kt"
    click Memory "https://github.com/jetbrains/koog/blob/develop/agents/agents-features/agents-features-memory/src/commonMain/kotlin/ai/koog/agents/local/memory/feature/AgentMemory.kt"
    click Tracing "https://github.com/jetbrains/koog/blob/develop/agents/agents-features/agents-features-trace/src/commonMain/kotlin/ai/koog/agents/local/features/tracing/feature/Tracing.kt"
    click EventHandler "https://github.com/jetbrains/koog/blob/develop/agents/agents-features/agents-features-event-handler/src/commonMain/kotlin/ai/koog/agents/local/features/eventHandler/feature/EventHandler.kt"
    click BaseEmbedder "https://github.com/jetbrains/koog/blob/develop/embeddings/embeddings-base/src/commonMain/kotlin/ai/koog/embeddings/base/Embedder.kt"
    click LLMEmbedder "https://github.com/jetbrains/koog/blob/develop/embeddings/embeddings-llm/src/commonMain/kotlin/ai/koog/embeddings/local/LLMEmbedder.kt"
    click PromptDSL "https://github.com/jetbrains/koog/blob/develop/prompt-model/src/commonMain/kotlin/ai/koog/prompt/dsl/PromptDSL.kt"
    click Markdown "https://github.com/jetbrains/koog/blob/develop/prompt-markdown/src/commonMain/kotlin/ai/koog/prompt/markdown/Markdown.kt"
    click Xml "https://github.com/jetbrains/koog/blob/develop/prompt-xml/src/commonMain/kotlin/ai/koog/prompt/xml/Xml.kt"
    click Structured "https://github.com/jetbrains/koog/blob/develop/prompt-structure/src/commonMain/kotlin/ai/koog/prompt/structure/StructuredPrompts.kt"
    click AbstractExecutor "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-model/src/commonMain/kotlin/ai/koog/prompt/executor/model/PromptExecutor.kt"
    click CachedExecutor "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-cached/src/commonMain/kotlin/ai/koog/prompt/executor/cached/CachedPromptExecutor.kt"
    click MultiLLMExecutor "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-llms-all/src/commonMain/kotlin/ai/koog/prompt/executor/llms/all/DefaultMultiLLMPromptExecutor.kt"
    click OpenAI "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-clients/prompt-executor-openai-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/openai/OpenAILLMClient.kt"
    click Anthropic "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-clients/prompt-executor-anthropic-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/anthropic/AnthropicLLMClient.kt"
    click Google "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-clients/prompt-executor-google-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/google/GoogleLLMClient.kt"
    click Ollama "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-clients/prompt-executor-ollama-client/src/commonMain/kotlin/ai/koog/prompt/executor/ollama/client/OllamaClient.kt"
    click OpenRouter "https://github.com/jetbrains/koog/blob/develop/prompt-executor/prompt-executor-clients/prompt-executor-openrouter-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/openrouter/OpenRouterLLMClient.kt"
    click InMemory "https://github.com/jetbrains/koog/blob/develop/prompt-cache/prompt-cache-model/src/commonMain/kotlin/ai/koog/prompt/cache/memory/InMemoryPromptCache.kt"
    click FileCache "https://github.com/jetbrains/koog/blob/develop/prompt-cache/prompt-cache-files/src/jvmMain/kotlin/ai/koog/prompt/cache/files/FilePromptCache.kt"
    click Redis "https://github.com/jetbrains/koog/blob/develop/prompt-cache/prompt-cache-redis/src/jvmMain/kotlin/ai/koog/prompt/cache/redis/RedisPromptCache.kt"
    click Examples "https://github.com/jetbrains/koog/tree/develop/examples/"
    click IntegrationTests "https://github.com/jetbrains/koog/tree/develop/integration-tests/src/jvmMain/kotlin/ai/koog/integration/tests"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#0366d6,color:#000;
    classDef extension fill:#D7E8D4,stroke:#22863a,color:#000;
    classDef feature fill:#E6F0F3,stroke:#0052CC,color:#000;
    classDef embeddings fill:#FFF5B1,stroke:#DBAB09,color:#000;
    classDef prompt fill:#FDE8E3,stroke:#D73A49,color:#000;
    classDef executor fill:#E1E4E8,stroke:#6a737d,color:#000;
    classDef client fill:#FEE2C0,stroke:#A85C00,color:#000;
    classDef cache fill:#F0F0F0,stroke:#6a737d,color:#000;
    classDef external fill:#FFDDDD,stroke:#B31D28,color:#000;
    classDef examples fill:#EADCF8,stroke:#6f42c1,color:#000;
```
