Get rid of required `finishTool` and support tools as functions in `subgraphWithTask`, deprecate `ToolArgs` and `ToolResult`, auto-generate `ToolDescriptor` #791

Ololoshechkin · 2025-09-12T14:52:16Z

Automatic Tool Descriptor Generation

Tool descriptors no longer need to be written manually — they are generated automatically.
Tool parameters must be annotated with @LLMDescription to provide descriptions.

subgraphWithTask ыimplification (no longer requires finishTool, deduces all information by output type automatically)
Serialization Improvements

ToolArgs and ToolResult are no longer needed — everything is handled via serialization.
ToolResult is now always Serializable to Json
For rare cases where JSON is not applicable:
- Inherit from ToolResult.TextSerializable and implement fun textForLLM().
- Specify resultSerializer = ToolResultUtils.toTextSerializer().
- The LLM will then receive the output from textForLLM().

Agent.asTool() no longer requires a ToolDescriptor.
(Requires only toolDescription: String, and only if the agent’s input type is a primitive (e.g., String). If the input type is not primitive, descriptions are taken from @LLMDescription.)

Type of the changes

New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Tests improvement
Refactoring

Checklist

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

github-actions · 2025-09-17T01:03:59Z

Qodana for JVM

848 new problems were found

Inspection name	Severity	Problems
`Check Kotlin and Java source code coverage`	🔶 Warning	829
`Vulnerable imported dependency`	🔶 Warning	17
`Unused import directive`	🔶 Warning	1
`Missing KDoc for public API declaration`	🔶 Warning	1

@@ Code coverage @@
+ 69% total lines covered
12404 lines analyzed, 8647 lines covered
# Calculated according to the filters of your coverage tool

☁️ View the detailed Qodana report

Contact Qodana team

Contact us at qodana-support@jetbrains.com

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

tiginamaria

Looks much nicer than it was!

It seems like not you can not provide a argument description for the primitive typed argument, or I miss something?

internal class PrimitiveTool(name: String) : Tool<Int, String>() {
    override val name = "primitive_tool"

    override val argsSerializer = Int.serializer()
    override val resultSerializer = String.serializer()
    
    override val toolDescription: String = "First tool description"

    override suspend fun execute(args: Int): String = "Do nothing $args"
}

Also, I'd add more tests for such cases (for example how List of not primitive type will work and other unusual cases)

sdubov · 2025-09-23T09:29:11Z

I like the simplified API. I have some small comments related to this change. Overall looks good for me.

agents/agents-core/src/commonTest/kotlin/ai/koog/agents/core/feature/TestFeature.kt

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/Tool.kt

...-handler/src/jvmTest/kotlin/ai/koog/agents/features/eventHandler/feature/EventHandlerTest.kt

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/SimpleTool.kt

agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/tool/file/EditFileTool.kt

sdubov · 2025-09-23T09:34:19Z

It seems like not you can not provide a argument description for the primitive typed argument, or I miss something?
internal class PrimitiveTool(name: String) : Tool<Int, String>() {
    override val name = "primitive_tool"

    override val argsSerializer = Int.serializer()
    override val resultSerializer = String.serializer()
    
    override val toolDescription: String = "First tool description"

    override suspend fun execute(args: Int): String = "Do nothing $args"
}
Also, I'd add more tests for such cases (for example how List of not primitive type will work and other unusual cases)

If I correctly understand the new API, you need to do it through:

internal data class Args(
        @property:LLMDescription("Number to convert to string")
        val number: Int
)

It would be nice if we can use a primitive types though.

tiginamaria

I think not having args description for primitive types is not a blocker at all:

