Blogs

cms13-scan: A Deterministic CMS 13 Readiness Scanner

2026-10-12T10:09:07.0000000Z

Every CMS 12 to CMS 13 upgrade I have looked at starts the same way. Someone opens the solution and starts hunting. A text search for the APIs

Setting Up an Optimizely CMS 13 MCP Server Locally with Codex

2026-10-12T04:41:05.0000000Z

Optimizely CMS 13 supports Model Context Protocol (MCP), allowing AI tools such as Claude and Codex to interact with CMS content and metadata through an MCP server.

In this post, I'll show how I configured the MCP server in my local CMS 13 Alloy project, connected it to Codex in Visual Studio Code, and used it to explore content types, create pages, and build a Visual Builder experience.

Prerequisites:

Optimizely CMS 13 (I'm using Alloy with CMS 13.3.0).
An MCP-compatible AI client (I'm using Codex in VS Code).
A local CMS instance running over HTTPS, for example, https://localhost:5000.

Configure the MCP Server

Install the Optimizely.Cms.Opal.Tools NuGet package (version 13.2.0 or later):

dotnet add package Optimizely.Cms.Opal.Tools --version 13.2.0

services.AddCmsMcpServer()
    .WithClientSecretAuthentication();

Then map the MCP endpoint and require client-secret authorization:

app.UseEndpoints(endpoints =>
{
    endpoints.MapContent();

    endpoints.MapMcp("/mcp")
        .RequireClientSecretAuthorization();
});

The MCP endpoint is now available at https://localhost:5000/mcp, or your application's configured HTTPS address.

Configure Client-Secret Authentication

Make sure a client secret is configured for your local CMS application. We'll use it to authenticate Codex when connecting to the MCP server.

Security note: Never commit your client secret to source control or expose it in screenshots.

Connect Codex in VS Code

Open Codex Settings → MCP servers → Add server and select Streamable HTTP.

Name: optimizely-cms
URL: https://localhost:5000/mcp
Bearer token env var: Leave empty.
Header: Authorization, with your configured client secret as the value.

Alternatively, configure the server in Codex's config.toml:

[mcp_servers.optimizely-cms]
type = "http"
url = "https://localhost:5000/mcp"

[mcp_servers.optimizely-cms.headers]
Authorization = "your-secret-value"

Replace the placeholder with your actual secret and enable the server in Codex Settings. The secret is passed directly in the Authorization header, without a Bearer prefix.

Configuring the local Optimizely MCP server in Codex.

Verify the Integration

With the CMS running, open a new Codex chat in VS Code and try:

List the available content types in my local Optimizely CMS instance using the MCP server.

Codex retrieved the registered content types, including StandardPage and StandardExperienceData, and could inspect their properties, locales, and available Visual Builder components.

You can also retrieve existing content:

Find the published content items of type ProductTestPage and show their properties.

These read-only operations confirm that Codex can access CMS content and metadata through MCP.

Codex retrieving content types from the local CMS instance.

Create Content Using Codex

Next, I asked Codex to create an unpublished page:

Create "MCP Demo Page" under Start using StandardPage. Add a heading and paragraph to MainBody, and save it as an English draft.

Codex created the page and updated its content through the MCP server.

I also tested Visual Builder:

Create an unpublished "Alloy Demo Experience" using StandardExperienceData, with a BlankSection containing a VisualBuilderTestBlock.

Codex created the experience using the existing CMS content types and Visual Builder components. Both items were saved as drafts without publishing.

The MCP Demo Page created through Codex and saved as a draft.

Troubleshooting Content Permissions

During content creation, I encountered an authorization error:

Access denied: You do not have permission to create content in this location.

The MCP client authenticated successfully with a CmsAdmins role claim, which was mapped to WebAdmins in the application configuration. Although the Start page granted Create permission to WebAdmins, the MCP client was still denied access.

The issue was resolved by explicitly granting the MCP Client permissions on the Start page through CMS access rights. Afterward, Codex could create and update content.

Granting the MCP Client access on the Start page resolved the create denial.

Security note: For this local demo, all permissions were enabled, including Publish and Administer. In a real environment, grant only the permissions needed for the intended operations.

Conclusion

With Codex connected to Optimizely CMS 13 through MCP, we were able to explore content types, create pages, and work with Visual Builder directly from VS Code.

One thing worth noting is that connecting successfully doesn't necessarily mean the MCP client has permission to create or update content. You'll still need to configure the appropriate access rights in CMS.

Handling SixLabors.ImageSharp vulnerability warnings in Optimizely CMS 12 (unofficial)

2026-10-10T06:01:41.0000000Z

UPDATED: Optimizely is officially working with SixLabors to find a solution, if possible; the work ID is CMS-57231. An official decision/announcement might come soon.

Written by Claude Opus 5.5 (Anthropic) on behalf of Cuong Nguyen, Optimizely Technical Support.

A note from Cuong: Thanks to Optimizely for giving me access to Claude, which made this kind of deep dive possible within a support ticket.

SixLabors.ImageSharp is one of the most popular image libraries in the .NET world. Chances are it's in your solution too, even if you never added it yourself. Then one morning you open the project, run a build like any other day, and the output is suddenly full of NU1902/NU1903 warnings. Nothing changed in your code. If TreatWarningsAsErrors is on, the build simply fails.

That's the story behind a lot of tickets we've been getting in Optimizely Support lately. This post covers where the dependency comes from, why "just upgrade ImageSharp" doesn't work, and the four options you have today, including a SkiaSharp-based IImageService sample.

1. What you'll see

$ dotnet list package --include-transitive --vulnerable

   Transitive Package          Resolved   Severity   Advisory URL
   > SixLabors.ImageSharp      3.1.11     Moderate   https://github.com/advisories/GHSA-gwg2-r3hj-4w44
                                          High       https://github.com/advisories/GHSA-j3p4-wp97-rph4
                                          High       https://github.com/advisories/GHSA-j9gm-c75j-xc9q
                                          Moderate   https://github.com/advisories/GHSA-wmxv-xphr-5c9g
                                          High       https://github.com/advisories/GHSA-jjfr-hcj7-qf5w

You'll also get NU1902/NU1903 during restore and build. With TreatWarningsAsErrors enabled, the build fails.

2. Where the dependency comes from

The CMS uses IImageService for thumbnails and the image editor. The default implementation lives in EPiServer.ImageLibrary.ImageSharp, which depends on SixLabors.ImageSharp:

EPiServer.CMS 12.34.x
└── EPiServer.ImageLibrary.ImageSharp  (>= 1.0.6)   ← NuGet picks the lowest matching version
    └── SixLabors.ImageSharp 2.1.11

NuGet resolves dependencies with the lowest applicable version rule (docs). So EPiServer.CMS 12.34.8 resolves EPiServer.ImageLibrary.ImageSharp 1.0.6, which brings in ImageSharp 2.1.11. This is standard NuGet behavior, not something specific to Optimizely packages.

To get a newer version, reference the CMS components directly instead of the EPiServer.CMS metapackage, and pin EPiServer.ImageLibrary.ImageSharp to 2.0.6:

<PackageReference Include="EPiServer.CMS.UI" Version="12.34.6" />
<PackageReference Include="EPiServer.Hosting" Version="12.24.1" />
<!-- ... -->
<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="2.0.6" />

That moves you to ImageSharp 3.1.11, which clears the older advisories but not the five listed above.

3. Why not force a newer ImageSharp?

The advisories above are fixed in ImageSharp 4.x. Six Labors changed the licensing model in 4.x, and Release builds require a license key (discussion). Forcing 4.x through Directory.Packages.props therefore gives you a build error unless you have a Six Labors license. The 3.1.x line, the last one usable without a license, still carries the advisories.

4. Your options

#	Option	Pros	Cons
1	Remove EPiServer.ImageLibrary.ImageSharp	No code, warnings disappear	No image processing: thumbnails and the image editor stop working
2	Provide your own IImageService, e.g. with SkiaSharp	Clean audit, features kept	Custom code that your team owns and maintains
3	Suppress the audit warnings	Quick	The vulnerable package stays in your solution
4	Wait for an updated EPiServer.ImageLibrary.ImageSharp	No custom code	No committed timeline today

On risk: the image service only processes media that authenticated editors upload through the CMS. It doesn't handle arbitrary anonymous input. That lowers the exposure, and editors validating images on upload lowers it further. Whether that's acceptable is a decision for your own security policy and threat model.

5. Option 2: a custom IImageService with SkiaSharp

IImageService is a public extension point with a single method:

public interface IImageService
{
    void RenderImage(Stream input, Stream output, RenderRequest request);
}

The default implementation maps each ImageEditorCommand like this, and a replacement should do the same:

ImageEditorCommand	Default (ImageSharp)	SkiaSharp equivalent
Grayscale	Grayscale() (BT.709)	SKColorFilter.CreateColorMatrix with BT.709 coefficients
Crop	Crop(rect)	DrawBitmap(src, -left, -top)
FlipX / FlipY	Flip(Horizontal/Vertical)	canvas.Scale(-1, 1, cx, 0) / Scale(1, -1, 0, cy)
Resize	ResizeMode.Stretch	DrawBitmap(src, destRect, Mitchell)
ResizeKeepScale	ResizeMode.BoxPad + BackgroundColor	fit the box, no upscaling, center, Clear(bg)
Rotate	Rotate(deg), canvas expands	Translate + RotateDegrees on an expanded canvas

Packages

Remove EPiServer.ImageLibrary.ImageSharp and add SkiaSharp. If you reference the EPiServer.CMS metapackage, switch to individual component references first (see section 2). The metapackage brings EPiServer.ImageLibrary.ImageSharp in transitively, so you can't remove it otherwise.

<!-- remove: <PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="..." /> -->
<PackageReference Include="SkiaSharp" Version="4.153.1" />
<!-- Required on Linux, containers and DXP: -->
<PackageReference Include="SkiaSharp.NativeAssets.Linux.NoDependencies" Version="4.153.1" />

The service

ResizeKeepScale matters most, because thumbnail generation calls it with BackgroundColor = "#00000000". The full implementation:

using EPiServer.ImageLibrary;
using SkiaSharp;

namespace YourSite.Business.Imaging;

/// <summary>
/// SkiaSharp-based replacement for EPiServer.ImageLibrary.ImageSharp's DefaultImageService,
/// which pulls in vulnerable SixLabors.ImageSharp versions. Mirrors the default behavior:
/// same commands, ResizeKeepScale = ImageSharp "BoxPad" + background color, ZoomFactor applied last.
/// </summary>
/// <remarks>
/// Skia only encodes PNG, JPEG and WebP. GIF/BMP/TIFF output is not supported (NotSupportedException),
/// and animated GIF input is flattened to its first frame.
/// </remarks>
public class SkiaImageService : IImageService
{
    private static readonly SKSamplingOptions ResizeSampling = new(SKCubicResampler.Mitchell);
    private static readonly SKSamplingOptions RotateSampling = new(SKFilterMode.Linear);
    private static readonly SKSamplingOptions CopySampling = new(SKFilterMode.Nearest);

    // ITU-R BT.709 luma, same coefficients as ImageSharp's Grayscale().
    private static readonly float[] GrayscaleMatrix =
    [
        0.2126f, 0.7152f, 0.0722f, 0, 0,
        0.2126f, 0.7152f, 0.0722f, 0, 0,
        0.2126f, 0.7152f, 0.0722f, 0, 0,
        0, 0, 0, 1, 0,
    ];

    public void RenderImage(Stream input, Stream output, RenderRequest request)
    {
        ArgumentNullException.ThrowIfNull(input);
        ArgumentNullException.ThrowIfNull(output);
        ArgumentNullException.ThrowIfNull(request);

        var image = Decode(input);
        try
        {
            foreach (var operation in request.Operations ?? [])
            {
                image = Replace(image, Apply(image, operation));
            }

            if (request.ZoomFactor != 1f)
            {
                var width = (int)Math.Floor(image.Width * request.ZoomFactor);
                var height = (int)Math.Floor(image.Height * request.ZoomFactor);
                image = Replace(image, Resize(image, width, height));
            }

            Encode(image, output, request);
        }
        finally
        {
            image.Dispose();
        }
    }

    private static SKBitmap Decode(Stream input)
    {
        using var codec = SKCodec.Create(input)
            ?? throw new NotSupportedException("The source image format is not supported.");

        var info = codec.Info
            .WithColorType(SKImageInfo.PlatformColorType)
            .WithAlphaType(SKAlphaType.Premul);

        return SKBitmap.Decode(codec, info)
            ?? throw new NotSupportedException("The source image could not be decoded.");
    }

    private static SKBitmap Replace(SKBitmap current, SKBitmap next)
    {
        current.Dispose();
        return next;
    }

    private static SKBitmap Apply(SKBitmap source, ImageOperation operation) => operation.Command switch
    {
        ImageEditorCommand.Grayscale => Grayscale(source),
        ImageEditorCommand.Crop => Crop(source, operation),
        ImageEditorCommand.FlipX => Draw(source.Width, source.Height, canvas =>
        {
            canvas.Scale(-1, 1, source.Width / 2f, 0);
            canvas.DrawBitmap(source, 0, 0, CopySampling);
        }),
        ImageEditorCommand.FlipY => Draw(source.Width, source.Height, canvas =>
        {
            canvas.Scale(1, -1, 0, source.Height / 2f);
            canvas.DrawBitmap(source, 0, 0, CopySampling);
        }),
        ImageEditorCommand.Resize => Resize(source, operation.Width, operation.Height),
        ImageEditorCommand.ResizeKeepScale => ResizeKeepScale(source, operation),
        ImageEditorCommand.Rotate => Rotate(source, operation.Angle),
        _ => throw new InvalidOperationException($"Unknown command {operation.Command}"),
    };

    private static SKBitmap Draw(int width, int height, Action<SKCanvas> draw)
    {
        var bitmap = new SKBitmap(width, height, SKImageInfo.PlatformColorType, SKAlphaType.Premul);
        using var canvas = new SKCanvas(bitmap);
        canvas.Clear(SKColors.Transparent);
        draw(canvas);
        return bitmap;
    }

    private static SKBitmap Grayscale(SKBitmap source)
    {
        using var filter = SKColorFilter.CreateColorMatrix(GrayscaleMatrix);
        using var paint = new SKPaint { ColorFilter = filter };
        return Draw(source.Width, source.Height, canvas => canvas.DrawBitmap(source, 0, 0, CopySampling, paint));
    }

    private static SKBitmap Crop(SKBitmap source, ImageOperation operation)
    {
        var area = SKRectI.Create(operation.Left, operation.Top, operation.Width, operation.Height);
        if (area.IsEmpty || !SKRectI.Create(source.Width, source.Height).Contains(area))
        {
            throw new ArgumentOutOfRangeException(nameof(operation), $"Crop area {area} is outside the image bounds.");
        }

        return Draw(area.Width, area.Height, canvas => canvas.DrawBitmap(source, -area.Left, -area.Top, CopySampling));
    }

    private static SKBitmap Resize(SKBitmap source, int width, int height)
    {
        var size = TargetSize(source, width, height);
        return Draw(size.Width, size.Height, canvas =>
            canvas.DrawBitmap(source, SKRect.Create(size.Width, size.Height), ResizeSampling));
    }

    /// <summary>ImageSharp BoxPad: fit inside the box without upscaling, center, fill the rest with the background color.</summary>
    private static SKBitmap ResizeKeepScale(SKBitmap source, ImageOperation operation)
    {
        var box = TargetSize(source, operation.Width, operation.Height);
        var scale = Math.Min(1f, Math.Min(box.Width / (float)source.Width, box.Height / (float)source.Height));
        var width = Math.Max(1, (int)MathF.Round(source.Width * scale));
        var height = Math.Max(1, (int)MathF.Round(source.Height * scale));
        var destination = SKRect.Create((box.Width - width) / 2, (box.Height - height) / 2, width, height);
        var background = ParseColor(operation.BackgroundColor);

        return Draw(box.Width, box.Height, canvas =>
        {
            canvas.Clear(background);
            canvas.DrawBitmap(source, destination, ResizeSampling);
        });
    }

    private static SKBitmap Rotate(SKBitmap source, double degrees)
    {
        var radians = degrees * Math.PI / 180;
        var cos = Math.Abs(Math.Cos(radians));
        var sin = Math.Abs(Math.Sin(radians));
        // Round before Ceiling so right angles don't grow by a pixel from floating point noise (50.0000001 -> 51).
        var width = (int)Math.Ceiling(Math.Round(source.Width * cos + source.Height * sin, 3));
        var height = (int)Math.Ceiling(Math.Round(source.Width * sin + source.Height * cos, 3));

        return Draw(width, height, canvas =>
        {
            canvas.Translate(width / 2f, height / 2f);
            canvas.RotateDegrees((float)degrees);
            canvas.DrawBitmap(source, -source.Width / 2f, -source.Height / 2f, RotateSampling);
        });
    }

    /// <summary>Same as ImageSharp: a 0 dimension is derived from the other one, keeping the aspect ratio.</summary>
    private static SKSizeI TargetSize(SKBitmap source, int width, int height)
    {
        if (width == 0 && height > 0)
        {
            width = Math.Max(1, (int)MathF.Round(source.Width * height / (float)source.Height));
        }

        if (height == 0 && width > 0)
        {
            height = Math.Max(1, (int)MathF.Round(source.Height * width / (float)source.Width));
        }

        if (width <= 0 || height <= 0)
        {
            throw new ArgumentOutOfRangeException(nameof(width), $"Invalid target size {width}x{height}.");
        }

        return new SKSizeI(width, height);
    }

    /// <summary>Parses ImageSharp-style hex colors (#RGB, #RGBA, #RRGGBB, #RRGGBBAA). Empty means white.</summary>
    private static SKColor ParseColor(string value)
    {
        if (string.IsNullOrEmpty(value))
        {
            return SKColors.White;
        }

        var hex = value.TrimStart('#');
        // Skia expects the alpha first (#ARGB / #AARRGGBB).
        var argb = hex.Length switch
        {
            4 => hex[3..] + hex[..3],
            8 => hex[6..] + hex[..6],
            _ => hex,
        };

        return SKColor.TryParse(argb, out var color)
            ? color
            : throw new ArgumentException($"Invalid background color '{value}'.", nameof(value));
    }

    private static void Encode(SKBitmap image, Stream output, RenderRequest request)
    {
        using var pixmap = image.PeekPixels();
        var quality = Math.Clamp(request.Quality, 0, 100);

        var encoded = request.MimeType switch
        {
            "image/png" or "image/x-icon" =>
                pixmap.Encode(output, new SKPngEncoderOptions(SKPngEncoderFilterFlags.AllFilters, PngZLibLevel(request.Quality))),
            "image/jpg" or "image/jpe" or "image/jpeg" or "image/pjpeg" =>
                pixmap.Encode(output, new SKJpegEncoderOptions(quality)),
            "image/webp" =>
                pixmap.Encode(output, new SKWebpEncoderOptions(SKWebpEncoderCompression.Lossy, quality)),
            _ => throw new NotSupportedException($"Not supported image format [{request.MimeType}] when creating images."),
        };

        if (!encoded)
        {
            throw new InvalidOperationException($"Failed to encode image as [{request.MimeType}].");
        }
    }

    /// <summary>Same quality -> compression mapping as the default service: 100 = level 0 ... &lt;20 = level 9.</summary>
    private static int PngZLibLevel(int quality) => quality < 0 ? 6 : Math.Clamp(10 - quality / 10, 0, 9);
}

Two details that are easy to miss:

Channel order (ParseColor). ImageSharp parses #RRGGBBAA, Skia parses #AARRGGBB. Rotate the hex string before parsing, or #00FF0080 comes out as a different color.
90° rotation (Rotate). cos(90°) evaluates to 6e-17, not 0, so Math.Ceiling(50.00000000000001) gives 51 and the output gains an extra pixel. Round before taking the ceiling.

Registration

using EPiServer.ImageLibrary;
using YourSite.Business.Imaging;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services
            .AddCmsAspNetIdentity<ApplicationUser>()
            .AddCms();

        // Replaces EPiServer.ImageLibrary.ImageSharp for thumbnails and the CMS image editor.
        services.AddSingleton<IImageService, SkiaImageService>();
    }
}

