feat(models): add Kimi (Moonshot AI) adaptation with dedicated provider and formatters by Leeaoyin · Pull Request #2320 · agentscope-ai/agentscope-java

Leeaoyin · 2026-07-20T08:47:11Z

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

New implementations (`io.agentscope.extensions.model.openai.compat.kimi`)

This PR adds first-class Kimi (Moonshot AI) support on top of the OpenAI-compatible extension module, adapted to the latest official Kimi open platform documentation (kimi-k3 / kimi-k2.7-code / kimi-k2.6 / kimi-k2.5 / moonshot-v1 series).

KimiFormatter — extends OpenAIChatFormatter with Kimi-specific request adaptations. Unlike other vendors, Kimi's constraints differ per model series, so the sanitization is model-aware:
- temperature / top_p / frequency_penalty / presence_penalty are fixed by the platform on kimi-* models (the API rejects other values) and are stripped from requests; they are passed through for the moonshot-v1 series, which still accepts them.
- reasoning_effort (low / high / max) is only supported by kimi-k3 and stripped on other models; thinking_budget is not a Kimi parameter and always stripped (K2.x thinking is controlled via the thinking body param instead).
- Only max_tokens is documented: max_completion_tokens (newer OpenAI style) is mapped onto it.
- tool_choice matrix per the official guide: auto / none pass through everywhere; required is kimi-k3-only and degraded to auto on the K2.x series; forcing a specific function is incompatible with thinking enabled (HTTP 400), so it is degraded to auto on always-thinking models (kimi-k3, kimi-k2.7-code) and passed through otherwise.
- The strict parameter in tool definitions is not sent (not documented by Kimi).
- Assistant reasoning_content is preserved in the request history, satisfying Preserved Thinking on kimi-k3 / kimi-k2.7-code and thinking.keep = "all" on kimi-k2.6.
KimiMultiAgentFormatter — extends OpenAIMultiAgentFormatter, reusing the same Kimi-specific sanitization and tool-choice handling.
KimiModelProvider — resolves kimi:<model> ids through ModelRegistry (Java SPI). Creates OpenAIChatModel instances preconfigured with:
- base URL https://api.moonshot.cn/v1 (consistent with KimiCredential.DEFAULT_BASE_URL);
- API key from ModelCreationContext, then MOONSHOT_API_KEY, then KIMI_API_KEY;
- KimiFormatter as the default formatter (a custom Formatter component takes precedence);
- nativeStructuredOutput disabled by default (Kimi response_format only supports json_object, agents fall back to the generate_response tool) and nativeStructuredOutputWithTools disabled by default (Kimi prioritises response_format over tool invocations); both re-enablable via context options.

Other changes

SPI registration for KimiModelProvider in META-INF/services/io.agentscope.core.model.spi.ModelProvider.
OpenAIChatModel javadoc now lists KimiFormatter among provider-specific formatters.

Tests

KimiFormatterTest (27 cases): model classification helpers, fixed-sampling-param stripping vs moonshot-v1 pass-through, reasoning_effort handling, max_completion_tokens mapping, thinking body-param pass-through, the full tool_choice degradation matrix, and reasoning_content preservation in formatted history.
KimiMultiAgentFormatterTest (8 cases): multi-agent merging plus shared sanitization behavior.
KimiModelProviderTest (8 cases): provider id / supports / creation with ModelCreationContext, structured-output defaults and overrides, ServiceLoader resolution via ModelRegistry.
Verified locally: mvn spotless:check passes; module tests (422) and the full-repository mvn test all pass.

Documentation

docs/v2/{zh,en}/integration/model/openai.md: new "Kimi (Moonshot AI)" section with kimi:<model> and explicit-builder examples, the full list of request adaptations, and thinking-related parameter usage (thinking body param for K2.x, reasoning_effort for kimi-k3, Preserved Thinking notes).
docs/v2/{zh,en}/docs/building-blocks/model.md: environment variable list now includes MOONSHOT_API_KEY.

References

Checklist

Code is formatted with mvn spotless:apply
All new functionality is covered by unit tests
Existing tests pass (mvn test)
Documentation updated (zh + en)

- Introduced KimiFormatter for adapting requests to the Kimi Chat Completions API. - Updated OpenAIChatModel documentation to include Kimi model integration. - Added KimiModelProvider to the service provider configuration. - Enhanced environment variable handling to support MOONSHOT_API_KEY for Kimi models. - Updated relevant documentation in both English and Chinese to reflect new Kimi model capabilities.

…rovider - Updated the supports() method to ensure model IDs with only whitespace are not considered valid. - Added a test to verify that model names are trimmed correctly during creation. - Improved error messages for missing API keys to clarify requirements for model creation.

Copilot

Pull request overview

This PR adds first-class support for Kimi (Moonshot AI) on top of the existing OpenAI-compatible model extension by introducing Kimi-specific formatters and a dedicated ModelProvider (SPI-registered), along with docs and unit tests.

Changes:

Add KimiFormatter / KimiMultiAgentFormatter to apply Kimi model-series-specific request sanitization and tool-choice handling.
Add KimiModelProvider to resolve kimi:<model> IDs via ModelRegistry and create preconfigured OpenAIChatModel instances (Kimi base URL, env-var API key fallback, structured output defaults).
Add docs (EN/ZH) and comprehensive unit tests for formatter behavior and provider resolution.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/v2/zh/integration/model/openai.md	Document Kimi usage (`kimi:<model>`) and Kimi-specific request adaptations (ZH).
docs/v2/zh/docs/building-blocks/model.md	Add `MOONSHOT_API_KEY` to environment variable list (ZH).
docs/v2/en/integration/model/openai.md	Document Kimi usage (`kimi:<model>`) and Kimi-specific request adaptations (EN).
docs/v2/en/docs/building-blocks/model.md	Add `MOONSHOT_API_KEY` to environment variable list (EN).
agentscope-extensions/.../KimiMultiAgentFormatterTest.java	Unit tests for multi-agent formatting + shared Kimi sanitization behavior.
agentscope-extensions/.../KimiModelProviderTest.java	Unit tests for provider ID/supports/create defaults and ServiceLoader resolution.
agentscope-extensions/.../KimiFormatterTest.java	Unit tests for Kimi request sanitization, tool_choice matrix, and preserved reasoning content.
agentscope-extensions/.../META-INF/services/io.agentscope.core.model.spi.ModelProvider	Register `KimiModelProvider` for SPI discovery.
agentscope-extensions/.../OpenAIChatModel.java	Extend Javadoc to mention `KimiFormatter` as a provider-specific formatter.
agentscope-extensions/.../KimiMultiAgentFormatter.java	New multi-agent Kimi formatter that reuses shared sanitization/tool-choice logic.
agentscope-extensions/.../KimiModelProvider.java	New `ModelProvider` for `kimi:<model>` IDs with Kimi defaults and option overrides.
agentscope-extensions/.../KimiFormatter.java	New Kimi-aware formatter implementing model-series-specific request sanitization and tool-choice behavior.

codecov · 2026-07-20T09:01:38Z

Codecov Report

❌ Patch coverage is 85.27132% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../io/agentscope/core/model/ModelContextWindows.java	0.00%	13 Missing ⚠️
...nsions/model/openai/compat/kimi/KimiFormatter.java	93.58%	2 Missing and 3 partials ⚠️
...ns/model/openai/compat/kimi/KimiModelProvider.java	96.42%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

…rove test coverage - Restrict isAlwaysThinkingModel to the documented kimi-k2.7-code series - Add provider tests for missing API key, option validation and component overrides

oss-maintainer

Test review

jujn · 2026-08-03T08:24:52Z

+ *   <li>Only {@code max_tokens} is documented; {@code max_completion_tokens} is mapped to
+ *       {@code max_tokens} when the latter is not set. Reasoning tokens count towards
+ *       {@code max_tokens}, so the official guide recommends {@code max_tokens >= 16000} for
+ *       thinking models</li>


这里是不是写反了，官方推荐用 max_completion_tokens，max_tokens 已经废弃了：
https://platform.kimi.com/docs/api/chat#body-one-of-0-max-tokens
（我只是想确认一下，因为kimi官方文档很多地方不一致。确定的话，我本地直接修复。）

对的，确认过 API reference 的 schema 了，是写反了，感谢~🙂

对的，确认过 API reference 的 schema 了，是写反了，感谢~🙂

OK

Leeaoyin added 2 commits July 20, 2026 16:36

Copilot AI review requested due to automatic review settings July 20, 2026 08:47

Copilot started reviewing on behalf of Leeaoyin July 20, 2026 08:47 View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

Comment thread ...el-openai/src/main/java/io/agentscope/extensions/model/openai/compat/kimi/KimiFormatter.java

Leeaoyin and others added 3 commits July 22, 2026 10:11

fix(kimi): narrow always-thinking detection to kimi-k2.7-code and imp…

55c27c5

…rove test coverage - Restrict isAlwaysThinkingModel to the documented kimi-k2.7-code series - Add provider tests for missing API key, option validation and component overrides

Merge branch 'main' into feat(models)_Kimi_Model_Adaptation

6c4eb6a

Merge branch 'main' into feat(models)_Kimi_Model_Adaptation

46cd78a

oss-maintainer approved these changes Jul 28, 2026

View reviewed changes

Leeaoyin and others added 2 commits August 3, 2026 09:36

Merge branch 'main' into feat(models)_Kimi_Model_Adaptation

e4060e5

Merge branch 'main' into feat(models)_Kimi_Model_Adaptation

81d7a55

jujn requested changes Aug 3, 2026

View reviewed changes

fix: improve

0ee3b8d

jujn approved these changes Aug 3, 2026

View reviewed changes

jujn merged commit d3a9783 into agentscope-ai:main Aug 3, 2026
7 of 10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(models): add Kimi (Moonshot AI) adaptation with dedicated provider and formatters - #2320

feat(models): add Kimi (Moonshot AI) adaptation with dedicated provider and formatters#2320
jujn merged 8 commits into
agentscope-ai:mainfrom
Leeaoyin:feat(models)_Kimi_Model_Adaptation

Leeaoyin commented Jul 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

codecov Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

oss-maintainer left a comment

Uh oh!

jujn Aug 3, 2026

Uh oh!

Leeaoyin Aug 3, 2026

Uh oh!

jujn Aug 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Leeaoyin commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AgentScope-Java Version

Description

New implementations (io.agentscope.extensions.model.openai.compat.kimi)

Other changes

Tests

Documentation

References

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

codecov Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

oss-maintainer left a comment

Choose a reason for hiding this comment

Uh oh!

jujn Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Leeaoyin Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

jujn Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Leeaoyin commented Jul 20, 2026 •

edited

Loading

New implementations (`io.agentscope.extensions.model.openai.compat.kimi`)

codecov Bot commented Jul 20, 2026 •

edited

Loading