You can just describe the argument in tool description string
You can override tool description and define the proper schema
You can always use data class Args(value: Int) with @property:LLMDescription
Case with primitive input + tool as a class definition is super rear (only multiplatform I guess, but maybe it's better to work on cross-platform annotations or some other ways of supporting tools as function there)

Refactor `SerialToToolDescription` by extracting `parameterDescriptors` helper method to improve code reuse and clarity. Add comprehensive tests for `SerialDescriptor` to `ToolDescription` mapping and improve utility method structure. - Added unit tests in `LLMDescriptionUsageTest` and `SerialToToolDescriptionTest` to validate `SerialDescriptor` to `ToolDescriptor` conversions, covering edge cases and annotations. - Extracted private helper `description()` to streamline annotation description retrieval. - Improved parameter handling by introducing local variables for clarity and consistency. Refactor SimpleTool.kt to work with String instead of ToolResult.Text KtLint: Fix import order Remove unrelated change Introduce KMP support for deriving ToolDescription based on SerialDescriptor. Deprecate `ToolResult` and refactor tools to use KotlinX Serialization for results. Deprecate ToolArgs.kt, and remove usage.

…as functions

…alizable abstract class for custom serialization of tool results as text/markdown

…ations (#889)  ## Motivation and Context  As a follow-up to our last week discussion, it's good to test different input/output combinations in tool descriptors after the merge of #791. ## Breaking Changes  None. --- #### Type of the changes - [ ] New feature (non-breaking change which adds functionality) - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [x] Tests improvement - [ ] Refactoring #### Checklist - [x] The pull request has a description of the proposed change - [x] I read the [Contributing Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md) before opening the pull request - [x] The pull request uses **`develop`** as the base branch - [x] Tests for the changes have been added - [x] All new and existing tests passed ##### Additional steps for pull requests adding a new feature - [x] An issue describing the proposed change exists - [x] The pull request includes a link to the issue - [x] The change was discussed and approved in the issue - [ ] Docs have been added / updated

@tool

Fixes @tool("customName") not working after JetBrains#791.

…ations (#889)  ## Motivation and Context  As a follow-up to our last week discussion, it's good to test different input/output combinations in tool descriptors after the merge of #791. ## Breaking Changes  None. --- #### Type of the changes - [ ] New feature (non-breaking change which adds functionality) - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [x] Tests improvement - [ ] Refactoring #### Checklist - [x] The pull request has a description of the proposed change - [x] I read the [Contributing Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md) before opening the pull request - [x] The pull request uses **`develop`** as the base branch - [x] Tests for the changes have been added - [x] All new and existing tests passed ##### Additional steps for pull requests adding a new feature - [x] An issue describing the proposed change exists - [x] The pull request includes a link to the issue - [x] The change was discussed and approved in the issue - [ ] Docs have been added / updated (cherry picked from commit 58ba445)

@tool

Fixes @tool("customName") not working after JetBrains#791.

@tool

Fixes @tool("customName") not working after JetBrains#791.

…ubgraphWithTask`, deprecate `ToolArgs` and `ToolResult`, make `ToolDescriptor` auto-generated for class-based tools (JetBrains#791) 1. Automatic Tool Descriptor Generation - Tool descriptors no longer need to be written manually — they are generated automatically. - Tool parameters must be annotated with @LLMDescription to provide descriptions. 2. subgraphWithTask ыimplification (no longer requires finishTool, deduces all information by output type automatically) 3. Serialization Improvements - ToolArgs and ToolResult are no longer needed — everything is handled via serialization. - ToolResult is now always Serializable to Json - For rare cases where JSON is not applicable: - Inherit from ToolResult.TextSerializable and implement fun textForLLM(). - Specify resultSerializer = ToolResultUtils.toTextSerializer(). - The LLM will then receive the output from textForLLM(). 4. Agent.asTool() no longer requires a ToolDescriptor. (Requires only toolDescription: String, and only if the agent’s input type is a primitive (e.g., String). If the input type is not primitive, descriptions are taken from @LLMDescription.) --- #### Type of the changes - [x] New feature (non-breaking change which adds functionality) - [ ] Bug fix (non-breaking change which fixes an issue) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [x] Tests improvement - [x] Refactoring #### Checklist - [x] The pull request has a description of the proposed change - [x] I read the [Contributing Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md) before opening the pull request - [x] The pull request uses **`develop`** as the base branch - [x] Tests for the changes have been added - [x] 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 - [x] Docs have been added / updated --------- Co-authored-by: Simon Vergauwen <nomisRev@users.noreply.github.com> Co-authored-by: Anastasiia.Zarechneva <Anastasiia.Zarechneva@jetbrains.com>

…ations (JetBrains#889)  ## Motivation and Context  As a follow-up to our last week discussion, it's good to test different input/output combinations in tool descriptors after the merge of JetBrains#791. ## Breaking Changes  None. --- #### Type of the changes - [ ] New feature (non-breaking change which adds functionality) - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [x] Tests improvement - [ ] Refactoring #### Checklist - [x] The pull request has a description of the proposed change - [x] I read the [Contributing Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md) before opening the pull request - [x] The pull request uses **`develop`** as the base branch - [x] Tests for the changes have been added - [x] All new and existing tests passed ##### Additional steps for pull requests adding a new feature - [x] An issue describing the proposed change exists - [x] The pull request includes a link to the issue - [x] The change was discussed and approved in the issue - [ ] Docs have been added / updated (cherry picked from commit 58ba445)

Ololoshechkin requested review from Rizzen, nomisRev and tiginamaria September 12, 2025 14:52

Ololoshechkin force-pushed the vbr/subgraph-with-task-fix branch 2 times, most recently from b8968c9 to c10abf2 Compare September 15, 2025 14:22

aozherelyeva force-pushed the vbr/subgraph-with-task-fix branch from ed46f91 to a03f1b7 Compare September 16, 2025 13:16

tiginamaria requested changes Sep 22, 2025

View reviewed changes

sdubov approved these changes Sep 23, 2025

View reviewed changes

tiginamaria self-requested a review September 23, 2025 11:52

tiginamaria approved these changes Sep 23, 2025

View reviewed changes

Ololoshechkin force-pushed the vbr/subgraph-with-task-fix branch from f0503d7 to 803171e Compare September 26, 2025 02:05

nomisRev and others added 15 commits September 26, 2025 15:15

fixup! Add missing Kdocs

65b7fbc

Get rid of required finishTool in subgraphWithTask and support tools …

3862530

…as functions

fixup! Fix rebase issues

8fac2ba

Refactor all usages and examples

086da99

fixup! fix CE

8ffeec4

fixup! fix CE

9e3c25d

fixup! fix nested class property LLM descriptions

1d40c3f

Rewrite trip-planning example with new simplified subgraphWithTask API

90ffce5

Add tests for more complex tool descriptor generation, fix bugs

2616875

fix Klint

3120cb3

Refactor EditFileTool, ListDirectoryTool, etc. and introduce TextSeri…

cda7fc1

…alizable abstract class for custom serialization of tool results as text/markdown

Rewrite all tools and examples with the new API

e0f7a80

fixup! Fix broken Banking example

474bc2a

Fix tests

264eaec

Ololoshechkin and others added 15 commits September 26, 2025 15:15

Fix doc knit

ad2fe64

Fix ModelCapabilitiesIntegrationTest

1b82d85

fix tests and lint

aab2b49

Add missing feature installations to Ktor plugin

8db622f

Add missing feature installations to Ktor plugin

11e6c9d

Fix bug with Ktor Koog feature install self-recursion

c69f6a1

Fix bug with primitives in subgraph

79b04f5

Fix rebase and review comments

16f561e

fix

f9e31cc

fix

31acd81

fix linter

1dcfc8c

fix other things

c3bb59c

fix other things

4a8101d

fix other things

b0becb3

fix CE

748d07f

Ololoshechkin force-pushed the vbr/subgraph-with-task-fix branch from 3e21c19 to 748d07f Compare September 26, 2025 13:19

Ololoshechkin added 3 commits September 26, 2025 15:38

fix ktlint

14fe454

fix ktlint and CE

463dcd6

fix ktlint !!!!!!!!!!! ___ANGRY___ ! VERY ANGRY!

147243e

Ololoshechkin merged commit c433b8e into develop Sep 26, 2025
15 checks passed

Ololoshechkin deleted the vbr/subgraph-with-task-fix branch September 26, 2025 14:47

aozherelyeva mentioned this pull request Sep 30, 2025

Add integration tests for executing tools with primitive types combinations #889

Merged

15 tasks

nicolasf added a commit to nicolasf/koog that referenced this pull request Oct 1, 2025

fix: ToolFromCallable with custom name

f667610

Fixes @tool("customName") not working after JetBrains#791.

nicolasf mentioned this pull request Oct 1, 2025

fix: ToolFromCallable with custom name #900

Open

11 tasks

nicolasf added a commit to nicolasf/koog that referenced this pull request Oct 3, 2025

fix: ToolFromCallable with custom name

d9376ae

Fixes @tool("customName") not working after JetBrains#791.

nicolasf added a commit to nicolasf/koog that referenced this pull request Oct 3, 2025

fix: ToolFromCallable with custom name

74db876

Fixes @tool("customName") not working after JetBrains#791.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Get rid of required `finishTool` and support tools as functions in `subgraphWithTask`, deprecate `ToolArgs` and `ToolResult`, auto-generate `ToolDescriptor` #791

Get rid of required `finishTool` and support tools as functions in `subgraphWithTask`, deprecate `ToolArgs` and `ToolResult`, auto-generate `ToolDescriptor` #791

Uh oh!

Ololoshechkin commented Sep 12, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Sep 17, 2025 •

edited

Loading

Uh oh!

tiginamaria left a comment •

edited

Loading

Uh oh!

sdubov commented Sep 23, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sdubov commented Sep 23, 2025 •

edited

Loading

Uh oh!

tiginamaria left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Get rid of required finishTool and support tools as functions in subgraphWithTask, deprecate ToolArgs and ToolResult, auto-generate ToolDescriptor #791

Get rid of required finishTool and support tools as functions in subgraphWithTask, deprecate ToolArgs and ToolResult, auto-generate ToolDescriptor #791

Uh oh!

Conversation

Ololoshechkin commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of the changes

Checklist

Additional steps for pull requests adding a new feature

Uh oh!

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

Uh oh!

Qodana for JVM

Uh oh!

tiginamaria left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sdubov commented Sep 23, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sdubov commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tiginamaria left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Get rid of required `finishTool` and support tools as functions in `subgraphWithTask`, deprecate `ToolArgs` and `ToolResult`, auto-generate `ToolDescriptor` #791

Get rid of required `finishTool` and support tools as functions in `subgraphWithTask`, deprecate `ToolArgs` and `ToolResult`, auto-generate `ToolDescriptor` #791

Ololoshechkin commented Sep 12, 2025 •

edited

Loading

github-actions bot commented Sep 17, 2025 •

edited

Loading

tiginamaria left a comment •

edited

Loading

sdubov commented Sep 23, 2025 •

edited

Loading