docs: add custom feature creation documentation by marinkovicmarko · Pull Request #1295 · JetBrains/koog

marinkovicmarko · 2025-12-22T10:31:54Z

Add documentation on how to implement custom features.

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-12-22T10:57:35Z

Qodana for JVM

1254 new problems were found

Inspection name	Severity	Problems
`Check Kotlin and Java source code coverage`	🔶 Warning	1234
`Missing KDoc for public API declaration`	🔶 Warning	20

@@ Code coverage @@
+ 72% total lines covered
18063 lines analyzed, 13017 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

azhebel · 2026-01-05T17:50:42Z

+- `interceptSubgraphExecutionCompleted`: After a subgraph completes.
+- `interceptSubgraphExecutionFailed`: When a subgraph execution fails.
+
+Note that interceptors are feature-scoped: only the feature that registers a handler receives those events (subject to 


Is this a note?) Also, I am lost at this point. You never mentioned handlers before this point. Event handlers are a predefined feature, so I am not sure if that's what you mean. The FeatureConfig subclass in your example doesn't have setEventFilter overridden. If this is an important note, I'd expand on this, provide some context and links.

azhebel · 2026-01-05T17:56:13Z

+### Disabling event filtering for a feature
+
+Some features, such as debugger and OpenTelemetry, must observe the entire event stream. If your feature depends on the 
+full event stream, disable event filtering by overriding `setEventFilter` in your feature configuration to ignore custom


Here you mention setEventFilter again, but it is not at all evident what it's for and why you need to make it always return true (disable events filtering) if the feature "depends on the full event stream". Are some events filtered by default?

I don't think there are default filters, but you should be able to set your own ones when installing a feature in an agent. As some features, such as OpenTelemetry, may depend on receiving all events as they are, this is a way to prevent any filtering or processing that would interfere with the functioning of the feature. @sdubov can confirm whether my understanding here is correct.

I agree we can make this more explicit, though.

azhebel

Looks good! Just a couple more minor comments.

azhebel · 2026-02-06T16:35:28Z

+1. Create a feature class.
+2. Define a configuration class. The configuration class is an extension of the [FeatureConfig](https://api.koog.ai/agents/agents-core/ai.koog.agents.core.feature.config/-feature-config/index.html) class.
+3. Create a companion object that implements `AIAgentGraphFeature`, `AIAgentFunctionalFeature`, or both.
+4. Give your feature a stable storage key so it can be retrieved in contexts.


It is not very obvious what "can be retrieved in contexts" refers to. It doesn't look like you mention it anywhere on this page. And if it's important enough to mention, maybe it needs its own separate chapter or page? As an altrnative, just an example, when would I need to use this key, for what?

sdubov

@marinkovicmarko , thank you a bunch for the amazing article! I really liked the easy and strict structure. I've left several comments that we can discuss if you find those topics useful.

sdubov · 2026-02-25T12:56:40Z

+Koog provides two interfaces that you can extend to implement custom features:
+
+- [AIAgentGraphFeature](https://api.koog.ai/agents/agents-core/ai.koog.agents.core.feature/-a-i-agent-graph-feature/index.html): Represents a feature specific to [agents that have defined workflows](complex-workflow-agents.md) (graph-based agents).
+- [AIAgentFunctionalFeature](https://api.koog.ai/agents/agents-core/ai.koog.agents.core.feature/-a-i-agent-functional-feature/index.html): Represents a feature that can be used with [functional agents](functional-agents.md).


I'm afraid we have three now: two you mentioned + AIAgentPlannerFeature. But I do not see this in the doc (https://api.koog.ai). So, maybe update this when this planner is available in the docs as well. cc @antoniibelyshev.

Not sure if a more recent version of API docs was deployed in the meantime, I see this: https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner/-a-i-agent-planner-feature/index.html

sdubov · 2026-02-25T13:20:42Z

+
+For a feature to receive a specific type of event, it needs to register the corresponding pipeline interceptor.
+
+### Filtering agent events


This is not actually a part of feature implementation, it is rather a part of agent configuration. Do we went to keep it in this MD file as well?

sdubov · 2026-02-25T13:21:58Z

+```
+<!--- KNIT example-custom-features-03.kt -->
+
+#### Disabling event filtering for a feature


Oh, I see, the section about filtering is pre-requisite for describing this pattern.

Add documentation on how to implement custom features. --- #### 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) - [x] Documentation update - [ ] 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 - [ ] 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 - [x] Docs have been added / updated

marinkovicmarko requested review from azhebel, innateteniuk and sdubov December 22, 2025 10:31

azhebel reviewed Jan 5, 2026

View reviewed changes

marinkovicmarko force-pushed the marinkovicmarko/custom-feature-creation-docs branch from 5ed6ed3 to 61dd236 Compare January 28, 2026 14:47

azhebel approved these changes Feb 6, 2026

View reviewed changes

marinkovicmarko changed the title ~~Add custom feature creation documentation~~ docs: add custom feature creation documentation Feb 10, 2026

sdubov approved these changes Feb 25, 2026

View reviewed changes

marinkovicmarko added 4 commits February 26, 2026 23:02

Add custom feature creation documentation

e2f3a00

Post-review feedback

501c03b

Final post-feedback update

718c1c4

Add AIAgentPlannerFeature, implement feedback

c213fe5

marinkovicmarko force-pushed the marinkovicmarko/custom-feature-creation-docs branch from 820e092 to c213fe5 Compare February 27, 2026 11:07

marinkovicmarko merged commit 148458d into develop Mar 3, 2026
14 checks passed

marinkovicmarko deleted the marinkovicmarko/custom-feature-creation-docs branch March 3, 2026 12:37


		For a feature to receive a specific type of event, it needs to register the corresponding pipeline interceptor.

		### Filtering agent events

Conversation

marinkovicmarko commented Dec 22, 2025

Type of the changes

Checklist

Additional steps for pull requests adding a new feature

Uh oh!

github-actions Bot commented Dec 22, 2025

Qodana for JVM

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

azhebel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sdubov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants