temporal-spring-ai: pass provider-specific ChatOptions through the activity boundary (#2857)

donald-pinckney · claude · web-flow · commit 911dd02c1320 · 2026-04-27T17:42:50.000Z
* temporal-spring-ai: plan — provider-specific ChatOptions pass-through

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

* temporal-spring-ai: amend plan — switch to serialized-blob pass-through

Option 2 (serialize the full ChatOptions subclass as JSON + class name,
rehydrate on the activity side) is strictly better than the opaque map.
Full fidelity, no per-provider allow-list, no builder gymnastics.

The earlier rationale for option 1 ("drags provider classes into the
workflow's classpath") was wrong: workflow and activity workers can be
separate JVMs, but the user's workflow can only construct
OpenAiChatOptions if spring-ai-openai is already on the workflow
worker's classpath, and the activity worker has the same class because
that's where the ChatModel bean runs. The precondition holds whenever
the feature is actually used.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

* temporal-spring-ai: pass provider-specific ChatOptions through the activity boundary

Serialize the caller's ChatOptions as (class name, JSON) on the workflow
side and rehydrate the exact subclass on the activity side. Every field
survives — including provider-specific ones like OpenAI
reasoning_effort or Anthropic thinking-budget settings — without the
plugin needing per-provider allow-lists, reflection into builder types,
or compile deps on spring-ai-openai/anthropic/etc.

Changes:
- ChatModelTypes.ModelOptions: two new nullable fields,
  chatOptionsClass and chatOptionsJson. Older callers that only set
  the common scalar fields still work via a convenience constructor.
- ActivityChatModel: serialize the caller's ChatOptions with a plain
  ObjectMapper when non-null; a Jackson mixin skips the tool-callback
  bag (toolCallbacks/toolNames/toolContext) since those cross the
  boundary via the separate `tools` field. Serialization failure is
  logged at debug and leaves the blob fields null — activity side then
  uses the common-field path.
- ChatModelActivityImpl: primary path rehydrates from the serialized
  blob and, if the result is a ToolCallingChatOptions, re-attaches the
  stub tool callbacks plus forces internalToolExecutionEnabled=false.
  Fallback path (no blob, class-not-found, deser error) builds a plain
  ToolCallingChatOptions from the common scalar fields, identical to
  the prior behavior.

Tests:
- ProviderOptionsPassthroughTest.customChatOptionsSubclass... — a
  test-local CustomChatOptions extending DefaultToolCallingChatOptions
  with an extra reasoningEffort field round-trips, and common fields
  (temperature/maxTokens) come through the same path.
- ProviderOptionsPassthroughTest.nullChatOptions... — workflow that
  doesn't set any options still works via the fallback path.

The workflow calls ActivityChatModel.call(new Prompt(...)) directly
instead of going through ChatClient, because ChatClient.defaultOptions
coerces the caller's subclass into the client's internal options type
before ActivityChatModel ever sees it. Users of ChatClient who want
provider-specific options should set those on the ChatModel bean's
default options (Spring AI merges those into every call).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

* temporal-spring-ai: drop PLAN.md

Planning scratchpad — not part of the shipped artifact. Removed before merge.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/temporal-spring-ai/src/main/java/io/temporal/springai/activity/ChatModelActivityImpl.java b/temporal-spring-ai/src/main/java/io/temporal/springai/activity/ChatModelActivityImpl.java
@@ -1,15 +1,19 @@
 package io.temporal.springai.activity;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
 import io.temporal.springai.model.ChatModelTypes;
 import io.temporal.springai.model.ChatModelTypes.Message;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.ai.chat.messages.*;
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.ai.chat.model.ChatResponse;
+import org.springframework.ai.chat.prompt.ChatOptions;
 import org.springframework.ai.chat.prompt.Prompt;
 import org.springframework.ai.content.Media;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
@@ -30,6 +34,25 @@
  */
 public class ChatModelActivityImpl implements ChatModelActivity {
 
+  private static final Logger log = LoggerFactory.getLogger(ChatModelActivityImpl.class);
+
+  /**
+   * Reads the caller's {@link ChatOptions} back out of the serialized JSON carried on {@link
+   * ChatModelTypes.ModelOptions}. Plain Jackson — the workflow side wrote the blob with a matching
+   * plain {@link ObjectMapper}.
+   */
+  private static final ObjectMapper OPTIONS_MAPPER =
+      new ObjectMapper().addMixIn(ToolCallingChatOptions.class, ToolCallingChatOptionsMixin.class);
+
+  /**
+   * Mirror of the mixin in {@code ActivityChatModel} so deserialization ignores the same tool-bag
+   * properties the workflow side skipped.
+   */
+  @com.fasterxml.jackson.annotation.JsonIgnoreProperties(
+      value = {"toolCallbacks", "toolNames", "toolContext"},
+      ignoreUnknown = true)
+  private abstract static class ToolCallingChatOptionsMixin {}
+
   private final Map<String, ChatModel> chatModels;
   private final String defaultModelName;
 
@@ -77,6 +100,32 @@ private Prompt createPrompt(ChatModelTypes.ChatModelActivityInput input) {
     List<org.springframework.ai.chat.messages.Message> messages =
         input.messages().stream().map(this::toSpringMessage).collect(Collectors.toList());
 
+    List<ToolCallback> toolCallbacks = stubToolCallbacks(input);
+
+    // Primary path: rehydrate the caller's exact ChatOptions subclass from the serialized blob.
+    // Preserves provider-specific fields (OpenAI reasoning_effort, Anthropic thinking budget,
+    // etc.) that aren't representable in the common ModelOptions record.
+    ChatOptions rehydrated = tryRehydrateChatOptions(input.modelOptions());
+    if (rehydrated instanceof ToolCallingChatOptions tcOpts) {
+      tcOpts.setInternalToolExecutionEnabled(false);
+      if (!toolCallbacks.isEmpty()) {
+        tcOpts.setToolCallbacks(toolCallbacks);
+      }
+      return Prompt.builder().messages(messages).chatOptions(tcOpts).build();
+    }
+    if (rehydrated != null) {
+      // Caller's ChatOptions isn't a ToolCallingChatOptions. Accept it as-is; tool callbacks
+      // can't be attached via this path, but most provider options in practice are
+      // ToolCallingChatOptions subclasses so this branch is a rare fallback.
+      log.debug(
+          "Rehydrated ChatOptions {} is not a ToolCallingChatOptions; tool callbacks will be"
+              + " omitted for this call.",
+          rehydrated.getClass().getName());
+      return Prompt.builder().messages(messages).chatOptions(rehydrated).build();
+    }
+
+    // Fallback path: no serialized blob, or rehydration failed. Build a ToolCallingChatOptions
+    // from the common scalar fields.
     ToolCallingChatOptions.Builder optionsBuilder =
         ToolCallingChatOptions.builder()
             .internalToolExecutionEnabled(false); // Let workflow handle tool execution
@@ -93,24 +142,63 @@ private Prompt createPrompt(ChatModelTypes.ChatModelActivityInput input) {
       if (opts.stopSequences() != null) optionsBuilder.stopSequences(opts.stopSequences());
     }
 
-    // Add tool callbacks (stubs that provide definitions but won't be executed
-    // since internalToolExecutionEnabled is false)
-    if (!CollectionUtils.isEmpty(input.tools())) {
-      List<ToolCallback> toolCallbacks =
-          input.tools().stream()
-              .map(
-                  tool ->
-                      createStubToolCallback(
-                          tool.function().name(),
-                          tool.function().description(),
-                          tool.function().jsonSchema()))
-              .collect(Collectors.toList());
+    if (!toolCallbacks.isEmpty()) {
       optionsBuilder.toolCallbacks(toolCallbacks);
     }
 
-    ToolCallingChatOptions chatOptions = optionsBuilder.build();
+    return Prompt.builder().messages(messages).chatOptions(optionsBuilder.build()).build();
+  }
+
+  private List<ToolCallback> stubToolCallbacks(ChatModelTypes.ChatModelActivityInput input) {
+    if (CollectionUtils.isEmpty(input.tools())) {
+      return List.of();
+    }
+    return input.tools().stream()
+        .map(
+            tool ->
+                createStubToolCallback(
+                    tool.function().name(),
+                    tool.function().description(),
+                    tool.function().jsonSchema()))
+        .collect(Collectors.toList());
+  }
 
-    return Prompt.builder().messages(messages).chatOptions(chatOptions).build();
+  /**
+   * Attempts to rehydrate the caller's exact {@link ChatOptions} subclass from the serialized blob
+   * in {@code modelOptions}. Returns {@code null} if the blob is absent or rehydration fails, in
+   * which case the caller should use the common-field fallback.
+   */
+  private ChatOptions tryRehydrateChatOptions(ChatModelTypes.ModelOptions modelOptions) {
+    if (modelOptions == null
+        || modelOptions.chatOptionsClass() == null
+        || modelOptions.chatOptionsJson() == null) {
+      return null;
+    }
+    String className = modelOptions.chatOptionsClass();
+    try {
+      Class<?> cls = Class.forName(className, true, Thread.currentThread().getContextClassLoader());
+      if (!ChatOptions.class.isAssignableFrom(cls)) {
+        log.warn(
+            "Serialized ChatOptions class {} is not a ChatOptions; falling back to common fields.",
+            className);
+        return null;
+      }
+      return (ChatOptions) OPTIONS_MAPPER.readValue(modelOptions.chatOptionsJson(), cls);
+    } catch (ClassNotFoundException e) {
+      log.warn(
+          "Could not load ChatOptions class {} on the activity side; falling back to common"
+              + " fields. This typically means spring-ai-<provider> is not on this worker's"
+              + " classpath.",
+          className);
+      return null;
+    } catch (com.fasterxml.jackson.core.JsonProcessingException e) {
+      log.warn(
+          "Could not deserialize ChatOptions of type {} on the activity side; falling back to"
+              + " common fields. Cause: {}",
+          className,
+          e.getMessage());
+      return null;
+    }
   }
 
   private org.springframework.ai.chat.messages.Message toSpringMessage(Message message) {
diff --git a/temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java b/temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java
@@ -1,5 +1,7 @@
 package io.temporal.springai.model;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import io.temporal.activity.ActivityOptions;
 import io.temporal.common.RetryOptions;
 import io.temporal.springai.activity.ChatModelActivity;
@@ -65,6 +67,32 @@
  */
 public class ActivityChatModel implements ChatModel {
 
+  private static final org.slf4j.Logger log =
+      org.slf4j.LoggerFactory.getLogger(ActivityChatModel.class);
+
+  /**
+   * Used to serialize the caller's {@link ChatOptions} into a string so the activity side can
+   * rehydrate the exact subclass. Plain Jackson with no Temporal-specific configuration — the
+   * output goes into a {@code String} field of {@link ChatModelTypes.ModelOptions}, which
+   * Temporal's own data converter then handles as normal.
+   */
+  private static final ObjectMapper OPTIONS_MAPPER =
+      new ObjectMapper().addMixIn(ToolCallingChatOptions.class, ToolCallingChatOptionsMixin.class);
+
+  /**
+   * Jackson mixin that skips {@link ToolCallingChatOptions}'s tool-callback bag on serialization.
+   * Tool definitions cross the activity boundary via {@link ChatModelTypes.FunctionTool} — the
+   * actual callbacks are re-stubbed on the activity side — so we don't need to ship them, and their
+   * concrete implementations (method tool callbacks, activity proxies, etc.) are not
+   * Jackson-friendly.
+   */
+  @com.fasterxml.jackson.annotation.JsonIgnoreProperties({
+    "toolCallbacks",
+    "toolNames",
+    "toolContext"
+  })
+  private abstract static class ToolCallingChatOptionsMixin {}
+
   /** Default timeout for chat model activity calls (2 minutes). */
   public static final Duration DEFAULT_TIMEOUT = Duration.ofMinutes(2);
 
@@ -301,10 +329,24 @@ private ChatModelTypes.ChatModelActivityInput createActivityInput(Prompt prompt)
             .flatMap(msg -> toActivityMessages(msg).stream())
             .collect(Collectors.toList());
 
-    // Convert options
+    // Convert options — carry both the common scalars (fallback path) and a serialized blob of
+    // the caller's exact ChatOptions subclass (primary path on the activity side, which
+    // preserves provider-specific fields like OpenAI reasoning_effort).
     ChatModelTypes.ModelOptions modelOptions = null;
     if (prompt.getOptions() != null) {
       ChatOptions opts = prompt.getOptions();
+      String chatOptionsClass = null;
+      String chatOptionsJson = null;
+      try {
+        chatOptionsJson = OPTIONS_MAPPER.writeValueAsString(opts);
+        chatOptionsClass = opts.getClass().getName();
+      } catch (JsonProcessingException e) {
+        log.debug(
+            "Could not JSON-serialize ChatOptions of type {}; activity will fall back to"
+                + " common-field path. Cause: {}",
+            opts.getClass().getName(),
+            e.getMessage());
+      }
       modelOptions =
           new ChatModelTypes.ModelOptions(
               opts.getModel(),
@@ -314,7 +356,9 @@ private ChatModelTypes.ChatModelActivityInput createActivityInput(Prompt prompt)
               opts.getStopSequences(),
               opts.getTemperature(),
               opts.getTopK(),
-              opts.getTopP());
+              opts.getTopP(),
+              chatOptionsClass,
+              chatOptionsJson);
     }
 
     // Convert tool definitions
diff --git a/temporal-spring-ai/src/main/java/io/temporal/springai/model/ChatModelTypes.java b/temporal-spring-ai/src/main/java/io/temporal/springai/model/ChatModelTypes.java
@@ -233,7 +233,18 @@ public record Function(
         @JsonProperty("json_schema") String jsonSchema) {}
   }
 
-  /** Model options for the chat request. */
+  /**
+   * Model options for the chat request.
+   *
+   * <p>When {@code chatOptionsClass} and {@code chatOptionsJson} are both non-null, the activity
+   * side attempts to rehydrate the caller's exact {@link
+   * org.springframework.ai.chat.prompt.ChatOptions} subclass by loading the class and
+   * JSON-deserializing the blob. That path carries every field the caller set, including
+   * provider-specific ones like OpenAI {@code reasoning_effort} or Anthropic thinking-budget
+   * settings. If class loading or deserialization fails, or if the workflow side couldn't serialize
+   * the caller's options in the first place, the common scalar fields on this record are used as a
+   * fallback.
+   */
   @JsonInclude(JsonInclude.Include.NON_NULL)
   @JsonIgnoreProperties(ignoreUnknown = true)
   public record ModelOptions(
@@ -244,5 +255,34 @@ public record ModelOptions(
       @JsonProperty("stop_sequences") List<String> stopSequences,
       @JsonProperty("temperature") Double temperature,
       @JsonProperty("top_k") Integer topK,
-      @JsonProperty("top_p") Double topP) {}
+      @JsonProperty("top_p") Double topP,
+      @JsonProperty("chat_options_class") String chatOptionsClass,
+      @JsonProperty("chat_options_json") String chatOptionsJson) {
+
+    /**
+     * Convenience constructor for callers that only populate common scalar fields, keeping the
+     * existing call sites (tests and the prior activity impl) working unchanged.
+     */
+    public ModelOptions(
+        String model,
+        Double frequencyPenalty,
+        Integer maxTokens,
+        Double presencePenalty,
+        List<String> stopSequences,
+        Double temperature,
+        Integer topK,
+        Double topP) {
+      this(
+          model,
+          frequencyPenalty,
+          maxTokens,
+          presencePenalty,
+          stopSequences,
+          temperature,
+          topK,
+          topP,
+          null,
+          null);
+    }
+  }
 }
diff --git a/temporal-spring-ai/src/test/java/io/temporal/springai/ProviderOptionsPassthroughTest.java b/temporal-spring-ai/src/test/java/io/temporal/springai/ProviderOptionsPassthroughTest.java
