Add Ktor integration via `Koog` ktor plugin #422

Ololoshechkin · 2025-07-11T11:34:29Z

Thank you for opening a pull request! Please add a brief description of the proposed change here.

Also, please tick the appropriate points in the checklist below.

Type of the change

New feature
Bug fix
Documentation fix
Tests improvement

Checklist for all pull requests

The pull request has a description of the proposed change
I read the Contributing Guidelines before opening the pull request
The pull request uses develop as the base branch
Tests for the changes have been added
All new and existing tests passed

Additional steps for pull requests adding a new feature

An issue describing the proposed change exists
The pull request includes a link to the issue
The change was discussed and approved in the issue
Docs have been added / updated

Ololoshechkin · 2025-07-11T11:44:58Z

Note: this is a draft proposal written in examples. Design should be improved and Ktor plugin should be moved as a separate module available in public API if we decide it's worth doing.

cc: @e5l WDYT? Can we add this into Ktor marketplace at some point?

Ololoshechkin · 2025-07-13T02:13:40Z

@nomisRev , I've added configuration from yaml/conf file + overriding from DSL.

Also created a separate module with the actual plugin.

github-actions · 2025-07-13T02:32:51Z

Qodana for JVM

369 new problems were found

Inspection name	Severity	Problems
`Check Kotlin and Java source code coverage`	🔶 Warning	352
`Unused import directive`	🔶 Warning	13
`Vulnerable imported dependency`	🔶 Warning	4

@@ Code coverage @@
+ 67% total lines covered
8344 lines analyzed, 5661 lines covered
# Calculated according to the filters of your coverage tool

☁️ View the detailed Qodana report

Contact Qodana team

Contact us at [email protected]

Or via our issue tracker: https://jb.gg/qodana-issue
Or share your feedback: https://jb.gg/qodana-discussions

kpavlov

Thank you, @Ololoshechkin — these are some great features. Would you be open to splitting the Ktor and Spring Boot integrations into separate PRs, since they represent distinct functionality? Also, do you think it might make sense to refactor the configuration class structure to improve extensibility, and possibly delegate model name mappings to the respective LLM providers?

koog-ktor-plugin/src/commonMain/kotlin/ai/koog/ktor/utils/config/EnvironmentConfigLoader.kt

koog-ktor-plugin/src/commonMain/kotlin/ai/koog/ktor/utils/config/ModelsConfigParser.kt

kpavlov · 2025-07-13T06:25:38Z

koog-ktor-plugin/src/commonMain/kotlin/ai/koog/ktor/utils/config/ModelsConfigParser.kt

+    }
+}
+
+private val OPENAI_MODELS_MAP = mapOf(


This and others: Let's move it to OpenAI module. Such mappings should live in the provider modules and have no relation to KTor

Yes, this definitely needs to be moved but it feels quite impactful to the core core types so I propose to review the code and propose a solution to move this to core in a separate PR to not complicate things further in this PR.

koog-ktor-plugin/src/commonTest/kotlin/ai/koog/ktor/ConfigurationLoadingTest.kt

koog-ktor-plugin/src/commonTest/kotlin/ai/koog/ktor/ModelIdentifierParsingTest.kt

koog-spring-boot-starter/src/main/kotlin/ai/koog/spring/KoogProperties.kt

Ololoshechkin · 2025-07-13T09:48:42Z

@kpavlov Hi! Thanks!
Speing Boot was already added -- I only generated KDocs with AI Assistant as they were missing :)

I only introduced Ktor.

But actually you are right -- I should open a PR with kdocs separately and include in the 0.3.0 release

kpavlov · 2025-07-13T13:05:27Z

KDoc is not critical, the config and test structure is more important. Separate PR to refactor this is ok, if you promise to refactor ;)
Would it make sense to include Ktor support in 0.4 and have some time to polish and test it up and down?

Ololoshechkin · 2025-07-13T17:28:29Z

