feat(models): add GLM (Zhipu AI) adaptation with dedicated provider and formatters

[Leeaoyin]

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

Fixes #2212

Background

GLM (Zhipu AI) exposes an OpenAI-compatible Chat Completions endpoint, but previously users had to manually configure baseUrl, pick the right formatter from the formatter package, and there was no ModelRegistry support (no glm:<model> string id). The existing GLMFormatter also lagged behind the current Zhipu API (glm-5.2 / glm-4.7 era): several OpenAI-style parameters are rejected or silently ignored by the GLM endpoint.

Changes

New package io.agentscope.extensions.model.openai.compat.glm:

• GLMFormatter — adapted to the latest official API reference (https://docs.bigmodel.cn/cn/api/introduction):
  • Ensures at least one user message exists (GLM returns error 1214 otherwise)
  • tool_choice only supports auto; other values are degraded with a log
  • Does not send the strict parameter in tool definitions
  • Strips unsupported frequency_penalty / presence_penalty / thinking_budget
  • Maps max_completion_tokens to max_tokens (GLM only supports the latter)
  • Clamps temperature to [0.0, 1.0] and top_p to [0.01, 1.0]; translates temperature = 0 to do_sample = false per the official OpenAI compatibility guide (https://docs.bigmodel.cn/cn/guide/develop/openai/introduction)
  • Thinking mode (thinking), GLM-5.2 reasoning_effort, and tool_stream pass through via GenerateOptions
• GLMMultiAgentFormatter — same GLM adaptations on top of OpenAIMultiAgentFormatter
• GLMModelProvider — modeled after OpenAIModelProvider; creates OpenAIChatModel instances preconfigured for GLM:
  • Supports glm:<model> ids (e.g. glm:glm-5.2) via ModelRegistry
  • Default base URL https://open.bigmodel.cn/api/paas/v4, default formatter GLMFormatter
  • API key from context, then GLM_API_KEY, then ZHIPUAI_API_KEY
  • Native structured output disabled by default (GLM response_format only supports json_object); can be re-enabled via the nativeStructuredOutput option
    SPI registration: appended GLMModelProvider to META-INF/services/io.agentscope.core.model.spi.ModelProvider.
    Deprecation: the old formatter.GLMFormatter / formatter.GLMMultiAgentFormatter are marked @Deprecated and now extend the new compat.glm implementations, so existing code keeps working unchanged. References in OpenAIChatModel Javadoc and the e2e GLMProvider were migrated to the new package.
    Docs: added a GLM section to docs/v2/{zh,en}/integration/model/openai.md (registry id, explicit builder, adaptation list, thinking/reasoning_effort/tool_stream usage) and mentioned GLM_API_KEY in docs/v2/{zh,en}/docs/building-blocks/model.md.

How to test

• Unit tests (no API key required): mvn test -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-openai -am -Dtest="GLM*Test"
  • compat/glm/GLMFormatterTest, GLMMultiAgentFormatterTest — formatter adaptations (user message, tool_choice, strict, parameter sanitizing/clamping)
  • compat/glm/GLMModelProviderTest — provider id/supports/create, defaults, ServiceLoader discovery
  • formatter/GLMFormatterTest — backward compatibility of the deprecated classes
• Manual (requires GLM_API_KEY): build an agent with .model("glm:glm-5.2") and verify chat + tool calling against the Zhipu endpoint.

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

This PR adds first-class support for Zhipu AI GLM via an OpenAI-compatible adapter layer, including glm:<model> ModelRegistry IDs, a dedicated GLMModelProvider, updated GLM-specific formatters, plus documentation and unit tests (fixes #2212).

Changes:

• Introduces io.agentscope.extensions.model.openai.compat.glm with GLMFormatter, GLMMultiAgentFormatter, and GLMModelProvider (SPI-registered) to support glm:<model> ids with GLM defaults.
• Deprecates the legacy openai.formatter.GLMFormatter / GLMMultiAgentFormatter by making them extend the new compat implementations; updates references (Javadoc + e2e provider).
• Adds/updates docs (EN/ZH) and adds focused unit tests for provider behavior and GLM request sanitization/adaptation.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/v2/zh/integration/model/openai.md	Adds ZH usage docs for glm:<model> and GLM-specific request adaptations.
docs/v2/zh/docs/building-blocks/model.md	Mentions GLM_API_KEY discovery and glm:<model> behavior in ZH docs.
docs/v2/en/integration/model/openai.md	Adds EN usage docs for glm:<model> and GLM-specific request adaptations.
docs/v2/en/docs/building-blocks/model.md	Mentions GLM_API_KEY discovery and glm:<model> behavior in EN docs.
agentscope-extensions/.../formatter/GLMFormatterTest.java	Refocuses legacy-package tests to validate deprecated-class backward compatibility.
agentscope-extensions/.../compat/glm/GLMMultiAgentFormatterTest.java	Adds unit tests for compat GLM multi-agent formatter behavior/sanitization.
agentscope-extensions/.../compat/glm/GLMModelProviderTest.java	Adds unit tests for provider id/supports/create defaults and ServiceLoader discovery.
agentscope-extensions/.../compat/glm/GLMFormatterTest.java	Adds unit tests for GLM formatter request adaptations (tool_choice, strict, clamping, mapping).
agentscope-extensions/.../resources/META-INF/services/io.agentscope.core.model.spi.ModelProvider	Registers GLMModelProvider for ModelRegistry resolution via SPI.
agentscope-extensions/.../openai/OpenAIChatModel.java	Updates Javadoc links to point to the new compat GLM formatter package.
agentscope-extensions/.../openai/formatter/GLMMultiAgentFormatter.java	Deprecates legacy formatter and makes it extend the compat implementation.
agentscope-extensions/.../openai/formatter/GLMFormatter.java	Deprecates legacy formatter and makes it extend the compat implementation + delegates helper statics.
agentscope-extensions/.../openai/compat/glm/GLMMultiAgentFormatter.java	Implements GLM-specific multi-agent formatting and option sanitization.
agentscope-extensions/.../openai/compat/glm/GLMModelProvider.java	Adds a GLM provider that creates OpenAIChatModel with GLM defaults and context options.
agentscope-extensions/.../openai/compat/glm/GLMFormatter.java	Implements GLM request adaptations (tool_choice degradation, param stripping, mapping, clamping).
agentscope-extensions/.../e2e/providers/GLMProvider.java	Updates e2e provider to import compat GLM formatters.

[codecov]

Codecov Report

❌ Patch coverage is 85.25641% with 23 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ions/model/openai/compat/glm/GLMModelProvider.java	75.32%	9 Missing and 10 partials ⚠️
...tensions/model/openai/compat/glm/GLMFormatter.java	93.84%	2 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!