feat(agents): Introduce wrapper for cli agents by antoniibelyshev · Pull Request #1413 · JetBrains/koog

antoniibelyshev · 2026-01-26T15:29:02Z

feat(CliAIAgent):
introduce CliAIAgent which calls another cli agent under the hood: e.g. claude, codex, etc.
CliAIAgent is an instance of AIAgent, and can also be used as a node in a graph, e.g. val claudeNode by ClaudeCodeAgent(...).asNode()

Motivation and Context

Breaking Changes

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
CI/CD changes
Dependencies update

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

Ololoshechkin

Please, add more tests on structured output, and see my other comments as well.

Additionally, please consider adding Java-friendly builder AIAgent.builder().agentConfig(...).cli(AIAgentCliStrategy. ...) ...
(add cli or cliStrategy in addition to .functionalStrategy, .goapStrategy and .graphStrategy).

Ololoshechkin · 2026-02-25T21:37:50Z

AIAgentCliStrategy.claude<String, String>(
            "",
            transport = DockerCliTransport("image"),
            structure = JsonStructure.create<String>()
)

-- this part requires both <Input, Output> parameters as well as structure to define the Output.
Let's maybe make it consistent so that Input is also defined not via generic params but via some argument (KType or Class, etc.)

Also add Java test and check how it looks there :)

Ololoshechkin

also maybe we'd need to run integration tests for:

all types of CLI agents (codex, claude, ?)
all types of transport (docker, process)
all OS: mac, windows, linux

cc @aozherelyeva can you help please 🙏

sdubov

@antoniibelyshev, thank you for the fixed comments! I've added several more notes related to the code. Could you please check?

sdubov

@antoniibelyshev , I have added several more question for the review. Could you please take a look.

The biggest concern from my side are:

DummyPromptExecutor. It is quite unclear how will it work when somebody call the prompt executor. Maybe it worth adding a stubs that will delegate execution to the CLI agent in future and just blank for now

I will give an approve from my side to not block the merging, but I think it would be nice if someone from the team look on these changes as well. cc @EugeneTheDev, @Ololoshechkin

Could you please also check the documentation and Module.md file. It might worth add some examples in the md file.

sdubov · 2026-05-05T08:47:19Z

+            prompt = agentConfig.prompt,
+            model = agentConfig.model,
+            responseProcessor = agentConfig.responseProcessor,
+            promptExecutor = DummyPromptExecutor,


Could you please clarify this logic for me? Am I right that you replace the prompt executor here with a dummy instance and delegate the execution to the CLI process. If this is correct, I would like to clarify several questions:

Do you expect to change the behaviour in future for better integration and interactions? For example, if I want to send some requests from Koog side inside a running CLI agent or respond to some questions received from CLI Agent?

How would that work with features? Let's say I add a feature that use prompt executor. Will those calls all throw?

Could you please add KDoc to the DummyPromptExecutor with some details if this is behaviour is not documented anywhere?

…h raw cli and with cli in docker

… out of the box

…ispatcher

EugeneTheDev

Please extract cli package from agents-core intro a separate module. We should avoid putting non-core stuff in core modules as much as possible

EugeneTheDev · 2026-03-31T14:27:39Z

+FROM node:20-slim
+
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN npm install -g @openai/codex @anthropic-ai/claude-code && npm cache clean --force


Please pin the exact version/hash when doing npm install, to prevent supply chain vulenrabilities

EugeneTheDev · 2026-03-31T14:31:19Z

+          node-version: 20
+
+      - name: Install CLI agents globally
+        run: npm install -g @openai/codex @anthropic-ai/claude-code


Why do you run npm install here, if the Dockerfile already has it? Seems like it's not needed here. And again, please always pin dependencies to exact versions/hashes

EugeneTheDev

Please also consider organizing agents cli package a bit. Currently, it has a flat structure, but I guess some of these classes can be grouped into several packages, for better readbility

EugeneTheDev · 2026-05-09T14:23:06Z

+/**
+ * Base class for cli-agent-related exceptions.
+ */
+public open class CliException(message: String, cause: Throwable? = null) : RuntimeException(message, cause)


Why is it a RuntimeException and not a regular Exception?

EugeneTheDev · 2026-05-09T14:26:18Z