@kpavlov yes, I think it can go to 0.4.0, definitely not 0.3.0 :)

So this PR is rather a draft that someone would finish while I'm on vacation))

e5l · 2025-07-14T06:55:25Z

@Ololoshechkin, sure. It can be done through the https://github.com/ktorio/ktor-plugin-registry without release

e5l

lgtm

examples/build.gradle.kts

nomisRev

Awesome work 👏 👏 👏
I have some critical concerns about some of the API, but I think we can solve this in a subsequent PR as well so I'm not going to block this PR contains the important foundation for the Ktor Koog plugin!

Please let me know in my comments what you think 🙏

examples/src/main/kotlin/ai/koog/agents/example/ktor/KtorIntegrationExample.kt

koog-ktor-plugin/src/commonMain/kotlin/ai/koog/ktor/KoogKtorServerPlugin.kt

nomisRev · 2025-07-14T08:52:06Z

@Ololoshechkin I can take over if you want 👍

ptitjes · 2025-07-14T09:03:07Z

@Ololoshechkin @nomisRev can we directly put this in an integrations/integrations-ktor/integrations-ktor-plugin?

There is already the Spring integration that is standalone in the the root of the project. I also want to introduce a Redis VectorStore, which will require to move up the current Redis PromptCache in order to introduce an integrations/integrations-redis/integrations-redis-shared module to share the configuration and connection logic.

I am not sure if integrations is the right word, but I think it is rather necessary to regroup the integrations and not accumulate modules at the root of the project. WDYT?

nomisRev · 2025-07-14T11:15:45Z

I am not sure if integrations is the right word, but I think it is rather necessary to regroup the integrations and not accumulate modules at the root of the project. WDYT?

Great point! Personally I have no strong opinion on how to organise this. The projects I'm invoked with follow similar strategies but this project seems to have different needs. "integrations/integrations-redis/integrations-redis-shared" could be a good strategy, as in the future we might want to split up the Ktor support into separate modules as well.

koog-ktor-plugin/src/jvmMain/kotlin/ai/koog/ktor/KoogKtorServerPluginJvm.kt

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

…or LLM configs

…e-using Ktor low-level machinery inside the Koog plugin codebase. - Bump to Ktor 3.2.0 - Rewrite llm, and respond overloads with Koog DSLs.

…s accordingly.

…build files, tests, and code for consistency. Rewrite AI agent functions with improved parameterization and modularity.

…Ktor library definitions in `libs.versions.toml`.

…pe to run the configuration on until we have suspend plugins in Ktor 4.0

…cope to run the configuration on until we have suspend plugins in Ktor 4.0 - Protect toolRegistry with Mutex

koog-ktor/src/jvmMain/kotlin/ai/koog/ktor/KoogKtorServerPluginJvm.kt

devcrocod

LGTM!
I have a few questions and comments, please take a look

settings.gradle.kts

build.gradle.kts

settings.gradle.kts

koog-ktor/src/commonMain/kotlin/ai/koog/ktor/utils/EnvConfigLoader.kt

koog-ktor/src/commonMain/kotlin/ai/koog/ktor/utils/LLMModelParser.kt

koog-ktor/src/jvmMain/kotlin/ai/koog/ktor/KoogKtorServerPluginJvm.kt

kotlin-js-store/yarn.lock

...client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/anthropic/AnthropicLLMClient.kt

…d scripts accordingly." This reverts commit b8d3ebc. # Conflicts: # settings.gradle.kts

Revert Ktor Version Catalog Android Example