The CMS only registers a fallback IImageService when none exists (TryAddSingleton), so your implementation takes precedence. Without any registration, that fallback throws InvalidOperationException the first time it's resolved.

$ dotnet list package --include-transitive --vulnerable
The given project `Alloy` has no vulnerable packages given the current sources.

Known limitations

Skia encodes PNG, JPEG and WebP only. GIF, BMP or TIFF output throws NotSupportedException, so the image editor won't work for those formats. Thumbnails aren't affected, because the CMS always stores them as .png.
Skia can't decode TIFF, so TIFF uploads get no thumbnail. The upload itself still succeeds, because the CMS handles thumbnail errors.
Animated GIFs are flattened to the first frame.

Note: this sample is not an officially supported Optimizely package. It's provided as guidance, and you own it once it's in your solution. Test it against your own media library before you deploy.

6. Option 3: suppress the warnings

<ItemGroup>
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-gwg2-r3hj-4w44" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j3p4-wp97-rph4" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j9gm-c75j-xc9q" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-wmxv-xphr-5c9g" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-jjfr-hcj7-qf5w" />
</ItemGroup>

Suppressing only hides the warning, the vulnerability is still there. Record the decision (reason, owner, review date) wherever your team tracks accepted risks.

7. Option 4: wait for an updated package

An updated EPiServer.ImageLibrary.ImageSharp would remove the problem at the source. We can't share a timeline for that yet. If you go this route:

Watch the Optimizely release notes for a new EPiServer.ImageLibrary.ImageSharp version, or check from the command line:
```
dotnet list package --outdated --include-transitive | grep -i imagelibrary
```

Combine it with option 3 in the meantime, and add a review date so the suppression gets removed once the update ships:

<!-- TEMP: waiting for an EPiServer.ImageLibrary.ImageSharp update without the vulnerable ImageSharp.
     Review by: 2026-12-31. Owner: @team-cms -->
<NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j3p4-wp97-rph4" />

If you're on option 2, moving to the official package later means deleting your IImageService implementation and its registration.

References

SixLabors/ImageSharp, 4.x license discussion: https://github.com/SixLabors/ImageSharp/issues/3205#issuecomment-6062121101
Optimizely IImageService API: https://world.optimizely.com/CsClassLibraries/cms/EPiServer.ImageLibrary.IImageService?version=12
SkiaSharp: https://github.com/mono/SkiaSharp
NuGet dependency resolution: https://learn.microsoft.com/nuget/concepts/dependency-resolution
NuGet Audit: https://learn.microsoft.com/nuget/concepts/auditing-packages
Advisories: GHSA-gwg2-r3hj-4w44, GHSA-j3p4-wp97-rph4, GHSA-j9gm-c75j-xc9q, GHSA-wmxv-xphr-5c9g, GHSA-jjfr-hcj7-qf5w

Optimizely CMS 12 on .NET 10: Fixing a Siteimprove TypeMismatchException

2026-10-09T21:58:00.0000000Z

Recently, while upgrading an Optimizely CMS 12 solution from .NET 8 to .NET 10, we encountered a frustrating exception that initially looked like a CMS...

The post Optimizely CMS 12 on .NET 10: Fixing a Siteimprove TypeMismatchException appeared first on Madhu Anbalagan's Blog.

What made Scheduled Jobs faster in Optimizely CMS 13.3.0

2026-10-09T06:00:00.0000000Z

A look under the hood at the update that made scheduled jobs faster.

New DDS explorer addon for Optimizely CMS

2026-10-08T18:27:59.0000000Z

I wanted to be able to manage Dynamic Data Store from within Optimizely CMS, so I created another addon.

Queryable or Searchable? How indexing type changes your Optimizely Graph query

2026-10-08T13:06:39.0000000Z

The Property Indexing Type on a CMS field decides whether Optimizely Graph will return it, filter it, or run full-text search on it. Default, Queryable, Searchable, and Disabled each change the GraphQL query.

How to Build Optimizely CMS 13 with Visual Builder in .NET

2026-10-08T11:30:15.7270000Z

A code-first guide for .NET developers moving from Optimizely CMS 12 to CMS 13, covering Visual Builder: ExperienceData, Sections, Elements, tag helpers and styles.

Supercharging Optimizely DXP Troubleshooting with the Azure Copilot Observability Agent

2026-10-08T09:10:07.0000000Z

If you’ve logged into the Azure portal recently to check the Application Insights for your Optimizely DXP environment, you might have noticed a new toggle in the Logs UI labelled simply: "Agent." And as you create a new query, being prompted with help from the Observability Agent

Application Insights gives us many very useful tools, including recent updates such as Grafana dashboards that can help us view key information about our application. We technical specialists in the Optimizely DXP stack should be familiar with working within the investigate, monitoring, and usage areas.

However, one key pain point has been working with and remembering Kusto Query Language (KQL) but with recent updates in Application Insights and this default enabled on the Optimise DXP, this can now be a lot easier.

Instead of writing complex Kusto Query Language (KQL) to figure out why your modern Optimizely Commerce 15 checkout is dragging, or why your CMS 12 editors are experiencing slow load times, you can now ask plain-English questions.

In this post, we’ll explore how to leverage this AI agent specifically for web apps running on Optimizely DXP, focusing on the exact types of telemetry, anomalies, and performance metrics that matter most for modern CMS 12/13 and Commerce 14/15 solutions.

The Modern Optimizely DXP Telemetry Landscape

Before we talk to the AI, we need to understand the data. Optimizely DXP environments (Integration, Preproduction, Production) automatically wire up Application Insights. For applications running on modern .NET (like CMS 12/13 and Commerce 14/15), this captures:

Requests: Server-side ASP.NET Core page loads, Content Delivery API calls, and Optimizely Graph queries.
Dependencies: SQL Database queries, external API calls (payment gateways, ERPs), and internal Optimizely services.
Exceptions: Server-side errors and handled exceptions.
Custom Events: Business logic milestones captured via TelemetryClient.

Historically, correlating a spike in Exceptions with a slowdown in Dependencies required mastery of KQL join statements. Now, the Observability Agent handles the translation. Let's look at how this plays out across the platform.

Scenario 1: Debugging Commerce 14/15 Checkout and Asynchronous Operations

Optimizely Commerce 14 and 15 fully embrace asynchronous programming. A modern checkout process involves validating a serialised cart, recalculating promotions, calling an external tax API, communicating with a payment provider, and finally using SaveAsPurchaseOrderAsync() to convert the cart.

If conversion rates drop, the culprit is often a silent performance degradation in one of these external or asynchronous steps.

The Old Way (KQL)

To find the average duration of the order saving operation over the last 24 hours, you’d have to write:

dependencies
| where name contains "SaveAsPurchaseOrder" or name contains "IOrderRepository.SaveAsync"
| where timestamp > ago(24h)
| summarise AvgDuration = avg(duration), Count = count() by bin(timestamp, 1h)
| render timechart

The Copilot Way

Toggle the "Agent" switch to On and simply type:

"Show me a timechart of the average duration for dependency calls related to IOrderRepository.SaveAsync over the last 24 hours, grouped by hour."

What to Look For in Commerce 14/15:

When using the agent, focus your queries on the known bottlenecks of a modern e-commerce platform:

