Spryker Documentation

AI Dev SDK Skills and Agents

Wed, 22 Jul 2026 11:41:26 +0000

Experimental module

The AiDev module is experimental and not stable. There is no backward compatibility promise for this module. We welcome your feedback and contributions as we continue to develop and improve this module.

Overview

The AI Dev SDK ships a set of skills and agents that codify common Spryker workflows. They reach your project in two ways:

Via the ai-dev:setup console command — copies the skills and agents into your project’s AI-tool directories (.claude/skills/ + .claude/agents/, .windsurf/skills/ + .windsurf/agents/, and so on). Works for every AI tool listed on the AI Dev SDK Overview that supports an agents directory. Codex CLI is the one exception — it has no agents directory, so agents are skipped for that tool.
Via the Claude Code plugin — for Claude Code users, the Claude Code Plugin installs the same skills and agents through the official marketplace, no console command required.

Both delivery paths read from the same source files — the plugin just packages them for marketplace installation.

What’s the difference between a skill and an agent?

Skills load into the active chat on demand. Use them when you want the assistant to follow a specific workflow (write a product requirement document, refresh caches, run QA).
Agents are isolated sub-conversations the assistant delegates to. Use them when you want focused, single-purpose work done in its own context window (verify a behavior, diagnose a failure).

You do not need to remember the names — the assistant picks the right skill or agent from your prompt. The tables below explain what each one does so you know what to expect.

How to invoke

In most cases you do not need to call a skill or agent by name. Describe what you want — “build this feature”, “verify the new fee shows on the cart”, “write a product requirement document for…” — and the assistant matches your wording to the right skill or agent from the set installed in your project.

If you want to invoke one explicitly:

Claude Code plugin — every skill is also available as a slash command. Type /<skill-name> (for example /spryker-customization) and the skill loads into the current chat. The full list of commands is on the Claude Code Plugin page.
Other AI tools — invocation follows the tool’s own convention for skills and agents. In Cursor, Windsurf, Copilot, OpenCode, and Codex CLI, the skills and agents land in the tool-specific directories (.cursor/, .windsurf/, etc.) and are picked up automatically by your assistant. The AI Dev SDK Overview lists the output paths per tool.
Agents (subagents) are not invoked by the user directly — they are spawned by the assistant or by a parent skill when the work calls for an isolated context. You can suggest one by name in your prompt (“use the spryker-verifier to…”), but the assistant decides when to spawn.

Skills

Skills are delivered through ai-dev:setup (all supported AI tools) or the Claude Code plugin.

Skill	Purpose	Benefits
`ai-dev-setup`	Generate rules, an agents/context file, and skills for the project and the chosen AI tool	One command sets up consistent AI tooling for the whole team
`code-review`	Review staged or PR changes against Spryker coding standards	Catches Spryker-specific issues before they reach a pull request
`propel-schema`	Create and modify Propel ORM schema files	Follows Spryker schema conventions automatically
`data-import`	Create and modify data import CSV files and importers	Generates importers that fit Spryker’s data-import path
`codecept-functional`	Generate Codeception functional tests	Tests follow Spryker test patterns out of the box
`static-validation`	Run and interpret static analysis tools (PHPStan, PHP CS Fixer)	Quick diagnosis of style and type issues without context-switching
`payment-template`	Scaffold payment method integration	Follows Spryker payment module patterns end-to-end
`yves-atomic-frontend`	Create atomic design components for the Yves storefront	Components match the project’s atomic conventions
`product-requirement-document`	Turn a feature idea into a research-grounded product requirement document before any code is written	Spec-before-code; assigns a real Spryker actor to every story; cuts ambiguity before implementation
`spryker-customization`	Walk a product requirement document or set of acceptance criteria through to a committed branch	One workflow drives the full build; quality bar (PoC or MVP) chosen up-front; delegates focused work to the agents below; never auto-commits
`spryker-bugfix`	Drive a bug from an optional tracker ticket or a plain description through to a committed, validated, QA-accepted fix	Orchestrates reproduce, root-cause, minimal fix, functional test, static validation, review, QA, and final verification; a shared attempt budget loops back on any failed gate; Autonomous mode adds a pushed Draft PR with a remote-CI watch loop
`spryker-refresher`	Run the right post-change console and composer commands after edits	Owns the file-to-command mapping (codegen, caches, frontend builds, class-resolver); no missed cache rebuilds
`spryker-qa-coverage`	Turn acceptance criteria into a four-bucket test plan executed against the live app	Coverage goes beyond literal ACs — happy / negative / authorization / corner cases; reports pass/fail with real evidence
`spryker-docs-research`	Look up the right answer in official Spryker documentation	Grounds AI work in documented behavior rather than the model’s memory; falls back gracefully when MCP tools are unavailable
`spryker-runtime`	Drive the running Spryker application — Yves, Back Office, Merchant Portal, console, HTTP	Real authenticated sessions; read-only DB / Redis / queue inspection; reusable building block for higher-level skills and agents
`ai-runtime-debugging`	Inspect Spryker runtime state safely from an AI session	`[AI-DEBUG]` tagged-log pattern plus optional XDebug step-debug; built-in cleanup of debug instrumentation before commit

Agents

Agents are delivered through ai-dev:setup (every supported AI tool with an agents directory) or the Claude Code plugin.

Agent	Purpose	Benefits
`spryker-code-reviewer`	Review code against Spryker’s coding standards and architectural rules	Deeper, Spryker-aware review than a generic linter; catches layer-architecture and module-convention issues
`spryker-feature-expert`	Answer “how does feature X work in this project / in Spryker”	Pushes back when the user’s framing reinvents an existing primitive; surfaces canonical patterns first; never edits code
`spryker-verifier`	Verify that a specific behavior holds in the running Spryker environment	Returns PASS / FAIL / BLOCKED per acceptance criterion with raw evidence; never lies green; never tries to fix
`spryker-issue-diagnoser`	Investigate why something failed and return a root cause	Reads logs, DB state, queue, search, browser console — returns a suggested direction; never attempts the fix itself
`spryker-data-seeder`	Create small additive test data through Spryker’s existing import path	Safe and incremental — CSV + `data:import` only; never edits code, never writes directly to the database
`spryker-screenshot-collector`	Capture screenshots and GIFs of pages and flows for demos and documentation	Pure capture — never asserts whether something works, never investigates failures, never edits

Claude Code Plugin

Wed, 22 Jul 2026 11:41:26 +0000

Experimental module

Project must be running

The MCP server runs inside your Spryker Docker container. Start your project with docker/sdk run before using any skills that rely on MCP tools.

Overview

Working with Spryker in an AI coding assistant without project-specific context leads to a predictable pattern: the AI generates plausible-looking code that does not follow Spryker’s layer architecture, uses the wrong patterns, or misses module conventions entirely. You end up spending more time correcting mistakes than you saved.

The spryker-ai-dev-sdk Claude Code plugin closes this gap. It gives Claude Code deep knowledge of how Spryker projects are structured — layers, namespaces, plugin stacks, transfer objects, OMS flows — so the code it generates fits your project from the start instead of requiring repeated corrections.

What it does for you:

No more explaining Spryker basics. Rules covering 20 Spryker architectural patterns are automatically loaded into every session. Claude Code knows about factories, dependency providers, expanders, mappers, and more without you having to explain them.
Correct code on the first attempt. Skills for common Spryker tasks — Propel schema changes, data importers, functional tests, payment integrations, atomic frontend components — follow the exact conventions your project expects.
Live project context. The MCP server runs inside your Docker container and gives Claude Code real-time access to your transfer objects, module interfaces, and OMS configuration. The AI works with your actual project data, not guesses.
Consistent code reviews. The spryker-code-reviewer subagent checks your changes against Spryker’s coding standards and architectural rules, catching issues before they reach a PR.
Team-wide consistency. Generated rules and context files are committed to your repository, so every developer on the team works with the same AI configuration.

The plugin is distributed through the spryker-plugins-official marketplace and installed directly inside Claude Code.

Prerequisites

Claude Code installed
Your Spryker project is running: docker/sdk run

Install the plugin from the marketplace

Open Claude Code in your terminal.
Add the Spryker plugin marketplace:
Install the plugin:
After installation, reload plugins in Claude Code.

Set up AI tooling for your project

After installing the plugin, run the ai-dev-setup skill to configure your project. The skill generates rules, context files, and reusable AI skills tailored to your project and AI tool.

In Claude Code, run the setup skill:

The skill:

Installs the spryker-sdk/ai-dev package in your Spryker project.
Wires up console commands for McpServerConsole and AiToolSetupConsole.
Registers the AI Dev MCP server with Claude Code.
Adds .claude/rules/ with Spryker coding conventions and architectural guidelines.
Adds CLAUDE.md with project-specific context loaded into every Claude Code session.

Check with running /context in Claude Code to see:

Capabilities

For a one-page reference of every skill and agent — what each does, when to use it, and the value it adds — see AI Dev SDK Skills and Agents.

Skills

The plugin bundles the following Spryker-aware skills. Invoke them in Claude Code with the / prefix.

Skill	Command	Description
AI Dev Setup	`/spryker-ai-dev-sdk:ai-dev-setup`	Generates rules, a context file, and skills for your project and AI tool
Code Review	`/spryker-ai-dev-sdk:code-review`	Reviews staged or PR changes against Spryker coding standards
Propel Schema	`/spryker-ai-dev-sdk:propel-schema`	Helps create and modify Propel ORM schema files following Spryker conventions
Data Import	`/spryker-ai-dev-sdk:data-import`	Assists with creating and modifying data import CSV files and importers
Codecept Functional	`/spryker-ai-dev-sdk:codecept-functional`	Generates Codeception functional tests following Spryker test patterns
Static Validation	`/spryker-ai-dev-sdk:static-validation`	Runs and interprets static analysis tools (PHPStan, PHP CS Fixer)
Payment Template	`/spryker-ai-dev-sdk:payment-template`	Scaffolds payment method integration following Spryker payment module patterns
Yves Atomic Frontend	`/spryker-ai-dev-sdk:yves-atomic-frontend`	Helps create atomic design components for the Yves frontend
Product Requirement Document	`/spryker-ai-dev-sdk:product-requirement-document`	Drafts a research-grounded product requirement document for a Spryker feature before implementation
Spryker Customization	`/spryker-ai-dev-sdk:spryker-customization`	Orchestrates the end-to-end build of a customization from product requirement document to committed branch
Spryker Bugfix	`/spryker-ai-dev-sdk:spryker-bugfix`	Orchestrates the end-to-end bug fix from a ticket or description to a committed, validated, QA-accepted branch (Autonomous mode adds a pushed Draft PR with a CI watch loop)
Spryker Refresher	`/spryker-ai-dev-sdk:spryker-refresher`	Runs the right post-change console and composer commands after edits
Spryker QA Coverage	`/spryker-ai-dev-sdk:spryker-qa-coverage`	Turns acceptance criteria into a four-bucket test plan and executes it against the running app
Spryker Docs Research	`/spryker-ai-dev-sdk:spryker-docs-research`	Looks up grounded answers in the official Spryker documentation
Spryker Runtime	`/spryker-ai-dev-sdk:spryker-runtime`	Drives the running Spryker application — storefront, back office, console, HTTP
AI Runtime Debugging	`/spryker-ai-dev-sdk:ai-runtime-debugging`	Adds tagged debug logs (and optional XDebug) for inspecting Spryker runtime state

Subagents

The plugin includes the following subagents. They are isolated sub-conversations that the assistant delegates to for focused, single-purpose work:

Subagent	Description
`spryker-code-reviewer`	Performs deep code reviews of your changes against Spryker architectural patterns, coding standards, and best practices
`spryker-feature-expert`	Answers questions about how a Spryker feature, module, or capability works, grounded in docs and the project’s actual code
`spryker-verifier`	Verifies a specific behavior in the running Spryker environment and returns PASS, FAIL, or BLOCKED per acceptance criterion with raw evidence
`spryker-issue-diagnoser`	Investigates a failure across logs, database, queue, search, and browser state and returns a root cause
`spryker-data-seeder`	Creates small additive test data through Spryker’s existing data import path
`spryker-screenshot-collector`	Captures screenshots and short GIFs of pages and flows for demos and documentation

Rules

The ai-dev-setup skill writes a set of Spryker-specific coding rules into your project. These rules guide the AI to follow Spryker conventions automatically, without requiring you to explain them in every prompt.

Rule file	What it enforces
`business-models.md`	Business model structure and responsibilities
`client-zed-communication.md`	Client–Zed gateway communication patterns
`controller.md`	Controller conventions and responsibilities
`dependency-provider.md`	Dependency provider wiring and plugin stacks
`enforce-constants-for-control-flow.md`	Use of constants instead of magic strings in control flow
`expander-pattern.md`	Expander pattern for extending transfer objects
`factory-pattern.md`	Factory class structure and dependency injection
`form-data-loading-performance.md`	Performant data loading in Zed forms
`layer-communication.md`	Cross-layer call rules (Presentation → Communication → Business → Persistence)
`mapper-pattern.md`	Mapper pattern for transfer-to-transfer and entity-to-transfer mappings
`module-config.md`	Module configuration class conventions
`naming-conventions.md`	Class, method, and variable naming standards
`owasp.md`	OWASP security guidelines applied to Spryker code
`performance.md`	Performance best practices (query optimization, caching)
`persistence.md`	Persistence layer conventions (repositories, entity managers)
`php-code-style.md`	PHP code style rules (PSR compliance, formatting)
`plugins.md`	Plugin and plugin interface implementation patterns
`table.md`	Back Office table and query container conventions
`transfer-object.md`	Transfer object usage and immutability rules
`upgradability.md`	Backward compatibility and upgradability guidelines

Context file

The ai-dev-setup skill generates a CLAUDE.md context file based on the AGENTS.example.md template. This file is automatically loaded into every Claude Code session and provides:

Common Docker CLI commands for your Spryker project
Spryker application layer overview (Zed, Yves, Glue, Client, Service, Shared)
Namespace and directory structure
Component rules for controllers, plugins, factories, repositories, and more
Abstract class references for all layers

Starting point, not a complete setup

The files generated by ai-dev-setup are a baseline derived from Spryker defaults. They cover general Spryker conventions but do not include anything specific to your project — custom modules, third-party integrations, team conventions, or environment details. Treat the generated CLAUDE.md and rules as a starting point and extend them with your project-specific requirements.

Release notes 202606.0

Tue, 21 Jul 2026 12:48:50 +0000

Spryker Cloud Commerce OS is an end-to-end solution for digital commerce. This document contains a business-level description of new features and improvements. For information about installing Spryker, see [Getting started guide](/docs/dg/dev/development-getting-started-guide). ## B2B Business-Ready Commerce Experiences ### Recurring Orders {% include badge.html type="early-access,feature" %} Recurring Orders let buyers create cadence-based repeat purchases during checkout and execute them automatically on a defined schedule. The feature includes controls for confirmations and approvals, as well as review and recovery flows for basket changes, price changes, or ERP-related issues. **Key capabilities:** - Create recurring order schedules such as weekly, bi-weekly, or monthly - Support buyer-controlled confirmations, skips, modifications - Detect basket drift, price drift, and ERP errors with clear recovery flows **Business benefits:** - Reduces manual effort for repeat procurement - Helps prevent missed or delayed replenishment orders - Increases trust through controlled automation, governance, and auditability **Documentation:** - [Recurring Orders Feature Overview](/docs/pbc/all/order-experience-management/latest/base-shop/feature-overviews/recurring-orders-feature-overview.html) - [Install Recurring Orders](/docs/pbc/all/order-experience-management/latest/base-shop/install-and-upgrade/install-features/install-the-recurring-orders-feature) ### Budget & Cost Centers {% include badge.html type="feature" %} Budget & Cost Centers introduces native purchasing controls for departmental or project-based spending in B2B commerce. Companies can manage budgets and cost centers directly in Spryker to support compliant, auditable, and policy-driven purchasing workflows. **Key capabilities:** - Define and manage cost centers for purchasing activities - Enforce budgets directly within procurement workflows - Align spend controls with existing approval processes **Business benefits:** - Reduces overspending risk through built-in budget enforcement - Improves financial transparency across teams and projects - Streamlines procurement with consistent spend governance in one system **Documentation:** - [Purchasing Control Feature Overview](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview) - [Install Purchasing Control](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature) ### New Spryker Design System Storefront We extended the Spryker design system across key storefront pages, including product listing, product detail, and cart pages. This creates a more consistent and modern buyer experience while giving teams reusable components for faster delivery. **Key capabilities:** - Design system applied across the product details page - New reusable components such as cart entries, pagination, and quantity selectors - Storybook documentation for reference and reuse **Business benefits:** - Improves buyer trust with a more polished storefront experience - Reduces future implementation and QA effort through reusable patterns - Strengthens Spryker's out-of-the-box storefront for demos and evaluations

### Search Statistics & Google Analytics {% include badge.html type="feature" %} Search Statistics brings native search analytics to the Back Office for customers using ElasticSearch. Business users can review frequent searches and zero-result searches to better understand buyer behavior and optimize product discovery. **Key capabilities:** - View top frequent searches and top zero-result searches in the Back Office - Filter analytics by time period and review detailed search data - Export search statistics to Google Analytics for further analysis and sharing **Business benefits:** - Reduces the need for custom project-specific search analytics implementations - Helps teams improve search relevance, synonyms, and catalog quality based on real data - Identifies search gaps that can negatively affect discoverability and conversion **Documentation:** - [Search Statistics Feature Overview](/docs/pbc/all/miscellaneous/latest/third-party-integrations/marketing-and-conversion/analytics/google-analytics/search-statistics) - [Install Search Statistics](/docs/pbc/all/miscellaneous/latest/third-party-integrations/marketing-and-conversion/analytics/google-analytics/install-search-statistics) ### Back Office usability improvements {% include badge.html type="improvement" %} We improved several Back Office interactions to make administration tasks clearer and less error-prone. This covers block and slot assignment validation. **Key capabilities:** - Restores validation feedback when saving block and slot assignments - Fixes missing menu highlight on the View Merchant page in the Back Office **Business benefits:** - Improves clarity during Back Office administration - Helps business users navigate merchant management more easily **Releases:** - [No validation errors when saving block + slot assignment](https://api.release.spryker.com/release-group/6509) ### PunchOut support in the Back Office {% include badge.html type="improvement" %} PunchOut support in the Back Office makes PunchOut integrations easier to configure and manage with a more low-code approach. Building on Spryker's native support for common PunchOut flows and cXML/OCI compatibility, this update adds a dedicated PunchOut section with relevant fields and configuration support. This helps solution teams deliver integrations with less custom development effort. **Key capabilities:** - Adds a dedicated PunchOut section in the Back Office - Supports configuration of relevant PunchOut integration fields in a more low-code way - Complements native cXML, OCI, and core PunchOut message handling capabilities **Business benefits:** - Reduces bespoke development effort for PunchOut integrations - Makes implementations more repeatable and faster across projects - Simplifies setup and maintenance for customers and implementation partners

**Documentation:** - [PunchOut Gateway](/docs/pbc/all/punchout-gateway/punchout-gateway.html) ### PunchCommerce Punchout Connector {% include badge.html type="feature" %} The PunchCommerce Punchout Connector extends Spryker's support for complex PunchOut scenarios through a partner integration. It is designed for use cases that require multiple eProcurement connectors and document handling beyond Spryker's native capabilities. This helps customers address more advanced procurement integration requirements. **Key capabilities:** - Connects Spryker with PunchCommerce for advanced PunchOut scenarios - Supports use cases with multiple eProcurement connectors - Adds support for document-handling requirements not covered by native capabilities **Business benefits:** - Broadens PunchOut coverage for more complex B2B procurement scenarios - Reduces the need for bespoke implementations in advanced projects - Expands ecosystem support through a specialized partner solution **Documentation:** - [https://gitlab.netzdirektion.de/packages/punchcommerce-spryker-module](https://gitlab.netzdirektion.de/packages/punchcommerce-spryker-module) ## Connected, and AI-Enabled Platform ### AI Dev SDK: AI-Assisted Customization for Spryker Projects {% include badge.html type="early-access" %} The AI Dev SDK helps teams customize Spryker projects faster and with less manual effort. It supports developers in generating quick proofs of concept and MVP customizations that follow Spryker's patterns and project conventions, with developers staying in control at each approval point. This helps teams validate ideas faster, keep customization quality more consistent, and lower the manual effort each one takes.