…Scope` import.

…via fallback to client settings.

nomisRev · 2025-07-29T13:40:42Z

@devcrocod I removed all duplicated default values from the Ktor plugin, and delegate to the defaults from core.

I propose to remove the default model, and explicitly require the model when creating an agent. This additional argument will result in a nicer, and type safer API. This would also remove the need for (String) -> LLMModel, and then we can re-evaluate later if we really need it.

WDYT?

…configuration structure; remove `defaultLLM` and `agentTools` for better encapsulation.

…factor `aiAgent` to support `suspend`, and encapsulate `scope` in `AgentConfig` for safer concurrency.

…ngs, and ensure explicit `model` parameter usage in AI agent functions.

devcrocod · 2025-07-30T10:42:54Z

examples/src/main/resources/application.yaml

+  anthropic.apikey: "your-anthropic-api-key"
+  google.apikey: "your-google-api-key"
+  openrouter.apikey: "your-openrouter-api-key"
+  ollama.enable: true


Maybe we should require a url for Ollama?

It follows the same behavior as the Ollama Koog integration which is the default URL, or ollama.baseUrl = "...", or ollama { baseUrl = "..." } in code.

devcrocod · 2025-07-30T10:51:17Z

@nomisRev

I propose to remove the default model, and explicitly require the model when creating an agent. This additional argument will result in a nicer, and type safer API.

In my opinion, that’s a reasonable solution

Ololoshechkin requested review from e5l and Rizzen July 11, 2025 11:34

Ololoshechkin changed the title ~~[Draft, Proposal] Ktor integration example via Ktor plugins (proposal)~~ [Draft, Proposal] Ktor integration via Ktor plugins (proposal) Jul 12, 2025

Ololoshechkin force-pushed the vbr/ktor-integration branch from 6de7da0 to a08ba11 Compare July 13, 2025 02:11

Ololoshechkin changed the title ~~[Draft, Proposal] Ktor integration via Ktor plugins (proposal)~~ [Proposal] Add Ktor integration via Ktor plugin Jul 13, 2025

Ololoshechkin requested a review from nomisRev July 13, 2025 02:12

Ololoshechkin changed the title ~~[Proposal] Add Ktor integration via Ktor plugin~~ [Proposal] Add Ktor integration via Koog ktor plugin Jul 13, 2025

Ololoshechkin requested a review from devcrocod July 13, 2025 03:36

kpavlov reviewed Jul 13, 2025

View reviewed changes

e5l approved these changes Jul 14, 2025

View reviewed changes

examples/build.gradle.kts Outdated Show resolved Hide resolved

nomisRev reviewed Jul 14, 2025

View reviewed changes

Ololoshechkin assigned nomisRev Jul 16, 2025

harrytmthy reviewed Jul 20, 2025

View reviewed changes

koog-ktor-plugin/src/jvmMain/kotlin/ai/koog/ktor/KoogKtorServerPluginJvm.kt Outdated Show resolved Hide resolved

Ololoshechkin changed the title ~~[Proposal] Add Ktor integration via Koog ktor plugin~~ Add Ktor integration via Koog ktor plugin Jul 20, 2025

ariawisp mentioned this pull request Jul 25, 2025

Redis Persistence Provider for Agent Checkpoints #480

Open

13 tasks

ariawisp added a commit to ariawisp/koog that referenced this pull request Jul 26, 2025

Add Ktor integration via Koog ktor plugin (JetBrains#422)

64618d6

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

Ololoshechkin and others added 4 commits July 27, 2025 14:13

Draft Ktor integration proposal in examples

61c2663

Create separate module with Ktor plugin and support YAML properties f…

216bb59

…or LLM configs

Add tests for environment config loading and model id parsing

bfca0d1

- Rewrite Koog plugin to class-based plugin which allows for easier r…

9121004

…e-using Ktor low-level machinery inside the Koog plugin codebase. - Bump to Ktor 3.2.0 - Rewrite llm, and respond overloads with Koog DSLs.

nomisRev added 2 commits July 27, 2025 14:14

Adopt version catalog for Ktor dependencies and refactor build script…

b8d3ebc

…s accordingly.

Rename koog-ktor-plugin module to koog-ktor and refactor related …

2282684

…build files, tests, and code for consistency. Rewrite AI agent functions with improved parameterization and modularity.

nomisRev force-pushed the vbr/ktor-integration branch from a8fe1a0 to 2282684 Compare July 27, 2025 12:15

nomisRev added 3 commits July 27, 2025 14:28

Adopt Ktor version catalog in settings.gradle.kts, remove explicit …

5ce70c2

…Ktor library definitions in `libs.versions.toml`.

Remove suspend from mcp configuration, and create a temporary sco…

1150765

…pe to run the configuration on until we have suspend plugins in Ktor 4.0

- Remove suspend from mcp configuration, and create a temporary s…

51e83c2

…cope to run the configuration on until we have suspend plugins in Ktor 4.0 - Protect toolRegistry with Mutex

ariawisp mentioned this pull request Jul 29, 2025

Add AgentPool: High-performance agent reuse system #495

Closed

13 tasks

Mr3zee reviewed Jul 29, 2025

View reviewed changes

koog-ktor/src/jvmMain/kotlin/ai/koog/ktor/KoogKtorServerPluginJvm.kt Show resolved Hide resolved

devcrocod reviewed Jul 29, 2025

View reviewed changes

nomisRev added 4 commits July 29, 2025 15:17

Revert "Adopt version catalog for Ktor dependencies and refactor buil…

ec5dd3d

…d scripts accordingly." This reverts commit b8d3ebc. # Conflicts: # settings.gradle.kts

Remove yarn.lock from the kotlin-js-store directory.

81bd62f

Revert Ktor Version Catalog Android Example

Rename MCPToolsConfig to McpToolsConfig and remove unused `Global…