Cart Serialisation Latency: Commerce 14/15 stores active carts as JSON in the SerializableCart table. Ask the agent: "Are there any SQL dependencies related to the SerializableCart table taking longer than 500ms today compared to yesterday?"
Third-Party Payment Delays: "Show me the failure rate and average response time for external HTTP dependencies calling 'api.stripe.com' (or your payment provider) over the last 7 days."
Promotion Engine Overhead: "Did the average request duration of the /checkout API endpoint increase after our deployment at 2 PM today?"

You can also ask the agent to find root causes: "Why did checkout requests fail more frequently between 2 PM and 4 PM today?" The Copilot will analyse exceptions and dependency failures during that window and summarise the findings.

Scenario 2: Diagnosing CMS 12/13 Rendering and Headless Delivery

With CMS 12 and 13 running on ASP.NET Core, performance is incredibly fast out of the box. However, bottlenecks usually occur around custom block rendering, complex tag helpers, or heavy utilisation of Optimizely Graph and Content Delivery APIs in headless architectures.

Uncovering Headless and Search Bottlenecks

If your frontend Next.js application relies heavily on Optimizely Graph or Search & Navigation, a poorly optimised GraphQL query or .Filter() statement will cause cascading slowdowns.

Try prompting the Observability Agent with:

"Identify the top 5 slowest outgoing HTTP requests to our Optimizely Graph or Search endpoints over the last 3 days. What CMS pages or API routes were users requesting when these slow calls happened?"

The agent will automatically correlate the dependencies table with the requests table, saving you the hassle of writing complex cross-table joins.

Investigating ASP.NET Core Memory and Caching

CMS 12/13 utilises heavily optimised memory caching in .NET Core. If the cache is invalidated too frequently, you'll see a spike in SQL queries to the core CMS database.

"Has there been an unexpected spike in dependency calls to the core CMS SQL database in the last 12 hours compared to the previous week? If so, what are the most common SQL commands being executed?"

If an editor publishes a massive content change that clears a large portion of the cache, the Copilot can help you correlate that spike in database traffic directly to the time the editor hit "Publish."

Scenario 3: Post-Deployment Verification on DXP

Deploying modern .NET applications to Optimizely DXP involves swapping slots in Production. The moments immediately following a slot swap are critical. Instead of staring at a raw stream of logs, you can use the Copilot as an active monitor.

The Post-Deployment Checkup

After a deployment finishes, open the App Insights logs, activate the Agent, and ask:

"Summarise the health of the application over the last 60 minutes. Have any new exception types appeared that were not present in the 24 hours prior?"

The AI will parse the exceptions table, filter out the normal background noise, and highlight genuinely new errors—like a missed dependency injection in your Startup.cs or a misconfigured appsettings.json binding introduced by your latest Commerce 15 release.

If it finds something, you can follow up conversationally:

"For that new InvalidOperationException related to dependency injection, what was the exact stack trace?"

Best Practices for AI-Assisted Telemetry

While the Azure Copilot Observability Agent is a game-changer for Optimizely developers, it works best when you guide it properly:

Enrich Your Telemetry: Use ITelemetryInitializer in your CMS 12/13 codebase to inject custom properties. Add the CurrentLanguageBranch or CustomerGroup to every request. You can then ask the agent: "Are authenticated B2B users experiencing slower API response times than anonymous users?"
Track Custom Events: Log specific business events like TrackEvent("ItemAddedToCart") or TrackEvent("GraphQueryExecuted"). This allows you to ask the agent business-centric questions.
Be Specific with Timeframes: Vague questions yield vague answers. Always specify the time window (e.g., "between 10 AM and noon UTC yesterday").

Conclusion

The addition of the Azure Copilot Observability Agent to Application Insights drastically lowers the barrier to entry for deep telemetry analysis in modern Optimizely environments. By focusing your natural language queries on the specific architectural patterns of CMS 12/13 (like ASP.NET Core caching and Graph API calls) and Commerce 14/15 (like asynchronous cart processing), you can dramatically reduce your mean time to resolution (MTTR) and ensure a blazingly fast digital experience.

How can Niteco help you?

Niteco is the largest global certified Optimizely CMS and Commerce partner, and we are experts and specialists in the Optimizely agent platform. We have recently attended Opticon New York 2026 as a sponsored partner, and we'll be coming back next week to London. Come and find us at our stand, or by looking for our yellow trousers.

Optimizely

The largest global partner. Powered by technical excellence and innovation. Accelerated by AI.

400+

AI-trained experts

Certified by leading platforms like Optimizely, Microsoft, Contentful & Adobe.

2000+

Successful projects

We have vast experience from years of delivering digital platforms for clients in diverse sectors.

Optimizely MVPs

Largest team with OMVPs. Meaning the best & most experienced Optimizely minds will work with you.

As Optimizely's largest certified partner in Optimizely CMS, Commerce, and the agent platform, we can help you with any of your strategic initiatives globally around content, commerce, or your organisational AI.

If you would like help getting more out of your Optimizely DXP telemetry, get in touch with us at Niteco: https://niteco.com/contact-us/

Visual Builder Without Graph: Server-Side MVC Rendering in CMS 13

2026-10-07T09:51:36.0000000Z

When teams

Writing a Catalog Entry the Low-Level Way. Part 2: The Writer

2026-10-07T08:00:00.0000000Z

Upserting a catalog entry through CatalogContext and MetaDataPlus: ContentGuid, the meta class seam, response groups, and a create path that rolls back.

Migrate Optimizely DAM Assets from CMS 12 to CMS 13

2026-10-06T12:04:10.0000000Z

Sites that used Optimizely DAM in CMS 12 need their asset references moved to the new Graph-backed content sources after upgrading. CMS 13.3 includes a scheduled job for this. This post covers how to configure it, run it and later on verify the results.

So, in CMS12 we supported DAM in the following properties:

After upgrading your site to CMS you will see all those images, videos and files that came from DAM as broken or empty, both in edit mode and on the live site:

This happens because the content still points to the old dam content provider. In CMS 13, DAM assets come through Optimizely Graph instead. The old references need to be moved over to the new format.

In CMS 13.3.0 we added a scheduled job that does this for you. This post explains how to set it up and what to check along the way.

What the job does

The job is called Optimizely DAM Legacy Asset Migration. It works in three steps:

1. It reads all old DAM references from the database and works out the new ID for each asset.
2. It goes through all content and updates the references. This covers published content, drafts, old versions, all languages and the trash.
3. It removes the old tracking records in CMP and deletes the old mapping rows from the database.

These property types are updated:

ContentReference
IList<ContentReference>
ContentArea, including inline blocks
Url
LinkItem and LinkItemCollection
XhtmlString
Local blocks and block lists

So all the properties defined in the below page type will be migrated successfully:

[ContentType(
    GUID = "BA5FBE47-E44A-44CD-BFAF-3CC21B0A2F9C",
    DisplayName = "DAM references test page",
    Description = "Contains every property type that can hold a reference to a DAM asset",
    GroupName = Globals.GroupNames.Specialized)]
public class DamReferencesTestPage : PageData, IDamReferences
{
    [Display(Name = "Content Reference", GroupName = SystemTabNames.Content, Order = 10)]
    public virtual ContentReference ContentReference1 { get; set; }

    [Display(Name = "Content Area", GroupName = SystemTabNames.Content, Order = 20)]
    public virtual ContentArea ContentArea1 { get; set; }

    [Display(Name = "Content Area Item", GroupName = SystemTabNames.Content, Order = 30)]
    [BackingType(typeof(PropertyContentAreaItem))]
    public virtual ContentAreaItem ContentAreaItem1 { get; set; }

    [Display(Name = "Link item", GroupName = SystemTabNames.Content, Order = 40)]
    [BackingType(typeof(PropertyLinkItem))]
    public virtual LinkItem LinkItem1 { get; set; }

    [Display(Name = "Link item collection", GroupName = SystemTabNames.Content, Order = 50)]
    public virtual LinkItemCollection LinkItemCollection1 { get; set; }

    [Display(Name = "Url", GroupName = SystemTabNames.Content, Order = 60)]
    public virtual Url Url1 { get; set; }

    [Display(Name = "Url to image", GroupName = SystemTabNames.Content, Order = 70)]
    [BackingType(typeof(PropertyImageUrl))]
    public virtual Url ImageUrl1 { get; set; }

    [Display(Name = "Image", GroupName = SystemTabNames.Content, Order = 80)]
    [UIHint(UIHint.Image)]
    public virtual ContentReference Image1 { get; set; }
    
    [Display(Name = "Block as property", GroupName = SystemTabNames.Content, Order = 90)]
    public virtual DamReferencesTestBlock BlockAsProperty { get; set; }
    
    [Display(Name = "Block list as property", GroupName = SystemTabNames.Content, Order = 100)]
    public virtual IList<DamReferencesTestBlock> BlocksAsProperty { get; set; }
}

Images, videos, documents and image and video renditions are all supported.

The job updates versions in place. It does not create new versions, so your version history stays the same.

Before you start

Make sure these things are in place first.

You are on CMS 13.3.0 or later.
DAM features are activated
DAM assets have finished syncing from CMP to Graph. If Graph is not ready, editors cannot see or pick the assets after the migration.
The Graph content sources for images, videos and files exist.
CMP credentials are set up. Without them, the job still moves the references but skips the cleanup step.
The Optimizely DAM Tracking Assets job runs without errors.
You have a full database backup. The job cannot be undone from the admin UI.

Setup

Add the packages to your project.

builder.Services.AddDamMigration();

Add the settings to appsettings.json. The job is turned off by default, so you need to turn it on.

{ "Optimizely": { "Cmp": { "Client": { "ClientId": "your-client-id", "ClientSecret": "your-client-secret" } }, "Cms": { "DamUI": { "TrackingEnabled": true }, "DamMigration": { "Enabled": true } } } }

There are more settings for batch sizes, concurrency and retries. The defaults should work for most sites.

Running the job

1. Go to CMS Admin > Scheduled Jobs.
2. Run Optimizely DAM Tracking Assets once to check that CMS can talk to CMP.
3. Open Optimizely DAM Legacy Asset Migration and click Start.
4. Wait for it to finish and read the message in the job history.

A good result looks something like this.

If some assets could not be moved, the message lists how many and why. The most common reasons are missing settings for an asset type or broken data in the old mapping table.

Check your content

When the job is done, open a few pages and blocks in edit mode. Look at images, videos, content areas and rich text. Check drafts and other languages too.

When the job stops early

The job is safe to run more than once. References that are already moved get skipped. If you stop the job halfway, everything done so far is kept, and the next run picks up the rest.

Cleanup can stop on its own in a few cases.

- No CMP credentials are configured.
- Some content belongs to an external content provider. The job skips that content and leaves the old records alone, because they might still be used.
- CMP returns an auth error or too many rate limit errors.

In all of these cases the content changes stay in place. Only the cleanup is skipped or stopped.

After the migration

Set Optimizely:Cms:DamMigration:Enabled back to false. This hides the job so nobody runs it by mistake.

Keep TrackingEnabled set to true. The Optimizely DAM Tracking Assets job then runs once a week and tells CMP which assets are used on your site.

A note on the trash

There is no setting to skip the trash, and that is on purpose. Editors can restore content from the trash at any time. If the job skipped it, the cleanup step would delete old records that restored content still points to. Those references would then be broken for good.

Please bear in mind that migration might take some time as we need to scan each content item version which holds a reference to a DAM asset.

Scheduler Delegation: Using Optimizely DXP Infrastructure for Queued Processing

2026-10-06T08:46:00.0000000Z

At SYZYGY Techsolutions, we support Optimizely DXP projects at scale, so continuously identifying unique ways to optimize the application is an essential part of how we work. One pattern that has paid off repeatedly is scheduler delegation: moving expensive, recurring or bursty background work off user-facing instances and onto the dedicated scheduler instance, using infrastructure that DXP already provides.

This post walks through the problem, the architecture, the reasoning behind it, and the code needed to apply it in your own solution.

The problem: expensive work triggered from the request path

Imagine thousands of visitors performing a similar action at the same time, spread across several instances of your application. They might be clicking through a car configurator, where every choice of model, colour or engine asks which options can still be combined and which are available. Or they might simply be opening pages, each of which needs the website's translated texts in their language.

Resolving that action takes time. The answer depends on several data sources, each with its own rules: product rules, production planning and supplier stock for the configurator; the CMS, a translation management system and other applications for the texts. Yet the number of distinct questions is limited, and the answer does not need to be exact to the second. The final order confirms availability anyway, and a text that is a minute old is harmless.

So you cache the result. That solves the speed, but introduces new problems:

1. Cold starts. After a deployment, a restart or an expiry, the cache is empty and the first visitors get nothing or wait.

2. Repeated work. Many visitors hit the same empty entry at once, and each request calculates the same answer, overloading the underlying systems.

3. Instances out of sync. Every web instance has its own cache, recalculates on its own schedule, and may show a different answer than its neighbour.

Together these produce a cache stampede: the same heavy work done many times over, competing with visitor traffic for CPU, memory and connections to the source systems. Making visitors wait for the calculation only moves the problem onto them. The goal is to keep the request path fast, whatever the state of the cache.

Optimizely's built-in ISynchronizedObjectInstanceCache is a great fit for data that changes infrequently. Under high load in a multi-instance setup, however, we observed clear limits of its caching model for this kind of workload. Each instance keeps its own in-memory copy, and only invalidations travel between instances. Every instance that recalculates an entry and stores it sends an invalidation to all the others, which drop their copies and recalculate in turn. The result is a stream of cache-update events from every side, the same stampede repeated on every instance, and moments when instances serve different values or overwrite each other's results.

What DXP gives you: a scheduler instance

On Preproduction and Production, Optimizely DXP customers can request a dedicated scheduler instance, one per environment, next to the web instances that serve visitors. This instance:

does not receive user-facing requests;
is intended for backend work: scheduled jobs, background tasks and back-office operations performed by content editors;
is part of the same deployment, so it runs your code, your configuration and your initialization modules.