**Key capabilities:** - Orchestrates the full Spryker customization workflow, from research and planning through code generation, testing, and verification, with self-correction when issues are detected and developer approval at key checkpoints - Automates the technical work needed after every code change, including database migrations, cache rebuilds, and frontend builds - Offers two quality levels: quick PoC for validating ideas fast, and MVP for delivering code that follows Spryker's canonical patterns and project conventions **Business benefits:** - Speeds up delivery of Spryker customizations, whether a quick proof of concept or an MVP-grade build. - Reduces development effort and catches issues against Spryker and project standards earlier. - Lowers the cost of experimentation — quick PoCs make it cheap to validate an idea before investing in a full implementation. **Documentation:** - [AI Dev SDK Skills and Agents](/docs/dg/dev/ai/ai-dev/ai-dev-skills-and-agents.html) - [AI Dev SDK Customization Workflow](/docs/dg/dev/ai/ai-dev/ai-dev-customization-workflow.html) - [Claude Code Plugin](/docs/dg/dev/ai/ai-dev/ai-dev-claude-code-plugin.html) ### AI Commerce: Smart CMS for AI-assisted content creation {% include badge.html type="early-access" %} Smart CMS brings AI assistance directly into the CMS page and block creation in the Back Office. Content editors and business users can generate structured text content in-flow instead of writing or copying content manually. This reduces the effort required to create and update commerce content experiences at scale. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_smart_cms_1.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_smart_cms_2.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_smart_cms_3.png||" %} **Key capabilities:** - Generates CMS page and block content directly in the Back Office authoring flow - Accepts source attachments, such as documents with customer questions, to generate structured content like FAQ pages - Understands Spryker-specific content items so generated content fits existing content structures **Business benefits:** - Reduces manual effort for routine content creation and updates - Improves productivity for content editors and business admins - Helps scale content operations more efficiently as content needs grow **Documentation:** - [Smart CMS Content Assistant](/docs/pbc/all/ai-commerce/latest/smart-cms-content-assistant) - [Install Smart CMS Content Assistant](/docs/dg/dev/ai/ai-commerce/content-assistant/install-smart-cms-content-assistant#prerequisites) ### AI Foundation: Back Office AI Configuration {% include badge.html type="early-access" %} AI Foundation now includes a unified configuration experience in the Back Office for managing AI providers, models, prompts, and feature-specific behavior. This gives business and operational users a clearer, more consistent way to activate and control AI-powered capabilities, including switching AI vendors or models on the fly, without developer involvement or redeployment. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_ai_configuration_1.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_ai_configuration_2.png||" %} **Key capabilities:** - Centralizes AI provider and credential management in one configuration area - Supports feature-level enablement and control of AI behavior, including AI vendor, model, and prompt configuration, with no code changes or deployments required - Provides an extensible foundation designed to support additional AI-powered features over time **Business benefits:** - Simplifies setup and onboarding for AI-powered features - Gives merchants more control over AI behavior, output quality, and governance - Reduces configuration errors and repetitive administrative work **Documentation:** - [Configure multiple AI providers for AI Commerce](/docs/dg/dev/ai/ai-commerce/configure-multiple-ai-providers) ### AI Foundation: Back Office AI Cost Estimator {% include badge.html type="early-access" %} The AI Cost Estimator adds estimated AI cost visibility to the AI Audit Logs in the Back Office. Admins can configure model pricing once and then see estimated costs per interaction, total estimated spend, and breakdowns by provider and model. This makes it easier to understand the cost of individual AI-powered commerce features and make informed decisions about their value and continued use. {% include carousel.html images=" https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_ai_cost_estimator_1.png||:: https://spryker.s3.eu-central-1.amazonaws.com/docs/About/Releases/release-notes-202606/bo_ai_cost_estimator_2.png||" %} **Key capabilities:** - Shows estimated cost per AI interaction in the Audit Logs page - Provides total estimated cost and provider and model-level cost breakdowns based on active filters - Uses customer-configured provider and model prices, including support for multiple currencies **Business benefits:** - Improves visibility into AI operating costs across commerce features - Supports better governance and value assessment of AI capabilities - Reduces manual work previously needed to estimate AI spend from token usage **Documentation:** - [AI Audit Logs & Cost Estimations](/docs/dg/dev/ai/ai-foundation/ai-foundation-audit-logs) ### GLUE REST API migration to API Platform {% include badge.html type="feature" %} Spryker has modernized its internal GLUE REST API infrastructure by migrating it to API Platform. This change is backward compatible for existing API clients, while making APIs easier to maintain, extend, and evolve internally. It also improves the foundation for delivering new endpoints and capabilities faster. **Key capabilities:** - Keeps existing external API contracts unchanged for current clients and consumers - Replaces custom internal API infrastructure with API Platform - Enables more standardized API generation, validation, and documentation **Business benefits:** - Accelerates API delivery and reduces development effort for new endpoints - Improves maintainability and extensibility of the API layer - Supports more consistent and predictable machine-to-machine integrations **Documentation:** - [API Strategy](/docs/integrations/spryker-glue-api/getting-started-with-apis/api-strategy.html) - [Spryker API roadmap and adoption](/docs/integrations/spryker-glue-api/getting-started-with-apis/api-roadmap-and-adoption#whats-on-the-roadmap.html) - [Storefront API B2B Demo Shop reference](/docs/integrations/spryker-glue-api/storefront-api/api-references/storefront-api-b2b-demo-shop-reference.html) ### Backend API added to the Spryker API Strategy {% include badge.html type="feature" %} Spryker extended its API strategy to cover the Backend API, the application for administrative and system-to-system integrations. The strategy now documents the API types available under the Backend API—starting with the Back Office API you can build on today—and the types planned on the roadmap, all built on API Platform integration. As with the rest of the strategy, existing Glue Backend APIs remain fully supported with no End-of-Life and no forced migration. **Key capabilities:** - Documents the Backend API application and its API types, and clarifies that the Backend API application is distinct from the Back Office API type - Back Office API is available today for administrator-level and trusted internal integrations - Roadmap types documented for planning: Merchant API, Merchant Data Exchange API, Data Exchange API, and Async Event API - Guidance for choosing a Backend API type by caller and data-flow shape—record-by-record, bulk, or event-driven **Business benefits:** - Gives a clear, forward-looking view of backend integration options across administration, merchant, data exchange, and events - Protects existing Glue Backend API investments with a no-End-of-Life, no-forced-migration commitment - Speeds up planning for ERP, PIM, OMS, and marketplace integrations with consistent guidance **Documentation:** - [Spryker API Strategy](/docs/integrations/spryker-glue-api/getting-started-with-apis/api-strategy.html) - [Spryker API roadmap and adoption](/docs/integrations/spryker-glue-api/getting-started-with-apis/api-roadmap-and-adoption.html) ## Efficient and Flexible Cloud Foundation ### Propel 2.0 LTS {% include badge.html type="improvement" %} This work includes advancing Propel toward a stable release and increasing active maintenance. **Documentation:** - [PropelORM](https://github.com/propelorm/Propel2/releases/tag/2.0.0) ### Maintenance and service updates {% include badge.html type="improvement" %} We rolled out regular maintenance and service updates across cloud components to keep environments secure, stable, and maintainable. This includes updates to core services and supporting infrastructure components. These changes help reduce operational risk and technical debt over time. **Key capabilities:** - Updates core services and infrastructure components such as Nginx 1.30, and Docker images - Improves long-term maintainability of cloud services - Updated multiple dependencies **Business benefits:** - Improves system reliability and operational resilience - Updates `shell-quote` to a patched version addressing a critical shell injection vulnerability. - Upgrades `symfony/runtime` to address unsafe request argument handling. - Upgrades `symfony/monolog-bridge` to address unauthenticated log listener exposure. **Documentation:** - [Docker Images](/docs/about/all/releases/image-releases/spryker-php/release-notes-spryker-php-20260608.html) ### Key-Value Storage Optimization for Dynamic Store Mode {% include badge.html type="improvement" %} We optimized key-value storage usage for Dynamic Store Mode to reduce duplicated data across store and locale combinations. This improvement lowers Valkey/Redis memory consumption and key volume while keeping the solution backward compatible and opt-in. It is especially valuable for deployments with multiple stores and locales. **Key capabilities:** - Reduces duplicated product abstract and URL storage data in Dynamic Store Mode - Keeps compatibility with existing storage formats and supports gradual adoption - Provides an opt-in configuration and migration path for controlled rollout **Business benefits:** - Improves scalability for multi-store and multi-locale setups - Helps delay or avoid costly cache instance size increases **Documentation:** - [KV Storage Deduplication](/docs/dg/dev/guidelines/performance-guidelines/kv-storage-deduplication.html) ### Queue processing resilience and worker behavior {% include badge.html type="improvement" %} We improved queue processing behavior to reduce the risk of blocked or stalled message handling. The update addresses long-running worker processes, retry queue handling, and premature worker exits while messages are still waiting. **Key capabilities:** - Improves handling of long-running or stuck queue worker child processes - Prevents failed messages from being lost when no retry queue exists - Ensures `queue:worker:start --stop-when-empty` behaves more reliably **Business benefits:** - Reduces the risk of blocked publish and processing pipelines - Improves operational stability for queue-based workloads - Helps teams recover from processing failures more predictably **Documentation:** - [Publish and synchronization (queue and event performance)](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated#publish-and-synchronization-queue-and-event-performance) - [Enable queue worker wait limit](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines#enable-queue-worker-wait-limit) ### Cloud security improvements {% include badge.html type="improvement" %} We delivered a set of cloud security improvements to strengthen infrastructure protection and reduce unnecessary access paths. These updates address container-to-instance access risks, improve IAM controls, and support more secure cloud operations. They also include compatibility adjustments for newer managed service defaults. **Key capabilities:** - Tightens IAM policy controls to prevent overly broad administrative permissions in customer PaaS accounts - Adds compatibility handling for MariaDB 11.8 secure transport defaults in infrastructure templates **Business benefits:** - Reduces the risk of unauthorized access to cloud resources and secrets - Improves security posture across customer environments - Helps maintain secure operations as infrastructure components evolve ### RDS Auditability Extensions {% include badge.html type="feature" %} We have introduced advanced activity tracking for database operations to enhance security governance and accountability across your environments. This update provides clear visibility into data modifications and structural changes within your live production systems. **Key capabilities:** - Monitors and records database operations performed in production environments - Securely retains activity logs for a rolling two-year period to satisfy standard corporate compliance and security policies. **Business benefits:** - Provides complete transparency into exactly who executed which database operation, ensuring robust compliance and clear user accountability - Enhances Security Auditing: Simplifies the detection of potential application exploits—such as SQL injections—by tracking critical service account behaviors ### Persistent Jenkins Configuration {% include badge.html type="improvement" %} We have updated our cloud automation storage model to significantly improve platform stability. This enhancement ensures that your custom adjustments are safely preserved during routine platform updates and security maintenance. **Key capabilities:** - Permanently safeguards all manually created configurations and fine-tunings across system upgrades and server restarts - Unlocks continuous, automated operating system upgrades and critical infrastructure patching to keep your system completely protected **Business benefits:** - Eliminates the risk of losing bespoke operational settings, removing the need for costly and repetitive manual reconfiguration work - Enhances your overall security posture by allowing the seamless deployment of critical patches without disrupting business continuity ### Customer authentication and session handling {% include badge.html type="improvement" %} We fixed issues affecting customer authentication and session behavior in edge cases. These changes improve reliability for API authentication and login flows. **Key capabilities:** - Prevents unintended API authentication behavior related to `spy_customer.registered = NULL` - Improves error handling for invalid JWT tokens in warehouse token requests - Avoids false-positive WAF blocking caused by specific patterns that are not malicious. **Business benefits:** - Improves trust in authentication flows - Reduces login-related support cases - Helps secure customer access scenarios more consistently **Documentation:** - [spy_customer.registered=NULL allows API auth](https://api.release.spryker.com/release-group/6618) - [Adjusted Quote data and UI fixes](https://api.release.spryker.com/release-group/6621) - [Added optional base64 encoding for gateway](https://api.release.spryker.com/release-group/6633) ### Voucher code tracking and order display accuracy in the Back Office {% include badge.html type="improvement" %} We fixed issues with orders that use multiple voucher-code discounts. The Back Office now shows the correct voucher code for each applied discount, and usage counters are updated correctly for all voucher codes used in an order. **Key capabilities:** - Displays the actual voucher code used for each discount in the Back Office order overview. - Correctly increments usage counters for all voucher codes applied to an order. - Supports orders with multiple non-exclusive voucher-based discounts more accurately. **Business benefits:** - Improves trust in discount reporting and order auditability. - Reduces manual verification effort for merchandising and support teams. - Ensures voucher campaign performance is tracked correctly. **Release:** - [Multiple voucher codes on order](https://api.release.spryker.com/release-group/6640) ### Product and catalog experience improvements {% include badge.html type="improvement" %} We improved several product-related experiences in the Back Office and storefront to make catalog management and shopping journeys more reliable. The update covers product images in Zed, product readiness visibility, replacement product rendering, and marketplace product offer handling in carts. **Key capabilities:** - Restores product concrete image visibility in the Back Office **Business benefits:** - Gives business users clearer product status information - Reduces confusion during catalog maintenance in the Back Office - Improves cart accuracy for marketplace shopping scenarios **Documentation:** - [Show Product Concrete images in Zed](https://api.release.spryker.com/release-group/6501) ### Storefront performance, search, and content management improvements {% include badge.html type="improvement" %} We improved storefront performance, search reliability, content management efficiency, and product data consistency to deliver faster customer experiences, more accurate search results, and better scalability across high-volume environments. **Key capabilities:** - Improves checkout and customer-facing page performance by reducing unnecessary backend requests and eliminating Redis bottlenecks for large datasets. - Enhances product data publishing and search indexing to keep Storage and Search synchronized with catalog changes across multi-store and multi-locale environments. - Generates search index mappings correctly for advanced analyzer and multi-field configurations. - Optimizes CMS page version history loading for better Back Office performance when managing long-lived content. - Preserves locale selection across storefront, configurator, agent emulation, and authentication flows for a more consistent user experience. **Business benefits:** - Delivers faster storefront and checkout experiences, even at scale. - Improves search accuracy and product data consistency across channels. - Enhances Back Office productivity for content managers. - Reduces backend load and improves platform scalability. - Provides a more consistent localized shopping experience for customers and support agents. **Documentation and Releases:** - [Cart page and checkout for large carts](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated#cart-page-and-checkout-for-large-carts-100-items) - [Adjusted reading shipment type uuids on Checkout](https://api.release.spryker.com/release-group/5736) - [Added child fields to index map](https://api.release.spryker.com/release-group/6616) - [CMS page versions query for the form loads too much data](https://api.release.spryker.com/release-group/6630) - [Remediate error in spryker/category >= 5.23.0](https://api.release.spryker.com/release-group/6452) - [Remove Concrete Product on deactivation](https://api.release.spryker.com/release-group/6500) - [Remove product concrete from the search index](https://api.release.spryker.com/release-group/6574) - [Locale selection preserved when navigating in the Storefront](https://api.release.spryker.com/release-group/6521) - [Performance improvements to the checkout](https://api.release.spryker.com/release-group/6479)