+/**
+ * Interface for cli transport implementations.
+ */
+public expect interface CliTransport {


As far as I understand the use-case, this interface doesn't have to be expect/actual. You don't actually use it, the interface on both platforms looks the same. It's the platform-specific implementations that are located in platform-specific source sets anyway and contain platform-specific code. So you can make this one a regular interface

The reason I made it expect/actual is that I wanted to have CliTransport.default(), CliTransport.withDocker, etc., but these are only available on jvm for now. Does this make sense or can I do it better?

EugeneTheDev · 2026-05-09T14:30:30Z

+    /**
+     * Converts a JSON primitive to a string
+     */
+    public val JsonElement.stringVal: String?


Putting extension functions/propeties inside objects/classes is usually a bad idea, if they're used outside of that specific scope, because it will be harder to discover and use them. Consider moving these to the top-level. Also, are these internal helpers or an actual public API? If it's the former, consider adding internal api annotation

antoniibelyshev force-pushed the belyshev/cli-agents branch 4 times, most recently from 44e0012 to 3a801b4 Compare January 27, 2026 09:48

antoniibelyshev changed the title ~~WIP: write cli wrappers~~ Wrappers for cli agents Jan 28, 2026

antoniibelyshev changed the title ~~Wrappers for cli agents~~ Introduce wrapper for cli agents Jan 29, 2026

antoniibelyshev force-pushed the belyshev/cli-agents branch from 8504b5b to a01e00e Compare February 16, 2026 13:44

antoniibelyshev changed the title ~~Introduce wrapper for cli agents~~ feat(agents): Introduce wrapper for cli agents Feb 16, 2026

antoniibelyshev force-pushed the belyshev/cli-agents branch from a01e00e to 4e5abf7 Compare February 16, 2026 13:50

antoniibelyshev requested review from Ololoshechkin and sdubov February 17, 2026 12:01

Ololoshechkin requested changes Feb 25, 2026

View reviewed changes

Comment thread agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/cli/AIAgentCliStrategy.kt Outdated

Ololoshechkin requested changes Feb 25, 2026

View reviewed changes

Comment thread cli-transport/src/jvmMain/kotlin/ai/koog/cli/transport/DockerCliTransport.kt Outdated

Ololoshechkin requested changes Feb 25, 2026

View reviewed changes

Ololoshechkin requested review from EugeneTheDev and aozherelyeva February 25, 2026 22:04

sdubov reviewed Feb 27, 2026

View reviewed changes

antoniibelyshev force-pushed the belyshev/cli-agents branch 8 times, most recently from 6562dad to 1f00287 Compare March 2, 2026 22:25

antoniibelyshev force-pushed the belyshev/cli-agents branch 3 times, most recently from d4b0699 to d49ceb0 Compare March 31, 2026 08:26

antoniibelyshev force-pushed the belyshev/cli-agents branch from 139deea to 492c841 Compare April 14, 2026 16:36

antoniibelyshev requested a review from sdubov April 15, 2026 12:09

sdubov requested changes Apr 20, 2026

View reviewed changes

antoniibelyshev force-pushed the belyshev/cli-agents branch from 8942b99 to 521ad32 Compare April 27, 2026 13:21

antoniibelyshev requested a review from sdubov April 28, 2026 10:44

sdubov requested changes May 5, 2026

View reviewed changes

sdubov self-requested a review May 5, 2026 09:28

sdubov approved these changes May 5, 2026

View reviewed changes

antoniibelyshev added 19 commits May 8, 2026 18:33

introduce cli transport and its implementation via ProcessBuilder wit…

dfcd0c1

…h raw cli and with cli in docker

introduce CliAIAgent and CliAIAgentStrategy, provide codex and claude…

44cadb2

… out of the box

add builder for the cliaiagent

3ed7082

add integration tests for CliAIAgent

c254b6b

introduce agent.asNode()

50fb4fa

remove code duplication in environment creation

f06f09e

add cli agent response on failure + multiple fixes

401b258

multiple fixes

1e5ce98

add missing kdocs

e164a1d

fix ktlint

0c134b9

fix tests

e72626a

fix ktlint

f6fd091

multiple small fixes

d8447c2

add timeout to the availability check and run it on a SuitableForIO d…

8283799

…ispatcher

fix ktlint

8e7a955

add missing binaryPath and name to the claude cli builders

91cb803

add cmd /c to docker --version when checking docker availability on win

1f030bd

update default availability timeout to 1 minute

a42350f

small fixes

cacd812

antoniibelyshev force-pushed the belyshev/cli-agents branch from 521ad32 to cacd812 Compare May 8, 2026 16:38

EugeneTheDev requested changes May 9, 2026

View reviewed changes

Conversation

antoniibelyshev commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Breaking Changes

Type of the changes

Checklist

Additional steps for pull requests adding a new feature

Uh oh!

Ololoshechkin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ololoshechkin commented Feb 25, 2026

Uh oh!

Ololoshechkin 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!

Uh oh!

Uh oh!

Uh oh!

sdubov 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!

sdubov 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sdubov May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

EugeneTheDev left a comment

Choose a reason for hiding this comment

Uh oh!

EugeneTheDev Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

EugeneTheDev Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

EugeneTheDev left a comment

Choose a reason for hiding this comment

Uh oh!

EugeneTheDev May 9, 2026

Choose a reason for hiding this comment

Uh oh!

antoniibelyshev commented Jan 26, 2026 •

edited

Loading

sdubov left a comment •

edited

Loading