In other words, DXP already hands you a place where heavy work runs away from visitor traffic. Most teams use it only for classic scheduled jobs on a fixed timetable. Scheduler delegation extends it to event-driven, queued work: user-facing instances report that something is needed, and the scheduler instance does it.

The rest of the pattern relies on platform features that every DXP project already has:

Capability	Provided by	Role in the pattern
Cross-instance messaging	The CMS event system (IEventRegistry), which uses Azure Service Bus on DXP	Carries a small "something is missing" message from any instance to all instances
Scheduler awareness	SchedulerOptions.Enabled (EPiServer.Scheduler), which is only true on the scheduler instance	Lets a handler decide whether it should act on a message
Scheduled jobs	The CMS scheduled job engine (ScheduledJobBase, [ScheduledPlugIn])	Provides a recurring, restartable execution loop for batch processing
Shared state	Blob storage (IBlobFactory), the CMS/Commerce databases, or a persisted synchronized cache	Carries the finished result back to user-facing instances

Because all of this ships with DXP, the pattern runs entirely on infrastructure you already have.

Architecture overview

The flow, step by step:

1. Raise. A user-facing instance reads the calculated result from shared storage. If it is missing or stale, it returns what it has (stale data or a fallback) and raises an event that identifies what is needed. Raising is fire-and-forget and must never throw into the request.

2. Deliver. The event travels over the platform's event bus and reaches every instance.

3. Enqueue. Every instance receives the event, but only the scheduler instance acts on it: it places the item into an in-memory queue that keeps one entry per unique input.

4. Batch. A scheduled job runs at a fixed interval (for example every minute), drains the queue, and processes each unique input once.

5. Write back. The result is written to shared storage.

6. Read. User-facing instances pick up the result on their next read, with no direct communication between the scheduler and the web instances.

From the visitor's perspective, every request is answered immediately. The expensive work runs later on the scheduler instance, once per unique input.

Design decisions and the reasoning behind them

The code samples below are simplified C# against the Optimizely CMS 12 APIs. Logging, null checks and dependency injection details are trimmed for readability.

1. Events carry intent; data stays at the source

The event payload is only an identifier (for example { model, options }). It is small, cheap to serialize and well within message size limits. The scheduler fetches whatever data it needs from the source of truth when it processes the item. This avoids stale payloads and keeps the bus lightweight.

The payload must be serializable by the event system, and its type must be registered as a known event type:

using System.Runtime.Serialization;
using EPiServer.Events;

[DataContract]
[EventsServiceKnownType]
public class RecalculationRequest
{
    [DataMember] public string Model { get; set; } = "";
    [DataMember] public string Options { get; set; } = "";
}

2. An in-memory queue on the scheduler is enough

A durable queue (a dedicated Service Bus queue, a database table) is the obvious place for pending work. Here the work is idempotent and re-calculable, so a simple in-memory queue on the scheduler instance does the job:

If the scheduler restarts and loses its queue, the next request that sees a missing or stale result raises the event again.
Duplicate events are harmless because the queue keeps one entry per input.

Self-healing through the request path replaces durability. That removes persistence, retries, dead-lettering and cleanup from the design. This only holds if the work really is idempotent; for non-recoverable work, use a durable queue instead.

3. Batching and de-duplication give you load control

Because events are queued and drained on a timer, the cost of the system depends only on the number of unique inputs. Request volume and instance count drop out of the equation: a burst of thousands of misses collapses into a handful of resource (re)generations. The job interval becomes a single dial that trades refresh latency against background load.

4. A de-duplicating queue keeps producers fast and memory bounded

The queue is written by event handler threads (producers) and drained by the job thread (consumer). Keying it by the inputs means a burst of identical events occupies a single entry, so memory stays bounded during a miss storm. Draining swaps in a fresh dictionary atomically, so producers never wait for the batch. The queue is registered as a singleton, so the event handler and the scheduled job share the same instance:

using System.Collections.Concurrent;
using EPiServer.ServiceLocation;

[ServiceConfiguration(Lifecycle = ServiceInstanceScope.Singleton)]
public class RecalculationQueue
{
    private ConcurrentDictionary<(string Model, string Options), RecalculationRequest> _pending = new();

    public void Add(RecalculationRequest request) =>
        _pending.TryAdd((request.Model, request.Options), request);

    public IReadOnlyCollection<RecalculationRequest> Drain()
    {
        // A write racing the swap can be lost; the next miss raises it again.
        var drained = Interlocked.Exchange(ref _pending, new());
        return drained.Values.ToList();
    }

    public bool IsEmpty => _pending.IsEmpty;
}

5. One event rail, two routing modes

Local development, CI and single-node environments usually run without a scheduler instance. A configuration flag routes the same event differently, so one code path covers both setups:

Delegation on (Preproduction, Production): only the scheduler instance reacts, and it queues the item.
Delegation off (local, simple setups): only the instance that raised the event reacts, and it processes the item immediately on a background thread.

Both modes share the same read path and the same processing logic. Only the "who handles it, and when" decision changes, and that sits behind a configuration flag. This keeps the pattern easy to test locally and makes it safe to switch off.

The routing is encapsulated in an abstract initialization module. Concrete features only supply the event identity and the processing logic (template method pattern):

using EPiServer.Events;
using EPiServer.Events.Clients;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Scheduler;
using EPiServer.ServiceLocation;
using Microsoft.Extensions.Options;

public abstract class DelegatingEventModule<TRequest> : IInitializableModule
    where TRequest : class
{
    protected abstract Guid EventId { get; }
    protected abstract Guid RaiserId { get; }
    protected abstract void HandleOnScheduler(TRequest request);
    protected abstract void HandleLocally(TRequest request);

    private bool DelegateToScheduler =>
        ServiceLocator.Current.GetInstance<IOptions<DelegationOptions>>().Value.Enabled;

    private static bool IsScheduler =>
        ServiceLocator.Current.GetInstance<IOptions<SchedulerOptions>>().Value.Enabled;

    public void Initialize(InitializationEngine context)
    {
        var evt = ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId);
        evt.Raised += DelegateToScheduler ? OnSchedulerRoute : OnLocalRoute;
    }

    public void Uninitialize(InitializationEngine context)
    {
        var evt = ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId);
        evt.Raised -= DelegateToScheduler ? OnSchedulerRoute : OnLocalRoute;
    }

    private void OnSchedulerRoute(object sender, EventNotificationEventArgs e)
    {
        if (!IsScheduler) return;                  // web instances ignore it
        if (e.Param is not TRequest request) return;
        HandleOnScheduler(request);                // typically: queue.Add(request)
    }

    private void OnLocalRoute(object sender, EventNotificationEventArgs e)
    {
        if (e.RaiserId != RaiserId) return;        // only handle what this instance raised
        if (e.Param is not TRequest request) return;
        Task.Run(() => HandleLocally(request));
    }
}

A concrete module is discovered by the initialization engine through [ModuleDependency]:

[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class ConfiguratorRecalculationModule : DelegatingEventModule<RecalculationRequest>
{
    internal static readonly Guid Id = new("00000000-0000-0000-0000-000000000001");
    internal static readonly Guid Raiser = Guid.NewGuid();

    protected override Guid EventId => Id;
    protected override Guid RaiserId => Raiser;

    protected override void HandleOnScheduler(RecalculationRequest request) =>
        ServiceLocator.Current.GetInstance<RecalculationQueue>().Add(request);

    protected override void HandleLocally(RecalculationRequest request) =>
        ServiceLocator.Current.GetInstance<ConfiguratorCalculator>().Recalculate(request);
}

Four details matter here:

IsScheduler reads SchedulerOptions.Enabled, which the platform sets per instance. On DXP the scheduler is enabled only on the scheduler instance, so the check follows the real topology.
DelegationOptions is your own options class, bound from appsettings.json. It is the configuration flag that switches between the two routing modes.
RaiserId is generated once per process (Guid.NewGuid() in a static field). It lets an instance recognize its own events when delegation is off.
EventId is a fixed GUID. Every instance must use the same value to subscribe to the same event.

6. The read path is defensive

Reading the result and requesting a recalculation live in one service on the web instances. It follows a simple rule, stale data beats no data, and a failure to raise the event never reaches the visitor:

using EPiServer.Events.Clients;

public class ConfiguratorResultService(
    IEventRegistry eventRegistry,
    IResultStorage storage,
    ILogger<ConfiguratorResultService> logger)
{
    private static readonly TimeSpan Ttl = TimeSpan.FromMinutes(2);

    public ConfiguratorResult GetResult(RecalculationRequest request)
    {
        var entry = storage.TryRead(request);

        if (entry is null || entry.CalculatedAt < DateTime.UtcNow - Ttl)
        {
            RequestRecalculation(request);
        }

        return entry?.Value ?? ConfiguratorResult.Fallback;
    }

    private void RequestRecalculation(RecalculationRequest request)
    {
        try
        {
            eventRegistry.Get(ConfiguratorRecalculationModule.Id)
                ?.Raise(ConfiguratorRecalculationModule.Raiser, request);
        }
        catch (Exception ex)
        {
            // A failed raise only delays the refresh; the visitor still gets an answer.
            logger.LogWarning(ex, "Recalculation request for {Model} could not be raised", request.Model);
        }
    }
}

7. The scheduled job is the batch processor

using EPiServer.PlugIn;
using EPiServer.Scheduler;

[ScheduledPlugIn(
    DisplayName = "Recalculate configurator results on demand",
    GUID = "00000000-0000-0000-0000-000000000002",
    IntervalType = ScheduledIntervalType.Minutes,
    IntervalLength = 1,
    DefaultEnabled = true,
    Restartable = true)]
public class RecalculateOnDemandJob : ScheduledJobBase
{
    private readonly RecalculationQueue _queue;
    private readonly ConfiguratorCalculator _calculator;
    private readonly ILogger<RecalculateOnDemandJob> _logger;
    private bool _stopRequested;

    public RecalculateOnDemandJob(
        RecalculationQueue queue,
        ConfiguratorCalculator calculator,
        ILogger<RecalculateOnDemandJob> logger)
    {
        _queue = queue;
        _calculator = calculator;
        _logger = logger;
        IsStoppable = true;
    }

    public override void Stop() => _stopRequested = true;

    public override string Execute()
    {
        if (_queue.IsEmpty) return "Nothing to recalculate";

        var batch = _queue.Drain();

        var done = 0;
        foreach (var request in batch)
        {
            if (_stopRequested) break;
            try
            {
                _calculator.Recalculate(request);   // calculate and write to shared storage
                done++;
            }
            catch (Exception ex)
            {
                // One failing item must not abandon the batch; the next miss re-raises it.
                _logger.LogError(ex, "Recalculation failed for {Model}", request.Model);
            }
        }

        return $"Recalculated {done} of {batch.Count} items";
    }
}

Restartable = true makes the scheduler start the job again if the instance shuts down while it is running, and IsStoppable together with Stop() lets an operator end a long batch from the admin interface. Items dropped by a stop are simply requested again by the next miss.

Results in production

In one production implementation, the read path serves about 1,022,000 requests per day (absolute figures are scaled for confidentiality; the ratios are real):

1,000,000 hits (about 98%), answered from a fresh entry;
22,000 stale reads (about 2%), answered immediately with the previous result while the scheduler refreshes the entry;
0 misses. Misses only occur before the storage is first populated. After that, visitors receive the previous value of an expired entry until it is refreshed.

Before the pattern, each of those 22,000 stale reads would have been a miss: a visitor waiting for a synchronous recalculation, with several instances often recalculating the same entry at once. Stale reads now absorb that work, and the recalculation runs once per unique input on the scheduler instance. The exact numbers depend on traffic, the feature and the chosen TTL, but the shape stays the same: misses disappear and stale reads take their place.

What enables this architecture

The building blocks are the platform capabilities listed earlier. Three properties make them fit together:

Every instance runs the same deployment. Initialization modules subscribe to the event on all instances, and a single platform setting decides which one acts.
The control path and the data path are separate. Events travel over the bus, results travel through shared storage, and the scheduler and web instances never call each other. Either path can be replaced independently.
There is a single writer. Only the scheduler instance calculates and stores results, so every web instance reads the same value. Eventual consistency is confined to one place: the time until the next job tick.

The return path is a free choice

Any storage that every instance can read works as the return path. Blob storage is the simplest starting point and handles large results well. The CMS or Commerce database suits small structured results but adds load to a shared database. A synchronized cache gives the lowest read latency, provided the scheduler instance stays its only writer; an eviction then simply raises a new recalculation request. Whichever you choose, keep a short-lived local cache on the web instances so that shared storage is read once per interval rather than on every request.

Trade-offs and failure modes

Restarts, duplicate events, failing items and environments without a scheduler are covered by the design decisions above. Three trade-offs remain:

Concern	Behavior	Mitigation
Eventual consistency	A first-time miss is answered with a fallback until the next job tick	Choose an interval that matches business tolerance; pre-warm after deployments
Event delivery is best-effort	A message may be missed in rare cases	The next miss or stale read raises it again; the TTL bounds the impact
Shared scheduler capacity	The scheduler instance also runs every other scheduled job and the editors' back-office work, so a long batch competes with them	Keep per-item work bounded, watch batch duration, and move truly heavy work to a dedicated service

Observability is worth building from day one: log every miss, every raise, and the batch size per tick. The ratio between events received and unique inputs processed is a direct measure of how much work the pattern is saving.

When to use it

The problem section already describes the shape that fits: a limited set of repeated questions, slow answers from several sources, tolerance for slightly outdated results, and work that can be recalculated at any time. Besides configurators and translated texts, the same shape appears in accessory compatibility per model, dealer and store details per region, and filter options per product category.

Two further conditions are easy to overlook:

The answer contains no financial values, personal data or access decisions. Such data must be accurate and current on every request.
Visitors ask only a fraction of all possible questions. If every answer is needed anyway, a plain scheduled job that calculates everything is simpler.

Cases that look similar but fail one of these conditions:

Business case	Why it does NOT fit
Prices, discounts, taxes, delivery costs	Financial values shown to customers must be accurate at all times. An outdated value creates legal and reputational risk.
Stock or slot reservation at checkout	Visitors compete for the same item, which needs a synchronous, locked check.
Personal recommendations or account data	Inputs are unique per visitor, so de-duplication has nothing to merge, and personal data should stay out of shared storage.
Navigation or content filtered by permissions	Access decisions must be current. A stale answer can expose content.
Sitemaps and product feeds	Every answer is needed and read by machines on a timetable. A plain scheduled job is simpler.
Image renditions	Serving the original as a fallback defeats the purpose, and the number of variants is large. Resize on demand at the CDN.

Getting started checklist

1. Request a scheduler instance for Preproduction and Production through Optimizely support.

2. Identify one expensive, re-calculable operation currently done on the request path.

3. Define a small event payload and a stable event identifier.

4. Implement the read path: raise on miss or stale, never throw, always return something.

5. Implement the delegating module with both routing modes behind a configuration flag.

6. Add the de-duplicating queue and the scheduled batch job.

7. Pick the return path and a TTL that match your consistency needs.

8. Add logging and metrics for misses, raises and batch size.

9. Disable delegation locally; enable it in Preproduction and Production.

Conclusion

Scheduler delegation turns an under-used part of DXP into a small background processing system. Web instances report what they need over the event bus, the scheduler instance collects those requests and processes them in batches, and shared storage hands the results back. The request path stays fast, each heavy calculation runs once per unique input, and everything runs on infrastructure DXP already provides.

Thomas in the AI Discovery Era

2026-10-06T02:48:33.0000000Z

Its been a while, but hope you haven't forgotten Thomas, our most loyal visitor, the one who suddenly stops showing up.
Not because he lost interest. Because he asked an AI tool the question he used to Google, got his answer in thirty seconds, and never came to the site at all.
That's the shift most brands haven't clocked yet. The front door moved. Search isn't the only way in anymore, and a lot of the traffic you're losing to AI never shows up as a loss in your analytics. It just quietly isn't there.
But here's the part worth sitting with: AI isn't only taking visits. It's also sending them, to the brands it decides are worth citing. Which means the game isn't over. It just changed.
I pulled apart what actually earns those citations, and the one tactic everyone's doubling down on that the 2026 data says barely moves the needle. Plus what it means for the visitor who lands on your site already halfway through a thought.

Read the full article here.

Gated Content on Optimizely Graph, Part 2: Keeping Graph in Step with the CMS

2026-10-06T00:00:00.0000000Z

A correct ACL in the CMS is not enough: Graph evaluates access against the state available to it. That state can lag behind the CMS, and every cache between Graph and the browser adds a window of its own.

Optimizely Agent Platform - October 2026 State of Play

2026-10-05T10:45:21.0000000Z

Overview

A month ago I wrote up my takeaways from Opticon New York (Opticon New York & The Strategy on Upgrading to CMS 13 & Commerce 15). The headline was that Opal has grown up: the platform as a whole is now the Optimizely Agent Platform, and the AI chat you work with day to day is now Mark.

The trouble is that the pace of delivery has been relentless. The 2026 release notes alone run to well over an hour of reading, with something shipping almost every week, and features have been renamed, moved, merged and superseded along the way. If you are a solution architect or technical lead trying to answer the simple question "what does the platform actually do today, and how is it put together?", it is genuinely hard to get a clean picture.

So this post is my attempt at a state-of-play roundup as of early October 2026, broken down by the core building blocks of the platform, with a focus on the architecture, configuration and governance details that matter when you are designing real solutions. Wherever I can, I call out what changed and when using the official release notes, and I flag the places where the documentation is still catching up.

FYI, I know this is quite a long document, and it is mostly AI-generated, with my review added in. It should be a really good update for anyone who's used the platform, trying to keep up with all the changes. I'll probably do one of these every 6 months.

A note on sources. Everything here is based on the Agent Platform documentation, the 2026 and 2025 release notes, and Optimizely's Opticon announcements, as they stood on 5 October 2026. Screenshots marked as from the documentation are reproduced with permission. Things move fast, so always double-check the docs before you commit to a design.

Also https://drive.google.com/file/d/1VLziEiYH4mSGEkiC3VrGJOTP_pSIwF0-/view?usp=sharing is a version of this document as a nice infographic for easier digestion

TL;DR for architects

Area	Where we are today
Naming	Opal → Optimizely Agent Platform (effective 1 September 2026). Mark is the personified AI; Mark-1 / Mark AI is the post-trained model family; Mark-IQ is the context layer; Mark-Bench is the open-source benchmark. The docs still say "Opal" almost everywhere.
Models	Six inference levels (Quick → Code) mapped to Gemini or Claude models. Admins pick a default model provider per instance; specialised agents can override both provider and level. Mark's own post-trained models are announced as "coming soon".
Orchestration	Chat automatically delegates to sub-agents (Mini / Fast / Deep tiers) in isolated contexts, with parallel fan-out, no recursion and a per-turn dispatch budget.
Context	Skills (formerly Instructions), Brands, Memory, Personal files and RAG (CMP, Graph, and now your own artifacts).
Tools	System tools, connector tools, remote MCP servers (bring your own as of July) and custom tools via SDKs for TypeScript, Python and C#. A large CMS 13 (PaaS) tool set landed from May onwards.
Agents	Agent Directory (70+ prebuilt), Agent Library (curated launcher), specialised agents, workflow agents (now with Code steps, parallel loops, nested workflows, trigger priority and version history).
Autonomy	Virtual Teammates with their own Opti ID, memory and scheduled jobs, plus Team Messages as the collaboration layer.
Governance	Input guardrails, the Quality tab (Output Evaluation, Execution Guardrails, Execution Advisor), Safe URL Browsing, agent sharing/visibility, custom roles, exportable audit logs and version history.
Commercials	Credits pooled across products, fixed complexity bands since March 2026, 200 complimentary credits per instance per month until the end of 2026.

1. What's in a name? Opal, Agent Platform and Mark

Let's get the naming sorted first, because it is the single biggest source of confusion right now.

Optimizely's support centre now labels the category as "Agent Platform (previously Opal)" and states that the rename to Optimizely Agent Platform took effect on 1 September 2026, with Mark (for Marketing) as the personification of the platform. At Opticon the brand was split into four parts:

Name	What it is
Optimizely Agent Platform	The overall platform: agents, workflows, tools, skills, governance and the admin app.
Mark	The personified AI you talk to. In practice, this is what we used to call Opal Chat and the in-product assistant.
Mark AI / Mark-1	A family of post-trained, open-weight-based models built specifically for marketing tasks. Optimizely positions these as roughly 10x more cost-efficient than frontier models on the same marketing work. The press release states they are coming soon to all Agent Platform customers, so treat these as announced rather than generally available.
Mark-IQ	The data and context layer the models draw on, including your experimentation history and web analytics.
Mark-Bench	An open-source benchmark of 285 tasks across 15 marketing functions with more than 6,000 grading criteria.

On Mark-Bench, it is worth being precise about the numbers, because two sets are in circulation. The Opticon press release reports Agent Platform at a 67% all-pass rate against 60% for Claude Code, at half the cost, on default configurations. Optimizely's own Camp Opticon write-up quotes 58% versus 52% at 2.1x cheaper. Both come from Optimizely running its own benchmark, so if you are using them in a business case, cite which figure and the configuration behind it.

The docs are mid-migration

As of today (early October 2026) the documentation still uses "Optimizely Opal" in nearly every page title, the release notes are still called "Optimizely Opal release notes", and the product UI in the doc screenshots still says Opal. So you will see three names for the same thing depending on where you look. In this post I use Agent Platform for the platform and Mark (Opal Chat) for the chat experience, and I keep the documentation's feature names where they have not changed.

Other renames and retirements in 2026

The platform rename is not the only one. These are the changes I have seen trip people up:

When	What changed	Impact
14 Jan 2026	The Connections tab moved into Settings → Product Connections.	Old guides point to the wrong place.
14 Jan 2026	New tools and registries are disabled by default; admins must enable them.	New system tools will not appear in agents until switched on.
5 Feb 2026	Skills (then "Instructions") became inactive by default on creation.	You must toggle Active on.
24 Feb 2026	"Threads" and "conversations" standardised to chats.	Cosmetic, but affects training material.
18 Mar 2026	The creativity (temperature) setting was removed from specialised agents because newer models no longer support it.	Existing values are ignored, not errors.
7 May 2026	Instructions renamed to Skills. Existing instructions now live under Context → Skills, with no behaviour change.	The biggest terminology change before the rebrand.
7 May 2026	The 128-tool cap on dynamic tool lookups was removed.	Bigger tool catalogues are now practical.
4 Jun 2026	cms_geo_apply and cms_geo_analysis (CMS SaaS) were decommissioned, replaced by the general CMS content tools.	Update any agents or workflows that reference them.

2. How the platform processes a request

Before going into features, it helps to understand the runtime model, because almost every feature plugs into one of its stages. Each prompt goes through roughly the following pipeline:

Prompt and intent extraction. Mark works out what you are actually asking for.
Skills. Relevant skills are selected and injected into the system prompt.
Contextual intelligence. Product data, content knowledge and workspace context are added.
Tool selection. The right tools and agents are chosen for the job.
Input generation and validation. Parameters are built and checked. If they are invalid, Mark asks you for clarification instead of calling the model, which saves credits.
LLM interaction. Foundation models are called through business accounts, and your data is not used for training.
Execute and refine. Tools and agents run, and the output is re-evaluated and iterated on.
Response. The result comes back, often as a canvas or an action card.

Source: Optimizely Agent Platform documentation

The way the docs describe the relationship between the building blocks is still the best mental model:

Skills define how the AI behaves and uses tools.
Tools provide capabilities, such as reading data or taking action.
Specialised agents package tools and skills into one well-defined task.
Workflow agents chain agents together behind a trigger.
Virtual Teammates (new in August) sit on top as persistent, autonomous roles that own jobs over time.

3. Models and inference

This is the area that has changed most under the bonnet in 2026, and it has direct cost and quality implications.

Multi-model by design

The Agent Platform launched on Google Gemini and from 15 March 2026 Anthropic's Claude models (accessed via Google Vertex AI) joined the line-up, with Anthropic becoming a sub-processor under the Optimizely DPA. If you are working with a client's legal or procurement team, that is the notice to point them to. Optimizely also states that the choice of model does not change how credits are consumed.

On 24 June 2026 model provider selection arrived at both the instance level and the specialised-agent level. Admins now choose a Default Model Provider in Settings → Chat. The docs position Gemini as fast, cost-effective and good for creative writing, and Claude as stronger for complex tool orchestration and code generation. Specialised agents can override the instance default.

Inference levels

The inference level controls both the model and how much "thinking" it does before responding. Balanced is the default.

Inference level	Best for	Google model	Claude model
Quick	Simple, fast tasks	gemini-3.5-flash-lite (medium thinking)	claude-haiku-4-5 (medium thinking)
Standard	Everyday tasks without deep reasoning	gemini-3.8-flash (low thinking)	claude-sonnet-5 (no thinking)
Balanced (default)	Everyday tasks that benefit from reasoning	gemini-3.8-flash (medium thinking)	claude-sonnet-5 (high thinking)
Complex	Multi-step planning and analysis	gemini-3.8-flash (high thinking)	claude-sonnet-5 (x-high thinking)
Pro	Nuanced evaluation and strategy	gemini-3.1-pro (medium thinking)	claude-opus-5 (high thinking)
Code	Code, plus anything needing maximum reasoning	gemini-3.1-pro (high thinking)	claude-opus-5 (x-high thinking)

Model mapping as published in the Inference level documentation (updated 2 October 2026).

The mapping is managed by Optimizely and changes without any action on your side. Two recent examples: on 14 August the Complex and Code levels were upgraded to claude-opus-5, and on 13 September the Standard, Balanced and Complex levels moved to Gemini 3.8 Flash. Note that the current table shows Complex on claude-sonnet-5 with x-high thinking rather than Opus, so the August note appears to have been superseded. Treat the inference-level page as the source of truth, not the release notes.

Admins set the organisation-wide default for chat; agent creators set a level per specialised agent that overrides it.

Source: Optimizely Agent Platform documentation

Sub-agents (released 17 September)

This is one of the most architecturally interesting releases of the year, and it has gone a bit under the radar. When chat (or a specialised agent) hits a self-contained sub-task, it now hands it off to a sub-agent that runs in its own isolated context and returns only the final result. Intermediate tool calls and documents never enter your conversation.

The motivation is classic context engineering: avoiding context bloat (re-reading huge tool outputs every turn) and split attention (one model juggling unrelated objectives).

Tier	Inference level	Extended thinking	Typical use
Mini	Quick	No	Extraction, classification, reformatting
Fast (default)	Balanced	Yes	General delegation needing judgement
Deep	Pro	Yes, with a higher token budget	Sustained multi-step reasoning

The key technical behaviours:

Parallel fan-out. Independent sub-tasks are dispatched concurrently; dependent ones run in sequence.
Multi-turn continuation. A sub-agent can be resumed with its context intact.
No recursion. Delegation tools are stripped from sub-agents, so there are no unbounded chains.
Per-turn dispatch budget. Individual calls and fan-out slots share one cap per turn.
Instance default provider. Sub-agents never override the configured model provider.
Zero configuration. They are installed and managed by Optimizely, cannot be edited or deleted, and do not appear in the Agent Directory.

The practical gotcha is in your logs. One chat message can now produce several rows in Agent Activity Logs (search for "sub"), each with its own credit total, attributed to the user who started the chat, with the model provider shown as Instance Default. Rows sharing the same execution time indicate fan-out. If a client asks why one question produced five log entries, this is why, and Optimizely's position is that it is the same work routed more cheaply rather than extra work.

4. The chat experience (Mark / Opal Chat)

Chat is still where most users meet the platform. It is available in the global navigation across Optimizely One and at opal.optimizely.com. (likely to be changed soon)

What's new in chat in 2026

The chat has matured from a simple prompt box into a proper agent console. In rough chronological order:

January. CSV uploads, Markdown in the input box, a toggle for the history panel, and dark mode and font-size settings.
February. Upload of .xlsx and .docx files, and an immediate "thinking…" indicator.
March. Skill mentions (type / to apply a skill) and "save this as a skill" directly from a conversation.
April. Message queuing (keep typing while Mark works), pinned conversations, recency-sorted history and undo for pasted content.
May. Chat modes to match output depth to the task, action cards (rich, interactive inline components instead of plain text), chat pills (one-click starter prompts), memory, and multi-turn mode for specialised agents.
June. A live activity stream with inline tool status and "context pickup pills" showing what context was pulled in, Escape to stop a response, PowerPoint and Word generation (via the code_execution tool) and an image editor.
June 30. The Agent Library on the chat homepage and Personalize Opal, a pinned onboarding agent that walks new users through connecting tools and building skills.
July. Conversation compaction (automatic and manual checkpoints for long chats), editing sent messages, rotating contextual tips, Agent Builder and Skill Builder inside chat, and Safe URL Browsing.
September. RAG for artifacts, so chat can draw on your own canvases.

For architects, compaction and sub-agents together are the important pair: they are Optimizely's answer to long-running, tool-heavy conversations getting slower, dumber and more expensive over time.

Chat everywhere: in-product and third-party surfaces

Chat is embedded across the stack, and that list keeps growing:

CMS 13. The Optimizely.Cms.OpalChat adds Opal to the platform under verson 13.2.0 but 13.2.0 and onwards have Mark chat is built directly in to the CMS (requires DXP and Opti ID)
CMS 12 (since October 2025, requires DXP and Opti ID), CMS SaaS, Commerce Connect (since September 2025), Configured Commerce, PIM (January 2026), CMP, Web and Feature Experimentation, Personalization, Analytics, ODP and Product Recommendations (beta from May 2026).
Slack. Now a verified app in the Slack Marketplace (February 2026).
Microsoft Copilot and Google Agentspace / Gemini Enterprise, the latter using the Agent-to-Agent (A2A) protocol for cross-vendor agent collaboration (both since September 2025).

5. The context layer: Skills, Brands, Memory, Personal files and RAG

If tools are what the platform can do, this layer is what it knows. It is also the part that has evolved the most conceptually this year, and it effectively forms the user-facing side of what Optimizely now calls Mark-IQ.

Skills (formerly Instructions)

Skills are the reusable rules, context and behavioural guidelines that shape output, such as brand voice, product taxonomies, personas, compliance language or output formats. They come in two scopes: organisation skills (admin-managed) and personal skills (user-managed, since 30 March).

Source: Optimizely Agent Platform documentation

Each skill has a name, watchers, version history, an active flag, a /shortcut, a scope, a When to use activation trigger, the core skill body (rich text or Markdown), attached reference files, and a Where to use setting to scope it to a specific product instance.

Source: Optimizely Agent Platform documentation

How selection actually works matters a lot when you are designing a skills library:

All active skills available to the user are gathered.
Tool-triggered skills are applied automatically whenever their tools are in play, with no further evaluation.
The remaining skills are judged by a relevancy model that reads your latest message, the conversation history and each skill's Keywords or phrases field.
Matched skills are added to the system prompt.

Two consequences are easy to miss. First, the relevancy model looks only at the When to use field and ignores the skill's name and body during selection. Second, it is deliberately inclusive: it would rather include a borderline skill than miss a relevant one, and it matches semantically. A skill about "marketing promotions" can fire for a prompt about strawberries on sale. The fix is to write tight activation criteria, using "ONLY use for…", explicit "Do NOT use for…" exclusions, synonyms for narrow concepts, and mutually exclusive boundaries between related skills. Leaving When to use blank makes a skill shortcut-only.

Source: Optimizely Agent Platform documentation

The skills toolchain has also grown up considerably:

When	Change
5 Feb	Status column added; skills inactive by default
30 Mar	Personal skills; create skills from a chat; / skill mentions
14 Apr	Redesigned Activation Trigger section; better disambiguation when editing from chat
7 May	Instructions → Skills rename
26 May	File-explorer UI for skill files; PPTX/DOCX support in skills (with code execution)
27 May	Skills section in specialised agents, with a Choose skills picker to insert skills at exact points in a prompt
24 Jun	Skill watching; import/export across instances; scope switcher between personal and organisation; skill preview in the agent editor
30 Jun / 29 Jul	Skills builder GA, then Skill Builder inside chat

Brands (25 August) - Not fully out yet

Brands are a structured record of a brand's assets, colours, typefaces and usage rules, managed under Context → Brand. The clever bit architecturally is that publishing a brand turns it into a skill, so you get a single source of truth that image generation, decks, documents and social images all read from, instead of each feature holding its own copy. Brands move through Draft, Published and Default states, and an organisation can hold several brands with one default. Marketers can also bootstrap a brand on the fly when none exists.

Source: Optimizely Agent Platform documentation

For multi-brand clients this is a significant change. Previously you had to emulate this with a pile of brand-voice skills.

Memory (7 May) and Personal files (21 September)

Memory and personal files are now one system, and the implementation will look very familiar to anyone who has worked with coding agents: it is file-based.

Personal files are a persistent, per-user document store under Context → Personal Files, with a browser-based editor for text and Markdown files.
Memory lives in that same store. FACTS.md holds short durable facts, named notes files hold broader context, and RECENTS.md is a running summary of recent conversations and agent activity that Mark maintains. MEMORY.md is generated by Mark and is read-only.
Memories are captured either automatically or on request ("remember that…").
When Enable personal context is turned on for a specialised agent, context files such as AGENTS.md and MEMORY.md are made available to the agent before it starts. You can restrict the agent to a working directory (for example /context/agents/support) rather than exposing the whole store.

Source: Optimizely Agent Platform documentation

The distinction the docs draw is useful when you explain it to clients: skills capture how work gets done; memory captures who you are and what you are working on.

Retrieval-augmented generation (RAG)

RAG has expanded in three steps this year:

7 May. RAG for CMP. Permission-aware semantic and keyword retrieval across campaigns, tasks, assets, work requests and briefs, exposed as rag_retrieve_from_cmp (structured) and rag_retrieve_from_cmp_as_csv (tabular). Alongside it came rag_retrieve_from_optimizely_graph for CMS and CMP content via Optimizely Graph.
24 June. Folder and path filtering for CMP assets, relevancy explanations for suggested assets, and EU-region RAG.
17 September. RAG for artifacts. Chat can now search your own canvases, respecting artifact permissions and including artifacts shared with you.

Retrieval, embedding and indexing all happen inside Optimizely's infrastructure, and every query respects the user's roles and permissions. Admins can turn RAG on or off for direct chat under Settings → RAG Configuration, but note that agents can use RAG regardless of that setting, which is important if you are relying on the toggle for governance.

Source: Optimizely Agent Platform documentation

This is exactly where the CMS 13 upgrade story from my last post comes back in: Graph is the bridge that gets CMS and Commerce content into the agent platform's retrieval layer.

6. Tools: system, connector, remote MCP and custom

Tools are the actions. There are three families, and the year's big story is the arrival of MCP as a first-class citizen.

Source: Optimizely Agent Platform documentation

The Tools area is now split into four tabs: Connectors (each user links their own third-party accounts), Tools, Registries and External Providers (remote MCP servers and auth providers). You can filter tools by type (Remote MCP or Opal Tools), control per registry whether tools are active and whether they are enabled in chat, and restore chat defaults. Note that agents started from chat can use a registry's tools even when that registry is disabled for chat.

Source: Optimizely Agent Platform documentation

System tools for Optimizely products

Optimizely-maintained tools now cover practically every product. The ones that matter most for CMS and Commerce architects:

CMS 13 (PaaS), which arrived from 22 May:

Content types: paas_cms_list_content_types, paas_cms_get_content_type_details, paas_cms_create_content_type, paas_cms_update_content_type, paas_cms_delete_content_type
Property groups: paas_cms_list_property_groups, paas_cms_create_property_group
Content: paas_cms_get_content_data, paas_cms_update_content_item (creates a draft if no key is given), paas_cms_delete_content_item (moves to the waste basket), paas_cms_publish_content_item (immediate or scheduled), paas_cms_create_content_variation (locale variations)
Preview: paas_cms_get_content_preview_url, which lets the agent fetch and analyse rendered HTML
SEO and GEO: paas_cms_seo_analysis, paas_cms_seo_edit, paas_cms_geo_analysis, paas_cms_geo_apply (writes JSON-LD into a JsonLdTemplates property as a draft)
Display templates and media (29 July): paas_cms_list_display_templates, paas_cms_get_display_template, paas_cms_create_display_template, paas_cms_update_display_template, and paas_cms_upload_media (pulls a file from a public URL into CMS media)

Note that the GEO tools were removed from CMS SaaS in June but exist for CMS 13 PaaS. Do not assume parity between the two tool sets.

Optimizely Graph (CMS SaaS, CMS 12 and CMS 13): graph_content_type_schema, graph_content_graphql_executor and graph_content_search_tool (January), plus graph_pinned_result and graph_synonyms (14 August), so agents can now tune search relevance, not just query it.

Commerce: Commerce Connect became a product connection on 13 March, alongside the Product Promotion agent for Commerce Connect; Configured Commerce has system tools and a Restriction Group Creation agent; and Product Recommendations has a growing pr_* tool set for category, search, trend and algorithm performance reports and page management.

Beyond that there are tool sets for CMP (work requests, campaigns, milestones, structured content, asset updates), Experimentation and Personalization (including ten exp_ve_* Visual Editor DOM tools that power the AI variation development agent), Analytics, ODP, Campaign, PIM and Content Recommendations.

Connector tools and remote MCP

The connector catalogue exploded this year. Highlights include Microsoft 365 (Teams, Outlook, and from 18 September OneNote and sensitivity labels on OneDrive and SharePoint), Google Workspace (Docs, Sheets, Slides, Calendar and Gmail), Google Ads, Google Search Console, GA4, LinkedIn Ads, OpenAI Ads, Adobe Analytics, Salesforce CRM, Amplitude, Mixpanel, WordPress, Zoom, Crunchbase and Figma.

Remote MCP arrived in stages:

30 March. Remote MCP connector tools (starting with Atlassian and Conductor), with user-level authentication: the admin enables the server for the organisation, and each user authenticates their own account so actions carry their own identity and permissions.
7 May. Notion, Contentsquare, Contentful, Gamma, GitHub, Sanity and ClickUp.
29 July. Bring your own remote MCP server, plus HubSpot and ZoomInfo.
18 September. Braze and Fullstory, and Contentful Global and EU endpoints for data residency.

User-level authentication is the most important architectural point here. It gives you proper action attribution and per-user data scoping for third-party systems, rather than a single shared service account.

Custom tools

When nothing off the shelf fits, you build a custom tool. The contract is straightforward:

A tool manifest describing name, description, typed parameters, the execution endpoint and auth requirements.
A discovery endpoint (typically /discovery) that returns the manifest. If it is unreachable or malformed, the tools simply will not appear.
An execution endpoint, typically a POST with a JSON body returning JSON.
Authentication. Notably, the docs state that only Opti ID is supported for tool authentication at the moment, with other providers in the works.

Since 1 April, parameters support nested schemas (objects within objects, arrays of objects and enums), which makes richer integrations far less awkward. Tools are hosted either on Optimizely Connect Platform (OCP) or anywhere publicly reachable, and they are registered as a registry with a discovery URL that you can re-sync.

Official SDKs:

Language	Install	Notes
TypeScript / JavaScript	npm install @optimizely-opal/opal-tools-sdk	Express middleware, @tool() decorators, parameter validation, auth helpers
Python	pip install optimizely-opal.opal-tools-sdk (import as opal_tools_sdk)	FastAPI integration, auto /discovery
C# / .NET	See note below	ASP.NET Core integration, [Tool] and [RequiresAuth] attributes, DI support

A small but real gotcha for .NET teams: the docs currently show the install command as Install-Package OptimizelyOpal.OpalToolsSDK, but link to a NuGet listing named Optimizely.Opal.Tools. Check NuGet for the current package ID before you pin it in a project.

7. Agents

The four kinds of agent

Type	Who builds it	What it is
Agent Directory agents	Optimizely	Prebuilt, installable agents. There are now 70+ listed in the credits reference alone. Since 25 August they auto-update when Optimizely publishes a new version (on by default).
Agent Library	Optimizely (curated)	A browsable launcher on the chat homepage with more than 45 agents runnable in one click, without installation (30 June).
Specialised agents	You	One well-defined task, with your prompt template, tools, skills, variables, model provider and inference level.
Workflow agents	You	Multi-step automations of triggers, logic and agents. Still described in the docs as private GA and not available on all instances.

Source: Optimizely Agent Platform documentation

Directory agents worth knowing as a CMS or Commerce architect

The Directory has shifted from generic content helpers towards agents that act directly on the platform:

CMS 13 (PaaS): Content Model Creation, Page Builder, Content Analysis, GEO Schema Optimization and SEO Metadata Implementation. The Content Analysis agent produces a Markdown instruction set for a content type that the Page Builder agent then uses, which is a neat pattern for on-model content generation.
CMS SaaS equivalents, plus Content Refresh Analysis and FAQ Creation.
Commerce: Product Promotion (Commerce Connect) and Restriction Group Creation (Configured Commerce).
Experimentation: Experiment Conflict Checker, Backlog Prioritization (PIE scoring), Value Estimator, Program Overview, Program Health Review, Feature Experimentation Governance, and the Feature Flag Implementation agent, which outputs a portable SKILL.md for implementing a flag in your codebase. That is a nice nod towards developer agent tooling.
AI search and AEO: GEO Auditor, the Conductor AEO Gap Finder, AI Brand Visibility and Competitive Share of Voice agents, Profound Citation Gap Analysis, and Agent Visibility Analytics Insights.

Specialised agents: what's new

The agent editor has quietly become quite sophisticated over 2026:

Versioning with view, restore and branch-from-version (January).
Prompt template shortcuts for inserting variables, tools and skills inline; case-insensitive, unique variables; array/list inputs (May).
Example shots in the prompt template (February) and preferred output examples.
JSON export and import for moving agents between instances (April).
Multi-turn interaction mode in chat (May). Note that specialised agents always run single-turn inside workflows.
Model provider and inference level per agent (June).
Sharing and visibility (30 June): private, named people or the whole organisation, with view, run, edit and delete permission levels. New agents default to private where the feature is enabled, and it is not available on all tiers.
Agent Builder in chat (29 July), so agents can be created and iterated on conversationally.
Personal context and working directory settings (September).
A 60-minute timeout (since November 2025) to stop runaway executions burning credits.

Workflow agents: what's new

Workflow agents are made up of triggers (chat, schedule, webhook and email), logic (conditions, loops and code) and agents.

Source: Optimizely Agent Platform documentation

This has been the busiest area for releases:

When	Change
Jan	Add a trigger first when building
Mar	Builder-first creation flow; multi-branch conditions in a single node; email trigger improvements
Apr	Webhook trigger redesign with product instance selection and default CMP auth headers; parameter generation logs; helper messages for chat triggers; JSON download and copy; case-sensitive conditions
May	Workflow import/export; loop validation; schedule start time and no end date
Jun	Execution-log export to CSV/Excel with date ranges
29 Jul	Nested workflows; static versus predicted parameters (lock a variable or let the LLM fill it); Agent Update Warning before editing an agent used by a workflow; Version History for workflows; a new Execution Status Taxonomy
17 Sep	Code step (Python, JavaScript or Bash, with no external service needed); Run iterations in parallel on loops; trigger priority (Standard versus Background) so batch runs do not delay interactive ones

The Code step is a big deal. Previously, any deterministic transformation, such as parsing, maths or reshaping JSON between agents, meant either burning an LLM call or standing up a custom tool. Now it can live inline in the workflow. Together with nested workflows and static parameters, workflow agents are becoming a reasonable low-code orchestration layer rather than just a chain of prompts.

A credit note: a workflow's cost is the sum of the specialised agents it invokes, with no overhead for the workflow itself.

8. Virtual Teammates and Team Messages

This was the headline Opticon launch, released on 25 August (Not availible to everyone yet, especially partners)

What a Virtual Teammate is

A Virtual Teammate is a persistent AI worker built from the same components you already have, namely tools, agents and workflows, and jobs (workflows it runs on its own, on a schedule or on events), wrapped in a persistent identity with memory, a persona and a defined role. The distinction from an agent is continuity: an agent runs when you invoke it, whereas a teammate keeps working, holds context, improves from feedback and collaborates with other teammates.

The launch roster:

Chief of Staff: daily and weekly briefs, meeting prep and recaps, and competitive intelligence.
Marketing Analyst: scheduled, decision-ready GA4 reports.
SEO & AI Search Analyst: reasons across Search Console, GA4, Conductor and AI Visibility Analytics.
CRO Manager: monitors behaviour, analyses competitor UX and stages experiment configurations in Optimizely.
Personalization Strategist: builds and runs personalisation campaigns end to end.

Identity and access: the architect's checklist

This is the bit to get right in any implementation:

Each teammate gets its own Opti ID account (its own login and email, flagged as a virtual user). It shows up alongside people and fits into existing access and audit processes, and its usage is tracked separately from human usage.
It does not consume a product seat.
It gets only the access you grant it, with nothing inherited automatically from the person who hired it.
Inside Optimizely products it acts as itself. Outside Optimizely it acts through accounts a human connects on its behalf, usually the person who hired it. It cannot authorise third-party connections on its own.
For CMS 13 and CMS SaaS there is an extra step: after granting the teammate a role in the Opti ID Admin Center, you must also add it to the relevant content under Settings → Set Access Rights in CMS, with only the rights its jobs need.

Source: Optimizely Agent Platform documentation

That last point is another reason Opti ID is non-negotiable in CMS 13: Virtual Teammates are first-class principals in the identity layer, so the same governance you apply to people applies to them.

Autonomy controls

By default a teammate drafts and proposes, and a human approves via Team Messages. As confidence builds you can allow specific actions to run automatically within boundaries you set, and you configure its persona, values, who it may talk to, and which tools it can read, write or run. Admins enable teammates for the organisation and can pause or deactivate them; users and agent builders hire and configure their own. You can even switch identity to work in the platform as the teammate.

Team Messages

Team Messages is the real-time collaboration layer for people, teammates and agents, offering direct messages, group chats and channels, with sharing of files, agents and artifacts, mentions and persistent history. It follows you across products (an unread badge appears on the IM icon in CMP, Experimentation and elsewhere), and teammates also join meetings and share transcript summaries in Teams and Slack.

Source: Optimizely Agent Platform documentation

Alongside it sit the Tracker and Notifications (in-app tray, Notification Center, browser notifications since May, and skill-update and guardrail notification categories since June).

9. Quality, safety and governance

If Virtual Teammates are the accelerator, this is the brake, and it is what makes autonomous operation defensible to a client's risk team.

Input guardrails (29 July)

You define rules in plain language about what users may ask, and the platform trains a classifier to enforce them. This is useful for keeping usage on-topic and compliant without hand-maintaining block lists.

The Quality tab for specialised agents (1 June)

Source: Optimizely Agent Platform documentation

The Quality tab gives you three mechanisms:

Output Evaluation. An AI judge scores every run against up to 10 criteria, a baseline score between 75% and 95% (in 5% steps) and up to five examples. This builds on the preferred-output examples from December 2025 and the ability (January 2026) to promote past runs to evals.
Execution Guardrails. These learn what "normal" looks like for an agent and progress through Learning → Watching → Enforcing as successful runs accumulate. You control sensitivity and whether flagged runs are stopped automatically.
Execution Advisor. This has no configuration screen; it acts on what the other two detect. It recovers flagged runs with corrective guidance, retries failed tool calls with adjusted input, and reviews sensitive tool calls (email, publish, delete) with inline Approved or Blocked verdicts.

Each run therefore carries two independent verdicts, an Evaluation Score and a Guardrail Status, and a run can pass one and fail the other. The docs suggest starting with Output Evaluation and adding guardrails once behaviour has stabilised, which matches how I would roll it out.

Source: Optimizely Agent Platform documentation

Safe URL Browsing (29 July)

Every URL is screened before the platform browses it. Standard (always on) checks Google Web Risk for malware, social engineering and unwanted software. Advanced (opt-in per instance under Settings → Chat) adds a Cloudflare Radar deep scan in parallel, which can add up to 30 seconds of latency for URLs Cloudflare has not seen recently. Only http and https are accepted, redirect targets are screened too (which closes the open-redirect bypass), and links in emails processed by email triggers are also checked. Blocked requests return no partial content, only the threat category.

Source: Optimizely Agent Platform documentation

If a client's firewall blocks the platform from scanning their sites, there is a published allowlist of separate non-EU and EU egress IPs, last updated on 22 July. Check the admin guide for the current list rather than copying it from old project documentation.

Roles, auditability and change control

Roles: Opal Administrator, Agent Builder (new on 24 February, for people who build agents without being admins) and Opal User, plus custom roles in the Opti ID Admin Center.
Audit: Created By, Triggered By and Modified By on agents and skills; credit usage per run in logs; execution-log export with date ranges for specialised and workflow agents; and the Execution Status Taxonomy (July).
Change control: version history for specialised agents, skills and workflows; watchers on skills and agents; and the Agent Update Warning before editing an agent a workflow depends on.
Human in the loop for side effects: for example, send_email shows a confirmation "island" in chat (since December 2025), and Execution Advisor can gate sensitive tool calls.
Kill switch: generative AI can be turned off for an organisation in the Opti ID Admin Center. Be aware that turning it off means contacting Optimizely Support to re-enable it.

10. Artifacts and canvases

Outputs have also grown well beyond chat text:

Canvas (December 2025) is the working surface for documents, HTML, React/Next.js, CSV and PowerPoint content, with downloads in the relevant formats (February), an "Edit in canvas" button, a raw Markdown mode (May) and space-level sharing permissions with view, edit and manage access (June).
The Artifacts page (May) is a single searchable home for everything you have created, with sharing and, since September, RAG over artifacts.
PowerPoint and Word creation and editing (June), when the code_execution tool is enabled, now on-brand by default thanks to Brands.
The image editor (June) offers element detection and selection, brush transforms, batch edits and smart aspect ratios. (below)
Limitless 1:1 Personalization (June) generates landing pages per target account or segment, which is the capability I covered from the keynote last month.

11. Administration, data residency and credits

Administration essentials

The setup order has not changed: connect your product instances first under Settings → Product Connections. If an instance is not connected, it cannot use the platform's features.

Source: Optimizely Agent Platform documentation

Other settings to know about are the default model provider and inference level, RAG in chat, Advanced URL safety, and the email domain used for outbound email. Be careful with the email domain: it is a single subdomain prefix per instance, and it cannot be changed once set. Users without Opti ID can also be enabled (see "Enable Opal for non-Opti ID users" in the docs).

Data residency

The platform is hosted in the US and the EU, with the region chosen on your order form. Everyone uses the same URL, and routing to your region happens behind the scenes. Customer inputs and outputs are stored long-term in North America or the EU (Belgium), with no per-country selection. However, prompt processing goes through global model endpoints for availability and performance, so a prompt may be processed in any region, although the LLM does not retain it and the output returns to your region. EU app hosting arrived on 4 June and EU RAG on 24 June. If a client has strict residency requirements, that processing nuance is the one to raise early.

Credits and cost

Credits are pooled across all eligible Optimizely products.
Since 1 March 2026, usage falls into fixed complexity bands for predictability.
Every instance gets 200 complimentary credits per month from 1 October 2025 until 31 December 2026. This is worth noting for 2027 budgeting.
There are no per-user credit limits. You control spend by controlling who has access.
Usage is visible in the Opti ID Usage and billing dashboards, with monthly notifications, and in the redesigned Opal Agent Usage dashboard (30 June), which shows executions, credits, top agents and users, and weekly active users.

Complexity band	Average credits per invocation
Chat and basic agents	2
XS	10
S	30
M	70
L	130
XL	200

To give a sense of scale from the published per-agent figures: SEO Metadata Implementation for CMS 13 averages 120–200 credits, GEO Schema Optimization 40–60, Content Model Creation 30–80 and the Conductor AEO Gap Finder 180–200.

Who pays depends on the trigger: for chat and in-product invocations it is the invoking user, but for schedule, webhook and email triggers it is the user who created the trigger. Keep that in mind when you design shared automations. In practice, you probably want a dedicated owner (or, increasingly, a Virtual Teammate) owning scheduled workflows, so usage reporting stays meaningful.

12. 2026 at a glance

Month	Headline releases
Jan	Specialised agent versioning; prompt template shortcuts; Graph tools; CMS SaaS content tools; Experimentation and Personalization system tools; PIM chat; tools disabled by default
Feb	Agent Builder role and custom roles; Slack Marketplace app; canvas downloads; example shots; Visual Editor, CMP and Analytics tool sets
Mar	Claude models join (15 March); fixed-band credits (1 March); Commerce Connect product connection; personal skills; user-level auth for connectors; first remote MCP connectors; credit usage in logs
Apr	Agent JSON import/export; message queuing; nested parameter schemas for custom tools; CMS 13 Opal Chat NuGet; Idea Builder
May	Instructions → Skills; memory; Artifacts page; notifications; chat modes, action cards and chat pills; RAG for CMP and Graph; CMS 13 content tools; more remote MCP servers
Jun	Quality tab; EU hosting and EU RAG; model provider selection; skill import/export; PPTX/DOCX generation; image editor; Agent Library; agent sharing and visibility; Limitless 1:1 Personalization; Teams and Outlook tools
Jul	Agent Builder and Skill Builder in chat; input guardrails; Safe URL Browsing; conversation compaction; nested workflows; workflow version history; bring-your-own remote MCP; CMS 13 display template and media tools
Aug	Virtual Teammates; Team Messages; Brands; Directory auto-update; Graph synonyms and pinned results; CMS 13 Page Builder and Content Analysis agents
Sep	Rename to Agent Platform and Mark; Mark-1, Mark-IQ and Mark-Bench announced; sub-agents; RAG for artifacts; workflow Code step, parallel loops and trigger priority; personal files; LinkedIn and OpenAI Ads connectors; Braze and Fullstory MCP

For context, at the start of the 2025 release notes Opal was essentially a chat assistant embedded in individual products. The platform pieces, namely specialised agents, workflow agents, the Agent Directory, system tools and custom tools, only arrived on 9 September 2025. Everything in the table above has been built in the thirteen months since.

13. What this means for solution architects

Pulling this together, these are the points I would take into any design conversation right now:

Upgrade the foundations first. Opti ID (identity for humans and teammates), Graph (retrieval, search tuning and agent access to content) and product connections are the prerequisites for nearly everything above. This is the practical reason the CMS 13 and Commerce 15 upgrade is a strategic decision, not just a version bump.
Treat skills as code. With import/export, versioning, watchers and a selection model that only reads When to use, a skills library deserves the same discipline as any shared configuration: naming conventions, scoped activation criteria with explicit exclusions, review, and promotion between instances.
Decide your integration pattern deliberately. For each external system, the choice is now between an existing connector, a vendor's remote MCP server, your own remote MCP server, or a custom tool (on OCP or self-hosted). User-level auth on MCP and connectors gives better attribution; custom tools currently authenticate with Opti ID only.
Put deterministic logic in deterministic places. Use workflow Code steps and static parameters for anything that does not need an LLM, and keep specialised agents small and single-purpose.
Design for cost visibility. Choose the inference level per agent rather than defaulting everything to Pro, expect sub-agent rows in logs, and be deliberate about who owns scheduled and webhook triggers, since they pay.
Layer governance before autonomy. Input guardrails, Output Evaluation, then Execution Guardrails, and only then let Virtual Teammates act without approval, scoping their Opti ID roles and CMS access rights to exactly what their jobs need.
Use the docs carefully. They are excellent but moving fast: naming is mid-migration, workflow agents are still flagged as private GA, release notes can be superseded by reference pages (as with the inference mapping), and at least one SDK package ID is inconsistent. When it matters, verify in your own instance.

Summary

Twelve months ago, Opal was a promising chat assistant with a brand-new agent builder. Today the Optimizely Agent Platform has a multi-model runtime with managed sub-agent delegation, a layered context system (skills, brands, memory, files and RAG), an open tool ecosystem built around MCP, low-code workflows with real code execution, autonomous Virtual Teammates with their own identities, and a governance stack to keep it all in check. Mark is the friendly face on top, and Mark's own post-trained models are next.

For those of us designing solutions on Optimizely, the platform is no longer an add-on to CMS or Commerce. It is becoming the operational layer that sits across them, and the quality of what it can do depends directly on how well the underlying platform is connected through Opti ID, Graph and the product connections.

If you would like help shaping your agent platform strategy, building custom tools and MCP integrations, or getting onto CMS 13 and Commerce 15 so you can use all of this, get in touch with us at Niteco: https://niteco.com/contact-us/

Key references

Agent Platform documentation: https://docs.optimizely.com/agent-platform/docs
2026 release notes: https://docs.optimizely.com/agent-platform/release-notes
2025 release notes: https://docs.optimizely.com/agent-platform/release-notes/2025-agent-platform-release-notes
Inference level and model mapping: https://docs.optimizely.com/agent-platform/docs/inference-level
Sub-agents overview: https://docs.optimizely.com/agent-platform/docs/sub-agents-overview
Skills overview: https://docs.optimizely.com/agent-platform/docs/skills-overview
Tools overview: https://docs.optimizely.com/agent-platform/docs/tools-overview
Create custom tools (SDKs): https://docs.optimizely.com/agent-platform/docs/create-custom-tools
Virtual Teammates overview: https://docs.optimizely.com/agent-platform/docs/virtual-teammates-overview
Quality tab overview: https://docs.optimizely.com/agent-platform/docs/quality-tab-overview
Credits: https://docs.optimizely.com/agent-platform/docs/agent-platform-credits
Administrator guide: https://docs.optimizely.com/agent-platform/docs/get-started-with-agent-platform-for-administrators
Mark models and Mark-Bench press release (1 September 2026): https://www.prnewswire.com/news-releases/optimizely-introduces-purpose-built-ai-models-for-marketing-that-deliver-frontier-level-quality-at-a-fraction-of-the-cost-302865074.html
My Opticon New York write-up: https://world.optimizely.com/blogs/scott-reed/dates/2026/9/opticon-new-york--the-strategy-on-upgrading-to-cms-13-/

Migrating from Search & Navigation (Find) to Optimizely Graph in CMS 13

2026-10-05T08:41:10.0000000Z

If you are planning an upgrade to Optimizely CMS 13, one of the biggest

So you've decided to move to .NET 10 (but stay on CMS 12)

2026-10-02T16:17:30.0000000Z

Ok, "decided" is a strong word. Microsoft decided for us. .NET 8 and .NET 9 both reach end of support on November 10, 2026, and if you're on CMS 12 and Commerce 14, the calendar is the project plan whether you like it or not.

CMS 13 is the shiny option, but it brings Opti ID, Optimizely Graph in place of Search & Navigation, and (for Commerce) a real rewrite. That's a project. Staying on CMS 12 / Commerce 14 and moving the runtime to .NET 10 is the "buy yourself time" option. Optimizely has said both CMS 12 and Commerce 14 support it.

We've been working through this for a couple of months on a DXP-hosted CMS 12 + Commerce 14 site. We're not on Production yet, so this isn't a victory lap. It's the list I wish someone had handed me on day one.

Isn't this just a TargetFramework change?

No. The TFM change is the easy part. The packages decide the rest.

The .NET 10-compatible Commerce 14 requires a newer EPiServer.Find.Commerce, which requires Search & Navigation (Find) 17. The build fails outright until you take it. It's not a warning you can sit on.
Find 17 changes the index format, which means a full reindex in every environment. More on that below, because it's the biggest item on this list.
Take the latest patch of everything, not the first version that compiles. We hit a SQL deadlock on bulk publish with Find 17.0.1. It went away after we moved to 17.0.2 together with the latest CMS and Commerce patches. We didn't isolate which one fixed it.
Check the official System requirements page against the blog posts. For a while they disagreed. Know which one you're relying on.

Why is my homepage a 500 right after deploying?

Against an index built by Find 16, Find 17 queries come back with a null content link, and you get an ArgumentNullException deep in ContentInstanceCache. If anything in your header or layout does a Find query, that's every page.

Things to plan for:

Rollback is asymmetric. Redeploying the old code is easy. But Find 16 code can't read a Find 17-format index either, so a rollback needs a second full reindex. Plan to fix forward.
The out-of-the-box indexing job may not be your whole index. If you push catalog content into Find with your own jobs, list every type you index and make sure each one actually has a job that indexes it. We found types that no job covered at all.
HTTP 200 is not "healthy." A half-built index can return {"total":0} in 30 ms and pass every smoke test. Check what the page actually renders (nav item counts, search result counts), not just status codes.
Big reindex jobs need to batch. One-item-at-a-time indexing of ~100k variants took about 12 hours. Batching brought it to about an hour. (The out-of-memory errors we saw on that job were the memory limit in the next section, not the lack of batching.)
For environments with live traffic, ask about a temporary second index. Optimizely told us it can provision a temporary migration index, so you build the new index next to the live one and flip DefaultIndex at cutover. Be clear that you mean a temporary one, not a permanent one. On DXP that flip is a support change request, not something you can do yourself on Preproduction/Production. At the time of writing ours hasn't been provisioned yet, so ask early.
Staging slots share the database. If you think of reindexing in a slot, remember the new code can run schema upgrades against the same database the live slot is using. Optimizely's suggestion was to turn off automatic schema updates on the slot (UpdateDatabaseSchema = false).

Why is it suddenly out of memory?

This one cost us the most time, so I'll spend a minute on it.

Same code, same environment tier. On .NET 8 our Integration site happily grew past 8 GB. On .NET 10 the same site capped at about 6 GB and threw OutOfMemoryException on heavy reports, exports and reindex jobs.

The reason: since .NET 9, the runtime honors the memory limit of the parent cgroup the App Service site runs in, and .NET 8 did not (dotnet/runtime#93611, part of #93030). By default the GC heap gets 75% of that limit. So .NET 8 was quietly using memory the newer runtime won't touch. If you're already on .NET 9, you already live with this limit.

What to do before you deploy:

Measure your current peak Private Bytes on .NET 8, per environment, for 30 days. Compare it with what the GC will allow on .NET 10: about 75% of the site's memory limit, which is lower than the plan's RAM. On an 8 GB P1v3 the site limit was about 7 GB.
Log what the runtime actually thinks it has at startup. Don't guess. This one line showed us the real limit:

var gcInfo = GC.GetGCMemoryInfo();
logger.LogInformation("GC TotalAvailableMemoryBytes={TotalAvailable}", gcInfo.TotalAvailableMemoryBytes);

HeapHardLimitPercent buys some headroom, but it's a stopgap. The rest of the memory is native memory you still need:

<ItemGroup>
  <RuntimeHostConfigurationOption Include="System.GC.HeapHardLimitPercent" Value="80" />
</ItemGroup>

Know about DATAS if you're comparing memory between .NET 8 and .NET 10. Since .NET 9, Server GC turns on dynamic heap sizing (DATAS) by default. We turned it off (<GarbageCollectionAdaptationMode>0</GarbageCollectionAdaptationMode>) so our numbers compared like for like.
Ask Optimizely about sizing early if your numbers say you need a bigger tier. Bring the measurements: the startup log line and the runtime issue link.

Wait, did we just upgrade Preproduction?

Good news: you don't need to ask DXP to change anything. It picks the base image from the target framework in your package, per environment. So Integration can run .NET 10 while Preproduction and Production stay on .NET 8.

The trap: a promotion reuses the source environment's container image, runtime included. Promote your .NET 10 Integration build and Preproduction is now on .NET 10. While you're evaluating, deploy the package directly to Integration and keep sending .NET 8 packages downstream.

To revert an environment, redeploy a .NET 8 package. One catch: Commerce and CMS package updates upgrade the database schema on first boot, and older packages refuse to start against a newer schema. A .NET 8 package is a clean rollback only if it carries the same Optimizely package versions. The .NET 10-compatible Commerce 14 still targets .NET 8, so ship the package updates on .NET 8 first. Then the runtime is the only thing you'd be rolling back.

Why does it build on my machine and not in CI?

System.Linq.Async vs. the BCL. .NET 10 added AsyncEnumerable to the framework, and the old package still arrives transitively through the CMS UI packages. Exclude its compile assets in every project that sees it (Microsoft's documented fix):

<PackageReference Include="System.Linq.Async" Version="6.0.1">
  <ExcludeAssets>compile</ExcludeAssets>
</PackageReference>

Castle.Core must stay below 5.0 for CMS 12. An add-on whose .NET 10 dependency group pulls in Castle.Core 5.x breaks boot with a TypeLoadException. In test projects, newer Moq versions pull it in too. The add-on author we reported it to fixed it within a day.
The classic NuGet task can disagree with dotnet restore. With the nuget.exe version our pipeline pinned, restore failed on an NU1605 downgrade that dotnet restore on the .NET 10 SDK never reported. Use a nuget.exe that matches your SDK, or switch CI to dotnet restore, and run a CI build early.
Build tools that target an older runtime (code generators, CLI tools invoked from MSBuild) fail on an agent that only has .NET 10. DOTNET_ROLL_FORWARD=LatestMajor in the pipeline fixed it for us.
Pin LangVersion if your team needs to keep a C# version ceiling. The new SDK will happily let people use features you didn't agree to.
Third-party UI packages with per-version license keys or hard-coded CDN versions break quietly when the package version moves and the hard-coded number doesn't.

Why does EF Core suddenly throw a syntax error?

If you move EF Core up with the runtime (EF Core 8 and 9 end support on the same date as .NET 8), check your large .Contains() calls. EF Core 10 sends a list as separate parameters by default, but past SQL Server's 2,100-parameter limit it falls back to one JSON parameter decoded with OPENJSON. That needs SQL Server compatibility level 130 or higher. Our local copy of the CMS database (restored from a DXP export) was at 110, and a .Contains() over about 5,000 IDs threw Incorrect syntax near '$'. Small lists worked fine, so a quick test won't catch it.

Check yours:

SELECT name, compatibility_level FROM sys.databases;

If you can't raise the level, tell EF to inline constants for that context:

options.UseSqlServer(connectionString,
    sql => sql.UseParameterizedCollectionMode(ParameterTranslationMode.Constant));

This applies to every .Contains() in that context, so expect more distinct query plans in SQL Server's plan cache.

Is that a .NET 10 bug or something else?

Most of what our first regression pass found wasn't .NET 10 at all. Before you blame the runtime, check:

Concurrency bugs that were already there. We had Task.WhenAll over several content loads on one request, which shares a database connection context that isn't built for parallel use. It was latent on .NET 8 and showed up on the new stack. Search for parallel IContentLoader calls.
Stale front-end bundles in local builds. If dist/ is gitignored, a local dotnet publish copies whatever bundles happen to be on disk. Renders fine, looks wrong.
Lower-environment content drift. Integration content and settings drift from Production. Compare with Preproduction before you file a bug: if it also fails on the .NET 8 environment, it's not a regression.
Old release pipelines. A pipeline nobody has touched in a while may point at a retired hosted agent image.

How do I test this without breaking things?

Turn off outbound integrations before you test. A regression pass that runs jobs and publishes content will send records to every partner, CRM and ticketing endpoint that environment is configured for. Check which of those are production endpoints before you start.
Script it. Our first pass was a full page-by-page walk-through and took two days. Most of it found content drift. The rerun is a script of about 90 minutes: boot log, a critical-path test suite, a page/API status sweep, heavy reports and jobs under load, one end-to-end checkout in test mode, an exception diff.
Capture before-and-after numbers in the same time window: request percentiles, memory, exceptions by type, job durations. If you change the tier and the runtime at the same time, you'll want to know which one helped.
Do a database copy-down rehearsal on Integration. Booting a Production-sized database on the new stack catches things a stale lower environment won't. A copy-down brings Production's scheduled jobs and settings with it, so turn off outbound jobs before the site boots.

So what did I miss?

That's the list so far. We're still working toward the Preproduction and Production cutover, so I expect to add to it. If you've already done this move on DXP, especially the Find 17 cutover on a live site, I'd love to hear how you sequenced it. Let me know in the comments.

From robots.txt to GEO Analytics: A Year On

2026-10-02T08:33:26.0000000Z

In September 2025, I wrote about updating

Connect Your AI Agents Directly to Optimizely CMS

2026-10-01T11:20:43.0000000Z

Connect any AI agent to Optimizely CMS and Commerce via Epicweb Agent API, reusing CMS-aware tools, instructions, and permissions to automate SEO, translation, and updates.