@@ -7,6 +7,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+ADDED
+
+- Added the optional `new_version` argument to
+`OrchestrationContext.continue_as_new()` so continued orchestrations can
+switch to a new version.
+
 ## v1.9.0
 
 ADDED
 
@@ -300,12 +300,14 @@ def new_complete_orchestration_action(
         status: pb.OrchestrationStatus,
         result: str | None = None,
         failure_details: pb.TaskFailureDetails | None = None,
-        carryover_events: list[pb.HistoryEvent] | None = None) -> pb.OrchestratorAction:
+        carryover_events: list[pb.HistoryEvent] | None = None,
+        new_version: str | None = None) -> pb.OrchestratorAction:
     completeOrchestrationAction = pb.CompleteOrchestrationAction(
         orchestrationStatus=status,
         result=get_string_value(result),
         failureDetails=failure_details,
-        carryoverEvents=carryover_events)
+        carryoverEvents=carryover_events,
+        newVersion=get_string_value(new_version))
 
     return pb.OrchestratorAction(id=id, completeOrchestration=completeOrchestrationAction)
 
 
@@ -389,7 +389,8 @@ def send_event(self, instance_id: str, event_name: str, *,
         )
 
     @abstractmethod
-    def continue_as_new(self, new_input: Any, *, save_events: bool = False) -> None:
+    def continue_as_new(self, new_input: Any, *, save_events: bool = False,
+                        new_version: str | None = None) -> None:
         """Continue the orchestration execution as a new instance.
 
         Parameters
@@ -398,6 +399,8 @@ def continue_as_new(self, new_input: Any, *, save_events: bool = False) -> None:
             The new input to use for the new orchestration instance.
         save_events : bool
             A flag indicating whether to add any unprocessed external events in the new orchestration history.
+        new_version : str | None
+            An optional version to assign to the new orchestration instance.
         """
         pass
 
 
@@ -1523,6 +1523,7 @@ def __init__(self,
         self._received_events: dict[str, list[str | None]] = {}
         self._pending_events: dict[str, list[task.CancellableTask[Any]]] = {}
         self._new_input: Any | None = None
+        self._new_version: str | None = None
         self._save_events = False
         self._encoded_custom_status: str | None = None
         self._parent_trace_context: pb.TraceContext | None = None
@@ -1619,7 +1620,8 @@ def set_failed(self, ex: Exception | pb.TaskFailureDetails):
         )
         self._pending_actions[action.id] = action
 
-    def set_continued_as_new(self, new_input: Any, save_events: bool):
+    def set_continued_as_new(self, new_input: Any, save_events: bool,
+                             new_version: str | None = None):
         if self._is_complete:
             return
 
@@ -1633,6 +1635,7 @@ def set_continued_as_new(self, new_input: Any, save_events: bool):
         # self._pending_actions.clear()  # Cancel any pending actions
         self._completion_status = pb.ORCHESTRATION_STATUS_CONTINUED_AS_NEW
         self._new_input = new_input
+        self._new_version = new_version
         self._save_events = save_events
 
     def get_actions(self) -> list[pb.OrchestratorAction]:
@@ -1657,6 +1660,7 @@ def get_actions(self) -> list[pb.OrchestratorAction]:
                 result=self._data_converter.serialize(self._new_input),
                 failure_details=None,
                 carryover_events=carryover_events,
+                new_version=self._new_version,
             )
             # We must return the existing tasks as well, to capture entity unlocks
             current_actions.append(action)
@@ -2135,11 +2139,12 @@ def send_event(self, instance_id: str, event_name: str, *,
                 ),
             )
 
-    def continue_as_new(self, new_input: Any, *, save_events: bool = False) -> None:
+    def continue_as_new(self, new_input: Any, *, save_events: bool = False,
+                        new_version: str | None = None) -> None:
         if self._is_complete:
             return
 
-        self.set_continued_as_new(new_input, save_events)
+        self.set_continued_as_new(new_input, save_events, new_version)
 
     def new_uuid(self) -> str:
         NAMESPACE_UUID: str = "9e952958-5e33-4daf-827f-2fa12937b875"
 
@@ -1719,11 +1719,12 @@ def orchestrator(ctx: task.OrchestrationContext, _):
 
 
 @pytest.mark.parametrize("save_events", [True, False])
-def test_continue_as_new(save_events: bool):
+@pytest.mark.parametrize("new_version", [None, "v2"])
+def test_continue_as_new(save_events: bool, new_version: str | None):
     """Tests the behavior of the continue-as-new API"""
     def orchestrator(ctx: task.OrchestrationContext, input: int):
         yield ctx.create_timer(ctx.current_utc_datetime + timedelta(days=1))
-        ctx.continue_as_new(input + 1, save_events=save_events)
+        ctx.continue_as_new(input + 1, save_events=save_events, new_version=new_version)
 
     registry = worker._Registry()
     orchestrator_name = registry.add_orchestrator(orchestrator)
@@ -1745,6 +1746,9 @@ def orchestrator(ctx: task.OrchestrationContext, input: int):
     complete_action = get_and_validate_complete_orchestration_action_list(1, actions)
     assert complete_action.orchestrationStatus == pb.ORCHESTRATION_STATUS_CONTINUED_AS_NEW
     assert complete_action.result.value == json.dumps(2)
+    assert complete_action.HasField("newVersion") == (new_version is not None)
+    if new_version is not None:
+        assert complete_action.newVersion.value == new_version
     assert len(complete_action.carryoverEvents) == (3 if save_events else 0)
     for i in range(len(complete_action.carryoverEvents)):
         event = complete_action.carryoverEvents[i]