bc1821f

…Scope` import.

Make client configuration properties nullable and set default values …

7c727ab

…via fallback to client settings.

nomisRev added 3 commits July 29, 2025 20:45

Refactor AI agent functions to include model parameter and improve …

8928514

…configuration structure; remove `defaultLLM` and `agentTools` for better encapsulation.

Introduce CoroutineScope for improved configuration flexibility, re…

ff1cd62

…factor `aiAgent` to support `suspend`, and encapsulate `scope` in `AgentConfig` for safer concurrency.

Simplify YAML configuration structure, remove redundant timeout setti…

edd7a29

…ngs, and ensure explicit `model` parameter usage in AI agent functions.

devcrocod reviewed Jul 30, 2025

View reviewed changes

devcrocod approved these changes Jul 30, 2025

View reviewed changes

nomisRev merged commit 22c37c4 into develop Jul 30, 2025
7 checks passed

nomisRev deleted the vbr/ktor-integration branch July 30, 2025 11:26

Add Ktor integration via Koog ktor plugin #422

Add Ktor integration via Koog ktor plugin #422

Uh oh!

Conversation

Ololoshechkin commented Jul 11, 2025

Type of the change

Checklist for all pull requests

Additional steps for pull requests adding a new feature

Uh oh!

Ololoshechkin commented Jul 11, 2025

Uh oh!

Ololoshechkin commented Jul 13, 2025

Uh oh!

github-actions bot commented Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Qodana for JVM

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kpavlov Jul 13, 2025

Choose a reason for hiding this comment

Uh oh!

nomisRev Jul 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ololoshechkin commented Jul 13, 2025

Uh oh!

kpavlov commented Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ololoshechkin commented Jul 13, 2025

Uh oh!

e5l commented Jul 14, 2025

Uh oh!

e5l left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nomisRev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nomisRev commented Jul 14, 2025

Uh oh!

ptitjes commented Jul 14, 2025

Uh oh!

nomisRev commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nomisRev commented Jul 29, 2025

Uh oh!

devcrocod Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

nomisRev Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

Add Ktor integration via `Koog` ktor plugin #422

Add Ktor integration via `Koog` ktor plugin #422

github-actions bot commented Jul 13, 2025 •

edited

Loading

kpavlov commented Jul 13, 2025 •

edited

Loading

nomisRev commented Jul 14, 2025 •

edited

Loading