Add a custom Back Office Assistant agent

Mon, 20 Jul 2026 08:24:20 +0000

Back Office Assistant routes each conversation to the most appropriate agent through its intent router. To handle a new domain—for example, managing customers or CMS content—implement a custom agent and register it alongside the built-in agents described in Back Office Assistant.

1) Implement the agent plugin

Create a plugin that implements BackofficeAssistantAgentPluginInterface from SprykerFeature\Zed\AiCommerce\Dependency\BackofficeAssistant:

METHOD	PURPOSE
`getName()`	Returns the unique agent name used for routing. This value is matched against the intent router’s response.
`getDescription()`	Describes what the agent handles. The intent router AI uses this description to decide which agent matches the user’s request, so make it specific about the agent’s domain and capabilities.
`isApplicable()`	Returns whether the agent is available for routing. Use this to gate the agent behind a configuration flag, similar to the built-in agents.
`executeAgent()`	Builds a `PromptRequestTransfer`, calls `AiFoundationFacade::prompt()`, and maps the result into a `BackofficeAssistantPromptResponseTransfer`.

<?php

namespace Pyz\Zed\AiCommerce\Communication\Plugin\Agent;

use Generated\Shared\Transfer\BackofficeAssistantPromptRequestTransfer;
use Generated\Shared\Transfer\BackofficeAssistantPromptResponseTransfer;
use Generated\Shared\Transfer\CustomerManagementAgentResponseTransfer;
use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Spryker\Shared\AiFoundation\AiFoundationConstants;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use SprykerFeature\Zed\AiCommerce\Dependency\BackofficeAssistant\BackofficeAssistantAgentPluginInterface;

/**
 * @method \Pyz\Zed\AiCommerce\Communication\AiCommerceCommunicationFactory getFactory()
 * @method \Pyz\Zed\AiCommerce\AiCommerceConfig getConfig()
 */
class CustomerManagementAgentPlugin extends AbstractPlugin implements BackofficeAssistantAgentPluginInterface
{
    protected const string NAME = 'Customer Management';

    protected const string TOOL_SET_CUSTOMER_MANAGEMENT = 'customer_management_tools';

    public function getName(): string
    {
        return static::NAME;
    }

    public function getDescription(): string
    {
        return 'Answers questions about customer accounts, addresses, and status. Use for customer lookup and account management questions.';
    }

    public function isApplicable(
        BackofficeAssistantPromptRequestTransfer $backofficeAssistantPromptRequest,
    ): bool {
        return $this->getConfig()->isCustomerManagementAgentEnabled();
    }

    public function executeAgent(
        BackofficeAssistantPromptRequestTransfer $backofficeAssistantPromptRequest,
    ): BackofficeAssistantPromptResponseTransfer {
        $promptRequest = (new PromptRequestTransfer())
            ->setAiConfigurationName($this->getConfig()->getCustomerManagementAgentAiConfigurationName())
            ->setConversationReference($backofficeAssistantPromptRequest->getConversationReference())
            ->setStructuredMessage(new CustomerManagementAgentResponseTransfer())
            ->addToolSetName(static::TOOL_SET_CUSTOMER_MANAGEMENT)
            ->setPromptMessage(
                (new PromptMessageTransfer())
                    ->setType(AiFoundationConstants::MESSAGE_TYPE_USER)
                    ->setContent($backofficeAssistantPromptRequest->getPrompt())
                    ->setAttachments($backofficeAssistantPromptRequest->getAttachments()),
            );

        $promptResponse = $this->getFactory()->getAiFoundationFacade()->prompt($promptRequest);

        $backofficeAssistantPromptResponse = new BackofficeAssistantPromptResponseTransfer();

        if (!$promptResponse->getIsSuccessful()) {
            return $backofficeAssistantPromptResponse;
        }

        /** @var \Generated\Shared\Transfer\CustomerManagementAgentResponseTransfer $customerManagementAgentResponse */
        $customerManagementAgentResponse = $promptResponse->getStructuredMessage();

        $backofficeAssistantPromptResponse->setAgent($customerManagementAgentResponse->getAgent());
        $backofficeAssistantPromptResponse->setMessage($customerManagementAgentResponse->getMessage());
        $backofficeAssistantPromptResponse->setReasoningMessage($customerManagementAgentResponse->getReasoningMessage());

        return $backofficeAssistantPromptResponse;
    }
}

Info

The CustomerManagementAgentResponseTransfer structured message transfer, the isCustomerManagementAgentEnabled() and getCustomerManagementAgentAiConfigurationName() config methods, and the customer_management_tools toolset are project-specific and must be defined as part of this implementation. Model the response transfer on the existing GeneralAgentResponseTransfer or DiscountManagementAgentResponseTransfer structure, with agent, message, and reasoningMessage fields.

2) Implement the toolset plugin

Each agent resolves its tools through a named toolset. Create a plugin that implements ToolSetPluginInterface from Spryker\Zed\AiFoundation\Dependency\Tools:

<?php

namespace Pyz\Zed\AiCommerce\Communication\Plugin\AiFoundation;

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;

/**
 * @method \Pyz\Zed\AiCommerce\Communication\AiCommerceCommunicationFactory getFactory()
 */
class CustomerManagementToolSetPlugin extends AbstractPlugin implements ToolSetPluginInterface
{
    protected const string TOOL_SET_CUSTOMER_MANAGEMENT = 'customer_management_tools';

    public function getName(): string
    {
        return static::TOOL_SET_CUSTOMER_MANAGEMENT;
    }

    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface>
     */
    public function getTools(): array
    {
        return [
            $this->getFactory()->createGetCustomerDetailsToolPlugin(),
        ];
    }
}

