fix(openai): avoid setting max_tokens and max_completion_tokens together (#906)

Fixes #905

## Summary
- Add `GenerateOptions.maxCompletionTokens`
- Update `OpenAIChatFormatter` to set `max_tokens` and
`max_completion_tokens` independently, without mirroring

## Behavior
- If only `maxTokens` is set -> only `max_tokens` is sent
- If only `maxCompletionTokens` is set -> only `max_completion_tokens`
is sent
- If both are set -> both fields are sent as-is (SDK does not enforce
exclusivity; provider can decide)

## Notes
- Affects `OpenAIChatFormatter` and its subclasses (e.g.
`OpenAIMultiAgentFormatter`, `DeepSeekFormatter`, `GLMFormatter`)
- Other providers (Gemini/DashScope/Anthropic/Ollama, etc.) continue to
use `maxTokens` only

Author: darkwu

agentscope-core/src/main/java/io/agentscope/core/formatter/openai/OpenAIChatFormatter.java

@@ -101,13 +101,7 @@ public void applyOptions(
             request.setPresencePenalty(presencePenalty);
         }
 
-        // Apply max tokens
-        Integer maxTokens =
-                getOptionOrDefault(options, defaultOptions, GenerateOptions::getMaxTokens);
-        if (maxTokens != null) {
-            request.setMaxCompletionTokens(maxTokens);
-            request.setMaxTokens(maxTokens);
-        }
+        applyMaxTokens(request, options, defaultOptions);
 
         // Apply seed
         Long seed = getOptionOrDefault(options, defaultOptions, GenerateOptions::getSeed);
@@ -123,6 +117,22 @@ public void applyOptions(
         applyAdditionalBodyParams(request, options);
     }
 
+    protected void applyMaxTokens(
+            OpenAIRequest request, GenerateOptions options, GenerateOptions defaultOptions) {
+        Integer maxTokens =
+                getOptionOrDefault(options, defaultOptions, GenerateOptions::getMaxTokens);
+        if (maxTokens != null) {
+            request.setMaxTokens(maxTokens);
+        }
+
+        Integer maxCompletionTokens =
+                getOptionOrDefault(
+                        options, defaultOptions, GenerateOptions::getMaxCompletionTokens);
+        if (maxCompletionTokens != null) {
+            request.setMaxCompletionTokens(maxCompletionTokens);
+        }
+    }
+
     @Override
     public void applyTools(OpenAIRequest request, List<ToolSchema> tools) {
         if (tools == null || tools.isEmpty()) {

agentscope-core/src/main/java/io/agentscope/core/model/GenerateOptions.java

@@ -39,6 +39,7 @@ public class GenerateOptions {
     private final Double temperature;
     private final Double topP;
     private final Integer maxTokens;
+    private final Integer maxCompletionTokens;
     private final Double frequencyPenalty;
     private final Double presencePenalty;
     private final Integer thinkingBudget;
@@ -65,6 +66,7 @@ private GenerateOptions(Builder builder) {
         this.temperature = builder.temperature;
         this.topP = builder.topP;
         this.maxTokens = builder.maxTokens;
+        this.maxCompletionTokens = builder.maxCompletionTokens;
         this.frequencyPenalty = builder.frequencyPenalty;
         this.presencePenalty = builder.presencePenalty;
         this.thinkingBudget = builder.thinkingBudget;
@@ -184,6 +186,20 @@ public Integer getMaxTokens() {
         return maxTokens;
     }
 
+    /**
+     * Gets the maximum number of completion tokens to generate.
+     *
+     * <p>This is an alternative to {@link #getMaxTokens()} for OpenAI-compatible APIs that support
+     * {@code max_completion_tokens}. Some providers/models treat {@code max_tokens} and
+     * {@code max_completion_tokens} as mutually exclusive; this SDK does not enforce exclusivity
+     * and will forward exactly what the caller sets.
+     *
+     * @return the maximum completion tokens limit, or null if not set
+     */
+    public Integer getMaxCompletionTokens() {
+        return maxCompletionTokens;
+    }
+
     /**
      * Gets the frequency penalty.
      *
@@ -388,6 +404,10 @@ public static GenerateOptions mergeOptions(GenerateOptions primary, GenerateOpti
                 primary.temperature != null ? primary.temperature : fallback.temperature);
         builder.topP(primary.topP != null ? primary.topP : fallback.topP);
         builder.maxTokens(primary.maxTokens != null ? primary.maxTokens : fallback.maxTokens);
+        builder.maxCompletionTokens(
+                primary.maxCompletionTokens != null
+                        ? primary.maxCompletionTokens
+                        : fallback.maxCompletionTokens);
         builder.frequencyPenalty(
                 primary.frequencyPenalty != null
                         ? primary.frequencyPenalty
@@ -450,6 +470,7 @@ public static class Builder {
         private Double temperature;
         private Double topP;
         private Integer maxTokens;
+        private Integer maxCompletionTokens;
         private Double frequencyPenalty;
         private Double presencePenalty;
         private Integer thinkingBudget;
@@ -560,6 +581,22 @@ public Builder maxTokens(Integer maxTokens) {
             return this;
         }
 
+        /**
+         * Sets the maximum number of completion tokens to generate.
+         *
+         * <p>This is an alternative to {@link #maxTokens(Integer)} for OpenAI-compatible APIs that
+         * support {@code max_completion_tokens}. This builder does not enforce exclusivity with
+         * {@code maxTokens}; both may be set and will be forwarded as-is by formatters that support
+         * both fields.
+         *
+         * @param maxCompletionTokens the maximum completion tokens limit
+         * @return this builder instance
+         */
+        public Builder maxCompletionTokens(Integer maxCompletionTokens) {
+            this.maxCompletionTokens = maxCompletionTokens;
+            return this;
+        }
+
         /**
          * Sets the frequency penalty.
          *