Each tool referenced in getTools() implements ToolPluginInterface from Spryker\Zed\AiFoundation\Dependency\Tools, exposing getName(), getDescription(), getParameters(), and execute(). The AI model uses getName() and getDescription() to decide when to call the tool, and getParameters() to know which arguments to pass.

3) Register the plugins

Add the agent plugin to the array returned by AiCommerceDependencyProvider::getBackofficeAssistantAgentPlugins(), alongside the already-registered built-in agents described in Install Back Office Assistant:

src/Pyz/Zed/AiCommerce/AiCommerceDependencyProvider.php

use Pyz\Zed\AiCommerce\Communication\Plugin\Agent\CustomerManagementAgentPlugin;

class AiCommerceDependencyProvider extends SprykerFeatureAiCommerceDependencyProvider
{
    /**
     * @return array<\SprykerFeature\Zed\AiCommerce\Dependency\BackofficeAssistant\BackofficeAssistantAgentPluginInterface>
     */
    protected function getBackofficeAssistantAgentPlugins(): array
    {
        return [
            // ... existing agent plugins
            new CustomerManagementAgentPlugin(),
        ];
    }
}

Add the toolset plugin to the array returned by AiFoundationDependencyProvider::getAiToolSetPlugins():

src/Pyz/Zed/AiFoundation/AiFoundationDependencyProvider.php

use Pyz\Zed\AiCommerce\Communication\Plugin\AiFoundation\CustomerManagementToolSetPlugin;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface>
     */
    protected function getAiToolSetPlugins(): array
    {
        return [
            // ... existing toolset plugins
            new CustomerManagementToolSetPlugin(),
        ];
    }
}

4) Add a dedicated AI configuration

Built-in Back Office Assistant agents share one Back Office setting, AI Commerce > Back Office Assistant > AI Vendor, that lets a project pick OpenAI, AWS Bedrock, or Anthropic for all agents at once. Each agent then resolves to a dedicated, per-provider named AI configuration for that choice. Follow the same pattern for a new agent so it participates in the same vendor switch and gets its own entries in the AiFoundation audit log.

4.1) Define configuration key constants

Add project-level constants for the new agent’s per-provider configuration names and its model settings in Pyz\Shared\AiCommerce\AiCommerceConstants:

src/Pyz/Shared/AiCommerce/AiCommerceConstants.php

<?php

namespace Pyz\Shared\AiCommerce;

use SprykerFeature\Shared\AiCommerce\AiCommerceConstants as SprykerFeatureAiCommerceConstants;

interface AiCommerceConstants extends SprykerFeatureAiCommerceConstants
{
    public const string AI_CONFIGURATION_CUSTOMER_MANAGEMENT_OPENAI = 'AI_COMMERCE:AI_CONFIGURATION_CUSTOMER_MANAGEMENT_OPENAI';

    public const string AI_CONFIGURATION_CUSTOMER_MANAGEMENT_AWS = 'AI_COMMERCE:AI_CONFIGURATION_CUSTOMER_MANAGEMENT_AWS';

    public const string AI_CONFIGURATION_CUSTOMER_MANAGEMENT_ANTHROPIC = 'AI_COMMERCE:AI_CONFIGURATION_CUSTOMER_MANAGEMENT_ANTHROPIC';
}

4.2) Resolve the configuration name from `AiCommerceConfig`

Override AiCommerceConfig in Zed to resolve the new agent’s configuration name from the existing vendor setting, reusing getBackofficeAssistantAiConfigurationName(). This is the method referenced as getCustomerManagementAgentAiConfigurationName() in the agent plugin from step 1:

src/Pyz/Zed/AiCommerce/AiCommerceConfig.php

<?php

namespace Pyz\Zed\AiCommerce;

use Pyz\Shared\AiCommerce\AiCommerceConstants;
use SprykerFeature\Zed\AiCommerce\AiCommerceConfig as SprykerFeatureAiCommerceConfig;

class AiCommerceConfig extends SprykerFeatureAiCommerceConfig
{
    public function getCustomerManagementAgentAiConfigurationName(): ?string
    {
        return match ($this->getBackofficeAssistantAiConfigurationName()) {
            AiCommerceConstants::AI_CONFIGURATION_BACKOFFICE_ASSISTANT_AWS => AiCommerceConstants::AI_CONFIGURATION_CUSTOMER_MANAGEMENT_AWS,
            AiCommerceConstants::AI_CONFIGURATION_BACKOFFICE_ASSISTANT_ANTHROPIC => AiCommerceConstants::AI_CONFIGURATION_CUSTOMER_MANAGEMENT_ANTHROPIC,
            default => AiCommerceConstants::AI_CONFIGURATION_CUSTOMER_MANAGEMENT_OPENAI,
        };
    }

    public function isCustomerManagementAgentEnabled(): bool
    {
        return (bool)filter_var(
            $this->getModuleConfig('ai_commerce:customer_management:general:is_enabled', true),
            FILTER_VALIDATE_BOOLEAN,
        );
    }
}

getBackofficeAssistantAiConfigurationName() and the AI_CONFIGURATION_BACKOFFICE_ASSISTANT_* constants are defined in your project’s Pyz\Zed\AiCommerce\AiCommerceConfig and Pyz\Shared\AiCommerce\AiCommerceConstants when you install the Back Office Assistant, as described in Install Back Office Assistant. Reuse them instead of adding a separate vendor switch for the new agent.

4.3) Add the configuration entries

Add one entry per provider to config/Shared/config_ai.php, following the same pattern used for the built-in agents in Install Back Office Assistant. Reuse the existing CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_*_MODEL and API token constants so the model and provider credentials stay configurable through Configuration Management, consistent with the other agents:

config/Shared/config_ai.php

<?php

use Pyz\Shared\AiCommerce\AiCommerceConstants;
use Spryker\Shared\AiFoundation\AiFoundationConstants;

$config[AiFoundationConstants::AI_CONFIGURATIONS][AiCommerceConstants::AI_CONFIGURATION_CUSTOMER_MANAGEMENT_OPENAI] = [
    'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
    'provider_config' => [
        'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_OPENAI_API_TOKEN,
        'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_OPENAI_MODEL,
    ],
];

$config[AiFoundationConstants::AI_CONFIGURATIONS][AiCommerceConstants::AI_CONFIGURATION_CUSTOMER_MANAGEMENT_AWS] = [
    'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
    'provider_config' => [
        'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL,
        'bedrockRuntimeClient' => [
            'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
            'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
        ],
    ],
];

$config[AiFoundationConstants::AI_CONFIGURATIONS][AiCommerceConstants::AI_CONFIGURATION_CUSTOMER_MANAGEMENT_ANTHROPIC] = [
    'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
    'provider_config' => [
        'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
        'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL,
    ],
];

Info

If the new agent needs its own model choice independent of the other agents, define dedicated CONFIGURATION_KEY_CUSTOMER_MANAGEMENT_*_MODEL constants and Configuration Management settings instead of reusing CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_*_MODEL.

5) Enable SSE streaming for the new agent

Back Office Assistant streams tool call progress to the chat widget over Server-Sent Events. BackofficeAssistantSsePreToolCallPlugin and BackofficeAssistantSsePostToolCallPlugin only emit an event when the current prompt’s AI configuration name is present in AiCommerceConfig::getBackofficeAssistantSseAiConfigurationNames(). If the new agent’s configuration name is missing from that list, its tool calls run normally but their progress does not stream to the widget.

Override getBackofficeAssistantSseAiConfigurationNames() in the project’s AiCommerceConfig to include the new agent’s configuration name:

src/Pyz/Zed/AiCommerce/AiCommerceConfig.php

<?php

namespace Pyz\Zed\AiCommerce;

use Pyz\Shared\AiCommerce\AiCommerceConstants;
use SprykerFeature\Zed\AiCommerce\AiCommerceConfig as SprykerFeatureAiCommerceConfig;

class AiCommerceConfig extends SprykerFeatureAiCommerceConfig
{
    // ... getCustomerManagementAgentAiConfigurationName() and isCustomerManagementAgentEnabled() from step 4.2

    /**
     * @return array<string>
     */
    public function getBackofficeAssistantSseAiConfigurationNames(): array
    {
        return array_values(array_filter([
            ...parent::getBackofficeAssistantSseAiConfigurationNames(),
            $this->getCustomerManagementAgentAiConfigurationName(),
        ]));
    }
}

BackofficeAssistantSsePreToolCallPlugin and BackofficeAssistantSsePostToolCallPlugin are registered once in AiFoundationDependencyProvider::getPreToolCallPlugins() and getPostToolCallPlugins(), as shown in Install Back Office Assistant. They apply to every agent whose configuration name is in the list above, so no additional plugin registration is required for the new agent.

Verification

In the Back Office, open the Back Office Assistant chat widget and send a message that matches the new agent’s description. Confirm the intent router routes the request to the new agent, that tool call progress streams live in the widget, and that the response uses the expected tools.

Getting started with cloud administration

Thu, 16 Jul 2026 15:05:07 +0000

This document is a starting point for managing your Spryker Cloud Commerce OS (SCCOS) cloud environments. SCCOS is a fully managed solution. Before you start developing, we set up environments, tools, and services based on your Onboarding Questionnaire. If you didn't request something in the questionnaire, you can always do it via [support](https://support.spryker.com). After the initial setup, the following is configured and available: - [Environments](/docs/ca/dev/environments-overview.html): staging and production. - Services: RDS database, RDS backup, logs, SMTP, etc. - Access to AWS, internal resources, and services. - CD pipelines for staging and production environments. - Domain names and SSL certificates. ## Accessing the cloud environments You can access your cloud environments via the following means: - IAM account: provides access to the AWS Management Console and AWS CLI. For instructions, see [Connecting to AWS Console and CLI with an IAM user](/docs/ca/dev/access/connecting-to-aws-console-and-cli-with-an-iam-user.html). - SSH: provides access to internal services via [bastion host](https://docs.aws.amazon.com/managedservices/latest/userguide/using-bastions.html). For instructions, see [Connect to services via SSH](/docs/ca/dev/access/connect-to-services-via-ssh.html). - VPN: provides access to internal services via [bastion host](https://docs.aws.amazon.com/managedservices/latest/userguide/using-bastions.html). You receive these access details during the onboarding. - SFTP: provides access to the SFTP folder mounted inside the Jenkins container. You receive these access details during the onboarding. ## Service credentials You can find the credentials for services in the environment variables for the Zed container in [Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html). For instructions, see [Locate service credentials](/docs/ca/dev/access/locate-service-credentials.html). ## CD pipelines The following CD pipelines are configured in [CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html):

| Pipeline | Details | | --- | --- | | DESTRUCTIVE | You can configure the installation stage of this pipeline in `config/install/destructive.yml`. | | NORMAL | You can configure the installation stage of this pipeline in `config/install/production.yml`. | | Build | Compiles images and pushes them into the [Amazon Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html). Starts automatically when a new commit's detected. | | Rollout Scheduler | Deploys the scheduler. |

To learn about running pipelines, see [Deploy in a staging environment](/docs/ca/dev/deploy-in-a-staging-environment.html) and [Deploy in a production environment](/docs/ca/dev/deploy-in-a-production-environment.html). ## Next step [Environments overview](/docs/ca/dev/environments-overview.html)

Connecting to AWS Console and CLI with an IAM user

Thu, 16 Jul 2026 15:05:07 +0000

This document describes how to access the AWS Management Console and configure AWS CLI access as an IAM user with Multi-Factor Authentication (MFA) enforced.

Prerequisites

AWS CLI installed on your machine.
An IAM user account and credentials provided by your administrator. If you need an account, contact support.

In your browser, open the sign-in URL provided by your administrator.

Sign-in URL

The sign-in URL contains the ID of the account you are signing into. The pattern is https://{AWS_ACCOUNT_ID}.signin.aws.amazon.com/console/. Alternatively, you can sign in at the general sign-in endpoint by entering the account ID manually.

The sign-in page opens with the Account ID (12 digits) or account alias field entered automatically.

Enter your IAM user name and Password.
Select Sign in.
When prompted, enter the MFA code from your authenticator application.

You are now signed in to the AWS Management Console.

Step 2: Generate access keys

Access keys are the long-term static credentials used to configure AWS CLI. Generate them once and store them securely.

Access key scope

You can only generate an access key for your own account.
Access keys are intended for local development and personal AWS CLI access only. Do not use them for automations.

In the AWS Management Console navigation bar, click your username > My Security Credentials.
On the Security credentials page, click Create access key.
On the Access key best practices & alternatives page, select Command Line Interface (CLI), then click Next. The Create access key window opens. Your access key has been generated.
Click Download .csv file to save the credentials.
Optional: To view the secret key in this window, click Show secret access key.

Store the downloaded credentials securely. The secret access key is shown only once.

Step 3: Configure static credentials in your terminal

Because MFA is enforced, you need temporary session credentials to use the AWS CLI. Static credentials alone are only used to request those temporary credentials.

Start by clearing any previously exported credentials to ensure no stale values are used:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Then export your static access key pair:

export AWS_ACCESS_KEY_ID="{YOUR_ACCESS_KEY_ID}"
export AWS_SECRET_ACCESS_KEY="{YOUR_SECRET_ACCESS_KEY}"

Replace {YOUR_ACCESS_KEY_ID} and {YOUR_SECRET_ACCESS_KEY} with the values from the .csv file you downloaded in Step 2.

Step 4: Find your MFA device ARN

To retrieve your MFA device serial number, use the AWS CLI:

aws iam list-mfa-devices

The output contains a SerialNumber field with a value in the following format:

arn:aws:iam::{ACCOUNT_ID}:mfa/{DEVICE_NAME}

Note this value — you need it in the next step.

Step 5: Generate temporary session credentials

Use one of the following options, replacing the placeholders with your values:

Option A: Step by step

Request temporary credentials from AWS STS and save the output to a variable:

temp_creds=$(aws sts get-session-token \
  --serial-number {MFA_DEVICE_ARN} \
  --token-code {MFA_TOKEN_CODE} \
  --query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \
  --output text)

Read the three values from the output into separate variables:

read -r AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN <<< "$temp_creds"

Export them to your terminal session:

export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Clean up the temporary variable:

unset temp_creds

Option B: Single command

Run all of the above as a single command:

temp_creds=$(aws sts get-session-token \
  --serial-number {MFA_DEVICE_ARN} \
  --token-code {MFA_TOKEN_CODE} \
  --query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \
  --output text) \
&& read -r AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN <<< "$temp_creds" \
&& export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN \
&& unset temp_creds

Placeholder	Description
`{MFA_DEVICE_ARN}`	The `SerialNumber` from Step 4.
`{MFA_TOKEN_CODE}`	The current 6-digit code from your authenticator application.

Example:

temp_creds=$(aws sts get-session-token \
  --serial-number arn:aws:iam::123456789012:mfa/john.doe \
  --token-code 521288 \
  --query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \
  --output text) \
&& read -r AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN <<< "$temp_creds" \
&& export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN \
&& unset temp_creds

The command fetches temporary credentials from AWS STS, reads the three values into variables, and exports them — overriding the static credentials in your current terminal session.

Session duration

Temporary credentials are valid for limited timeframe. When they expire, repeat Step 3 and Step 5 to obtain new ones. You can customize the duration using the --duration-seconds parameter (minimum: 900 seconds).

You can now use the AWS CLI to access your environment:

aws ec2 describe-instances

Next steps

Security

Thu, 16 Jul 2026 13:50:17 +0000

This section explains how to check ECR image scan results and introduces the web application firewall: - [Checking ECR image scan results](/docs/ca/dev/security/check-ecr-image-scan-results.html) - [Web Application Firewall (WAF)](/docs/ca/dev/security/web-application-firewall-waf.html) You can also find some details on the [Regular patching activities](/docs/ca/dev/security/patching-maintenancewindows.html)

Environments overview

Thu, 16 Jul 2026 13:50:17 +0000

This document describes the environment types shipped with Spryker and the best ways to use them. Knowing the purpose of the environments and working with them as intended can help you build more solid and performant projects.

Contracts may vary, and this document only describes the environments types that may represent your default setup. If you are using a different setup, ask your project manager or product owner for a more detailed explanation.
Your non-production environments don’t scale automatically. If you want to increase their scaling, let us know by submitting this form: Upscale Request. Because of contractual reasons, only customers can request these changes, not partners.

Basic concept

We offer environments that serve different purposes. These environments are non-production, production-like, and production environments. We can configure these environments to be as similar as possible to make sure that the code you deploy in one environment behaves the same way as in the others. You can help us keep your environments consistent by taking this into consideration when sending us change requests.

Non-production environments (NON-PROD)

Used for development and testing purposes, smaller in size and doesn’t scale. We offer several types of NON-PROD environments as described in the following sections. Non-production environments don’t feature zero-downtime deployments because services, such as Yves or Glue, aren’t set up in a redundant manner.

Developer environment (DEV)

A Dev environment is a non-production environment that is usually used to test code that just left your development team, or is used in the development process directly through continuous deployment. It is not designed to handle load tests and large datasets. The development environment does not provide autoscaling and and can only be scaled up upon request.

Staging (STAGE)

This environment is a non-production environment that is usually used to host a snapshot of the DEV environment, or a stable version of your code that is deployed to production eventually. You can use your STAGE environment to test how your code behaves in a production environment. However, staging is not of the same size as production, and a subset of data and expected traffic must be considered while running tests. This environment is regularly used for demos. The staging environment provides limited autoscaling capabilities and can only be scaled up on request.

Production-like (PROD-LIKE)

This environment is set up exactly like a PROD environment. It’s designed to carry out temporary load testing and related activities in an environment similar to PROD. This makes deployments to PROD more predictable and prevents issues. PROD-LIKE behaves exactly like PROD, but it’s only available for a short time period to perform the necessary tests.

Production (PROD)

Your production environment hosts the code that the end-user gets to interact with directly. The code must already be tested on the STAGE environment for stability and performance. In a PROD Environment, the application is automatically scaled to handle the load on the infrastructure generated by incoming requests. Production environments also offer zero-downtime deployments of Spryker services, because Spryker services, such as Glue, Yves, and Back Office, are set up in a redundant manner, making sure there is always enough instances available to serve requests while others are updated.

Making changes on PROD

Before you deploy to PROD, make sure the changes were deployed and tested in your DEV and STAGE environments. We highly recommend testing every data load and import, as well as any integrations on your STAGE.

Next step

Connecting to AWS Console and CLI with an IAM user

Connecting to AWS CLI with an SSO user

Thu, 16 Jul 2026 13:50:17 +0000

This feature is part of a gradual rollout and will be available to everyone eventually. We will notify your team once your project is onboarded.

This document describes how to configure and use SAML2AWS to authenticate with the AWS CLI using your SSO credentials.

SAML2AWS is a command-line tool that lets you authenticate against an identity provider (IdP) using SAML and obtain temporary AWS credentials. This gives you AWS CLI access to your cloud environment without managing long-lived AWS access keys.

Prerequisites

SAML2AWS installed on your machine.
AWS CLI installed on your machine.
An SSO user. See User Management SSO.
Your SSO login page URL. To get it, see SSO Access.

Step 1: Configure SAML2AWS

To configure SAML2AWS, replace the placeholders with your actual values and execute the following:

saml2aws configure \
  --idp-provider=Browser \
  --browser-type={BROWSER_TYPE} \
  --url={YOUR_SSO_LOGIN_PAGE_URL} \
  --profile={YOUR_PROFILE} \
  --skip-prompt

Parameter	Description
`--idp-provider=Browser`	Uses a browser-based login flow via your identity provider.
`--browser-type`	The browser to use for authentication. See Supported browser types.
`--url`	SSO login page URL.
`--profile`	The AWS CLI profile name to store credentials under.
`--skip-prompt`	Skips interactive prompts and applies values directly.

Example:

saml2aws configure \
  --idp-provider=Browser \
  --browser-type=chrome \
  --url=https://auth.spryker.systems/realms/my-realm/protocol/saml/clients/my-aws-client \
  --profile=my-aws-profile \
  --skip-prompt

Step 2: Log in with SAML2AWS

After configuring, run the login command to authenticate and retrieve temporary AWS credentials:

saml2aws login \
  --profile={YOUR_PROFILE} \
  --skip-prompt

Add --force to skip the expiry check and re-authenticate even if existing credentials are still valid:

saml2aws login \
  --profile={YOUR_PROFILE} \
  --skip-prompt \
  --force

Browser driver

On some operating systems and browsers, SAML2AWS needs to download a browser driver automatically. If login fails or the browser does not open, add the --download-browser-driver flag:

saml2aws login \
  --profile={YOUR_PROFILE} \
  --download-browser-driver \
  --skip-prompt

You do not need this flag if you are on Linux and using Chrome.

On successful authentication, your terminal displays a confirmation and the credentials are saved under the specified profile.

Step 3: Use the AWS CLI

Pass --profile {YOUR_PROFILE} to any AWS CLI command to use the credentials obtained from SAML2AWS:

aws --profile={YOUR_PROFILE} s3 ls
aws --profile={YOUR_PROFILE} ec2 describe-instances

To avoid specifying --profile with every command, set the AWS_PROFILE environment variable for your session:

export AWS_PROFILE={YOUR_PROFILE}
aws s3 ls
aws ec2 describe-instances

The temporary credentials expire after a set period. When they expire, re-run the login command from Step 2 to refresh them.

Supported browser types

The --browser-type parameter accepts the following values (see the full list in the saml2aws source):

Value	Browser
`chrome`	Google Chrome (stable)
`chrome-beta`	Google Chrome Beta
`chrome-dev`	Google Chrome Dev
`chrome-canary`	Google Chrome Canary
`chromium`	Chromium
`firefox`	Mozilla Firefox
`webkit`	WebKit (Safari engine, macOS)
`msedge`	Microsoft Edge (stable)
`msedge-beta`	Microsoft Edge Beta
`msedge-dev`	Microsoft Edge Dev
`msedge-canary`	Microsoft Edge Canary

OS and browser combinations

The following combinations have been verified to work:

Operating system	Browser
Ubuntu	Chrome, Chromium, Firefox
macOS	WebKit, Chromium
Windows 10	Chrome, Firefox, Microsoft Edge

Chrome on macOS

Chrome on macOS may not work for all users. If you experience issues, use webkit or chromium instead.

Troubleshooting

Issue	Solution
The browser does not open during login.	Add `--download-browser-driver` to the login command to let SAML2AWS download the required browser driver automatically.
Authentication fails or credentials are not saved.	Verify that `--browser-type` matches a browser installed on your machine and that the `--url` value is correct.
The AWS CLI does not recognize the profile.	Ensure the `--profile` value in the login command matches the one used during configuration.
`Error authenticating to IDP.: please install the driver (vx.x.x) and browsers first: %!w(<nil>)`	Add `--download-browser-driver` to the login command to let SAML2AWS download the required browser driver automatically.

Next steps

Access

Thu, 16 Jul 2026 13:50:17 +0000

This section describes how to access AWS Management Console as an Identity and Access Management (IAM) user, locate the credentials for Spryker Cloud Commerce OS services, and connect to services:

Spryker Documentation

AI Dev SDK Skills and Agents

Overview

How to invoke

Skills

Agents

Related

Claude Code Plugin

Overview

Prerequisites

Install the plugin from the marketplace

Set up AI tooling for your project

Capabilities

Skills

Subagents

Rules

Context file

Release notes 202606.0

Add a custom Back Office Assistant agent

1) Implement the agent plugin

2) Implement the toolset plugin

3) Register the plugins

4) Add a dedicated AI configuration

4.1) Define configuration key constants

4.2) Resolve the configuration name from AiCommerceConfig

4.3) Add the configuration entries

5) Enable SSE streaming for the new agent

Getting started with cloud administration

Connecting to AWS Console and CLI with an IAM user

Prerequisites

Step 1: Sign in to the AWS Management Console

Step 2: Generate access keys

Step 3: Configure static credentials in your terminal

Step 4: Find your MFA device ARN

Step 5: Generate temporary session credentials

Next steps

Security

Environments overview

Basic concept

Non-production environments (NON-PROD)

Developer environment (DEV)

Staging (STAGE)

Production-like (PROD-LIKE)

Production (PROD)

Next step

Connecting to AWS CLI with an SSO user

Prerequisites

Step 1: Configure SAML2AWS

Step 2: Log in with SAML2AWS

Step 3: Use the AWS CLI

Supported browser types

OS and browser combinations

Troubleshooting

Next steps

Access

4.2) Resolve the configuration name from `AiCommerceConfig`