Spryker Documentation

Extend AI Commerce agents with custom toolsets

Thu, 13 Aug 2026 08:55:34 +0000

AI Commerce agents can only act on data that a tool exposes to them. A tool is a PHP class the AI model calls with arguments and gets a result back. Tools are grouped into named toolsets, and each agent or feature declares which toolsets it uses.

To let an agent work with data that no built-in tool covers — for example, your own entity — implement a tool, group it in a toolset, register the toolset, and add the toolset name to the feature that must use it.

This document describes how to extend an existing agent or feature. To add a completely new agent, see Add a custom Back Office Assistant agent.

How toolsets are resolved

Every prompt request carries a list of toolset names. At runtime, AiFoundation matches those names against the toolset plugins registered in AiFoundationDependencyProvider::getAiToolSetPlugins() and passes the merged tools of all matching toolsets to the AI provider.

Two things follow from this:

A toolset is only available to a feature if the feature’s toolset name list contains its name. Registering the plugin alone does nothing.
A toolset name that does not match a registered plugin is ignored without an error. If your tool is never called, first check that the name in the configuration matches getName() exactly.

Features expose their toolset names differently:

FEATURE	WHERE TOOLSET NAMES COME FROM
Smart CMS Content Assistant	`AiCommerceConfig::getSmartCmsToolSetNames()`. Override it in `Pyz` to add names.
Back Office Assistant agents	Each agent plugin calls `PromptRequestTransfer::addToolSetName()` in `executeAgent()`. To change the list of an existing agent, override that agent plugin in `Pyz`.

Security

A tool is executable code that the AI model decides when to call, based on a model-generated argument list. Treat every tool as an untrusted, publicly reachable entry point:

Prefer read-only tools. Only expose write, update, or delete operations when the use case genuinely requires them. A prompt injected through user-generated content — a product description, a customer note, an uploaded file — can make the model call any tool that is available to it.
Validate and constrain every argument. The model can pass any value that fits the declared type. Validate arguments in execute() exactly as you would validate a request from the internet.
Enforce permissions inside the tool. Tool execution does not inherit the Back Office user’s ACL rules. Check permissions explicitly in execute() for anything sensitive.
Never return personal or secret data. Everything a tool returns is sent to the AI provider and stored in the conversation history. Return only the fields the agent needs, and exclude credentials, tokens, and personal data.
Limit result size. Apply a pagination limit, as getSmartCmsContentItemLookupLimit() does for Smart CMS, so a single call cannot send your entire catalog to the provider.
Catch exceptions. Return a neutral error string instead of letting an exception surface, so internal details such as stack traces or table names are not exposed to the model.

1) Implement the tool plugin

Create a plugin that implements ToolPluginInterface from Spryker\Zed\AiFoundation\Dependency\Tools:

METHOD	PURPOSE
`getName()`	Returns the unique tool name the model uses to call the tool.
`getDescription()`	Describes what the tool does and when to use it. The model relies on this text to decide whether to call the tool, so be specific.
`getParameters()`	Returns the accepted parameters as `ToolParameter` objects, each with a name, a type (`string`, `integer`, `number`, `boolean`, `array`, or `object`), a description, and a required flag.
`execute()`	Runs the tool and returns the result. Return a JSON-encoded string so the model can parse the result reliably.

The following read-only tool returns a single product by SKU:

src/Pyz/Zed/AiCommerce/Communication/Plugin/AiFoundation/Tool/GetProductToolPlugin.php

<?php

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

use Spryker\Shared\Log\LoggerTrait;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Throwable;

/**
 * @method \Pyz\Zed\AiCommerce\Business\AiCommerceFacadeInterface getFacade()
 */
class GetProductToolPlugin extends AbstractPlugin implements ToolPluginInterface
{
    use LoggerTrait;

    protected const string TOOL_NAME = 'get_product';

    protected const string PARAMETER_SKU = 'sku';

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

    public function getDescription(): string
    {
        return 'Returns the name, status, and price of a single product identified by its SKU. Use when the user asks about a specific product.';
    }

    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameterInterface>
     */
    public function getParameters(): array
    {
        return [
            new ToolParameter(static::PARAMETER_SKU, 'string', 'The SKU of the product to look up, for example "001_25904006".', true),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $sku = $arguments[static::PARAMETER_SKU] ?? null;

        if (!is_string($sku) || $sku === '') {
            return (string)json_encode(['error' => 'A non-empty sku is required.']);
        }

        try {
            $productConcreteTransfer = $this->getFacade()->findProductBySku($sku);

            if ($productConcreteTransfer === null) {
                return (string)json_encode(['error' => 'Product not found.']);
            }

            return (string)json_encode([
                'sku' => $productConcreteTransfer->getSku(),
                'name' => $productConcreteTransfer->getName(),
                'isActive' => $productConcreteTransfer->getIsActive(),
            ]);
        } catch (Throwable $throwable) {
            $this->getLogger()->error('GetProductToolPlugin::execute() failed.', ['exception' => $throwable]);

            return (string)json_encode(['error' => 'An error occurred while retrieving the product.']);
        }
    }
}

The tool validates the SKU before use, returns only three fields, and converts any exception into a neutral message. Apply the same three rules to every tool you add.

Warning

If you expose write operations — creating, updating, or deleting data — the model can trigger them without a human confirming the action. Restrict such tools to non-critical entities, validate every argument against an allowlist of permitted values, and check the acting user’s permissions inside execute().

2) Implement the toolset plugin

Group the tools in a toolset by implementing ToolSetPluginInterface from Spryker\Zed\AiFoundation\Dependency\Tools. Group tools that belong to the same domain, so an agent can enable them together:

src/Pyz/Zed/AiCommerce/Communication/Plugin/AiFoundation/ProductInfoToolSetPlugin.php

<?php

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

use Pyz\Zed\AiCommerce\Communication\Plugin\AiFoundation\Tool\GetProductToolPlugin;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;

class ProductInfoToolSetPlugin extends AbstractPlugin implements ToolSetPluginInterface
{
    protected const string TOOL_SET_PRODUCT_INFO = 'product_info_tools';

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

    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface>
     */
    public function getTools(): array
    {
        return [
            new GetProductToolPlugin(),
        ];
    }
}

3) Register the toolset plugin

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

src/Pyz/Zed/AiFoundation/AiFoundationDependencyProvider.php

<?php

namespace Pyz\Zed\AiFoundation;

use Pyz\Zed\AiCommerce\Communication\Plugin\AiFoundation\ProductInfoToolSetPlugin;
use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;

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

4) Enable the toolset for a feature

Registering the plugin makes the toolset resolvable, but a feature only receives its tools once the toolset name is in the feature’s list.

Smart CMS Content Assistant

Override getSmartCmsToolSetNames() in your project configuration and keep the built-in names, so the content item lookup tool stays available:

src/Pyz/Zed/AiCommerce/AiCommerceConfig.php

<?php

namespace Pyz\Zed\AiCommerce;

use SprykerFeature\Zed\AiCommerce\AiCommerceConfig as SprykerFeatureAiCommerceConfig;

class AiCommerceConfig extends SprykerFeatureAiCommerceConfig
{
    /**
     * @uses \Pyz\Zed\AiCommerce\Communication\Plugin\AiFoundation\ProductInfoToolSetPlugin::TOOL_SET_PRODUCT_INFO
     *
     * @return array<string>
     */
    public function getSmartCmsToolSetNames(): array
    {
        return array_merge(parent::getSmartCmsToolSetNames(), [
            'product_info_tools',
        ]);
    }
}

Back Office Assistant agents

Built-in agents add their toolset names in executeAgent(). To give an existing agent an additional toolset, extend that agent plugin in Pyz, add the extra name, and register your plugin instead of the built-in one in AiCommerceDependencyProvider::getBackofficeAssistantAgentPlugins(). For instructions on registering agent plugins, see Add a custom Back Office Assistant agent.

5) Adjust the system prompt

Tools alone do not guarantee the model uses them as intended. The system prompt sets the rules the model follows when it decides which tool to call, so review it whenever you add tools.

AiCommerceConfig exposes the prompt templates for the Smart PIM features — translation, category suggestion, content improvement, and image alt text — through methods such as getContentImproverPromptTemplate(). Each reads a Configuration Management value and falls back to the built-in template when the value is empty. Override the corresponding method or set the configuration value to state which tool to use, when to use it, and what the model must never do with the returned data.

Keep the placeholders of the original template. Removing a %s placeholder breaks the sprintf() call that builds the final prompt.

Because prompts are resolved per AI configuration, a prompt change affects every feature bound to that configuration. For how features map to configurations and providers, see Configure multiple AI providers for AI Commerce.

Warning

A system prompt is a guideline, not a security control. The model can be steered away from prompt instructions by injected content, so never rely on the prompt alone to prevent a tool from being misused. Enforce every restriction that matters in the tool’s execute() method.

6) Verify the toolset

Trigger the feature you enabled the toolset for, with a request that requires the new tool.
Check the AI interaction audit log to confirm the tool was called with the expected arguments. For details, see AI Interaction Audit Logs.

If the tool is never called, verify the following:

The toolset name in the feature configuration matches the toolset plugin’s getName() exactly.
The toolset plugin is registered in AiFoundationDependencyProvider::getAiToolSetPlugins().
The tool description states clearly when the tool applies. A vague description is the most common reason a model ignores a tool.

Smart CMS Content Assistant

Thu, 13 Aug 2026 05:03:30 +0000

Smart CMS Content Assistant is an AI-powered panel embedded in the Back Office CMS Page and CMS Block glossary editors. It lets Back Office users generate and refine placeholder content per locale using a conversational AI interface, with full access to the entity context, SEO metadata, available CMS content widgets, and existing content items. For the business overview and Back Office usage, see [Smart CMS Content Assistant](/docs/pbc/all/ai-commerce/latest/smart-cms-content-assistant.html). ## Architecture Smart CMS Content Assistant is built on the `AiFoundation` abstraction layer and runs entirely in the Zed (Back Office) application. The AI panel is injected into both glossary editors through Twig overrides at the project level: - **CMS Page glossary** — `src/Pyz/Zed/CmsGui/Presentation/CreateGlossary/index.twig` - **CMS Block glossary** — `src/Pyz/Zed/CmsBlockGui/Presentation/EditGlossary/index.twig` Both overrides use the `isSmartCmsEnabled()` Twig function (provided by `AiCommerceTwigPlugin`) to conditionally render the AI panel partial `@AiCommerce/Partials/smart-cms-glossary-panel.twig`. The panel is only rendered when the feature is enabled in the Back Office configuration. The panel collects entity context (name, template, URL slug, key, SEO meta, stores) and current placeholder/locale state client-side. The JavaScript component (`SmartCmsContentPanel`) sends requests to `SmartCmsContentController`, which delegates to `SmartCmsContentGenerator` through the `AiCommerceFacade`. ## Capabilities | CAPABILITY | DESCRIPTION | |------------|-------------| | Placeholder content generation | Generates title and body content per placeholder and locale using the entity context and system prompt. | | Content widget reuse | Collects available CMS content widgets from the editor DOM and makes them available to the AI as context. | | Content item reference | Uses the `get_content_items` tool (provided by `GetContentItemsToolPlugin`) to retrieve existing content items from the database and reference them in generated content. | | File attachment | Allows attaching files (base64-encoded) to the prompt. Both client-side and server-side validation are applied via `AttachmentValidator`. | ## Plugin wiring | PLUGIN | LOCATION | DESCRIPTION | |--------|----------|-------------| | `SmartCmsContentToolSetPlugin` | `AiFoundationDependencyProvider::getAiToolSetPlugins()` | Registers the Smart CMS Content Assistant toolset, including the `get_content_items` tool. | To make additional tools available to the Smart CMS Content Assistant, add your own toolset to `AiCommerceConfig::getSmartCmsToolSetNames()`. For instructions, see [Extend AI Commerce agents with custom toolsets](/docs/dg/dev/ai/ai-commerce/extend-ai-commerce-agents-with-toolsets.html). Content widget plugins are registered in `AiCommerceDependencyProvider::getContentGuiEditorPlugins()` and are used to resolve available CMS widgets that the AI can reference in generated content: | PLUGIN | NAMESPACE | |--------|-----------| | `ContentBannerContentGuiEditorPlugin` | `Spryker\Zed\ContentBannerGui\Communication\Plugin\ContentGui` | | `ContentProductContentGuiEditorPlugin` | `Spryker\Zed\ContentProductGui\Communication\Plugin\ContentGui` | | `ContentProductSetGuiEditorPlugin` | `Spryker\Zed\ContentProductSetGui\Communication\Plugin\ContentGui` | | `ContentFileListContentGuiEditorPlugin` | `Spryker\Zed\ContentFileGui\Communication\Plugin\ContentGui` | | `ContentNavigationContentGuiEditorPlugin` | `Spryker\Zed\ContentNavigationGui\Communication\Plugin\ContentGui` | ## AI configuration Smart CMS Content Assistant uses a dedicated named AI configuration entry in `AiFoundation`. The active configuration is resolved at runtime based on the AI vendor selected in the Back Office configuration UI. | CONSTANT | DESCRIPTION | |----------|-------------| | `AiCommerceConstants::AI_CONFIGURATION_SMART_CMS_OPENAI` | Configuration for the OpenAI-backed Smart CMS Content Assistant agent. | | `AiCommerceConstants::AI_CONFIGURATION_SMART_CMS_AWS` | Configuration for the AWS Bedrock-backed Smart CMS Content Assistant agent. | | `AiCommerceConstants::AI_CONFIGURATION_SMART_CMS_ANTHROPIC` | Configuration for the Anthropic-backed Smart CMS Content Assistant agent. | The active configuration is selected by `AiCommerceConfig::getSmartCmsAiConfigurationName()`, which reads `AiCommerceConstants::CONFIGURATION_KEY_SMART_CMS_AI_CONFIGURATION` from the Back Office configuration UI. The default is `AI_CONFIGURATION_SMART_CMS_OPENAI`. ## Feature flag The feature can be enabled or disabled from the Back Office under **AI Commerce > Smart CMS > AI Vendor**. The `isSmartCmsEnabled()` Twig function reads this flag and controls panel visibility in both glossary editors. ## Install [Install Smart CMS Content Assistant](/docs/dg/dev/ai/ai-commerce/content-assistant/install-smart-cms-content-assistant.html)

Use AI tools with the AiFoundation module

Thu, 13 Aug 2026 05:03:30 +0000

This document describes how to create and use AI tools with the AiFoundation module to extend AI capabilities by providing custom functions that AI models can invoke during conversations.

Overview

AI tool support enables large language models to call custom functions during conversations. Instead of only generating text, AI models can invoke your application’s functionality, retrieve data, perform calculations, or trigger business logic. This creates more powerful and interactive AI-powered features.

The AI model decides when to call tools based on the conversation context. The Zed facade executes tools with appropriate arguments, receives the results, and incorporates them into the response. The AiFoundation module handles the complete tool execution flow automatically.

Prerequisites

AiFoundation module installed and configured. For details, see AiFoundation module Overview.
Configured AI provider that supports tool calling (OpenAI, Anthropic Claude)

Provider compatibility

Not all AI providers support tool calling. Ensure your configured provider supports this feature. OpenAI and Anthropic Claude have native support for function calling.

Use cases

AI tools are ideal for scenarios where AI needs to interact with your application:

Data retrieval

Enable AI to fetch data from your system:

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;

// AI can call this tool to get product information
class GetProductInfoTool implements ToolPluginInterface
{
    public const NAME = 'get_product_info';

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

    public function getDescription(): string
    {
        return 'Retrieves product information by SKU';
    }

    public function getParameters(): array
    {
        return [
            new ToolParameter(
                name: 'sku',
                type: 'string',
                description: 'The product SKU to retrieve information for',
                isRequired: true
            ),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $sku = $arguments['sku'] ?? null;
        $product = $this->getProductClient()
            ->getProductBySku($sku);

        return json_encode([
            'name' => $product->getName(),
            'price' => $product->getPrice(),
            'availability' => $product->getAvailability(),
        ]);
    }
}

Calculations and processing

Provide specialized calculations:

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;

// AI can call this tool to calculate shipping costs
class CalculateShippingTool implements ToolPluginInterface
{
    public const NAME = 'calculate_shipping';

    public function __construct(
        private ShippingCalculatorInterface $shippingCalculator
    ) {
    }

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

    public function getDescription(): string
    {
        return 'Calculates shipping cost based on weight, destination, and shipping method';
    }

    public function getParameters(): array
    {
        return [
            new ToolParameter(
                name: 'weight',
                type: 'number',
                description: 'Package weight in kilograms',
                isRequired: true
            ),
            new ToolParameter(
                name: 'destination',
                type: 'string',
                description: 'Destination country code (e.g., US, DE, FR)',
                isRequired: true
            ),
            new ToolParameter(
                name: 'method',
                type: 'string',
                description: 'Shipping method: standard, express, or overnight',
                isRequired: false
            ),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $weight = $arguments['weight'] ?? 0;
        $destination = $arguments['destination'] ?? '';
        $method = $arguments['method'] ?? 'standard';

        $cost = $this->shippingCalculator
            ->calculate($weight, $destination, $method);

        return (string) $cost;
    }
}

Business logic execution

Allow AI to trigger business operations:

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolPluginInterface;
use Spryker\Zed\AiFoundation\Dependency\Tools\ToolParameter;

// AI can call this tool to create support tickets
class CreateSupportTicketTool implements ToolPluginInterface
{
    public const NAME = 'create_support_ticket';

    public function __construct(
        private SupportFacadeInterface $supportFacade
    ) {
    }

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

    public function getDescription(): string
    {
        return 'Creates a support ticket with title, description, and priority';
    }

    public function getParameters(): array
    {
        return [
            new ToolParameter(
                name: 'title',
                type: 'string',
                description: 'Brief title summarizing the issue',
                isRequired: true
            ),
            new ToolParameter(
                name: 'description',
                type: 'string',
                description: 'Detailed description of the issue or request',
                isRequired: true
            ),
            new ToolParameter(
                name: 'priority',
                type: 'string',
                description: 'Priority level: high, medium, or low',
                isRequired: false
            ),
        ];
    }

    public function execute(...$arguments): mixed
    {
        $title = $arguments['title'] ?? '';
        $description = $arguments['description'] ?? '';
        $priority = $arguments['priority'] ?? 'medium';

        $ticketId = $this->supportFacade
            ->createTicket($title, $description, $priority);

        return sprintf('Ticket created with ID: %s', $ticketId);
    }
}

Create tool sets

Tool sets group related tools together. Create a tool set class that implements ToolSetPluginInterface. Tool sets are Zed-layer plugins registered in the Zed AiFoundationDependencyProvider.

<?php

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

use Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface;

class CustomerServiceToolSet implements ToolSetPluginInterface
{
    public const NAME = 'customer_service_tools';

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

    public function getTools(): array
    {
        return [
            new GetOrderStatusTool(),
            new CreateRefundTool(),
            new UpdateCustomerAddressTool(),
            new SendNotificationTool(),
        ];
    }
}

Organizing tools into sets

Group tools by functional domain:

// Product-related tools
class ProductToolSet implements ToolSetPluginInterface
{
    public const NAME = 'product_tools';

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

    public function getTools(): array
    {
        return [
            new SearchProductsTool(),
            new GetProductDetailsTool(),
            new CheckStockTool(),
        ];
    }
}

// Order-related tools
class OrderToolSet implements ToolSetPluginInterface
{
    public const NAME = 'order_tools';

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

    public function getTools(): array
    {
        return [
            new CreateOrderTool(),
            new GetOrderHistoryTool(),
            new CancelOrderTool(),
        ];
    }
}

Register tool sets

<?php

namespace Pyz\Zed\AiFoundation;

use Pyz\Zed\YourModule\Plugin\AiFoundation\CustomerServiceToolSet;
use Pyz\Zed\YourModule\Plugin\AiFoundation\ProductToolSet;
use Pyz\Zed\YourModule\Plugin\AiFoundation\OrderToolSet;
use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Tools\ToolSetPluginInterface>
     */
    protected function getAiToolSetPlugins(): array
    {
        return [
            new CustomerServiceToolSet(),
            new ProductToolSet(),
            new OrderToolSet(),
        ];
    }
}

Use tools in AI requests

Specify which tool sets to make available to the AI by adding tool set names to your prompt request:

<?php

namespace Pyz\Zed\YourModule\Business\Assistant;

use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Pyz\Zed\YourModule\Plugin\AiFoundation\CustomerServiceToolSet;
use Pyz\Zed\YourModule\Plugin\AiFoundation\OrderToolSet;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

class CustomerAssistant
{
    public function __construct(
        protected AiFoundationFacadeInterface $aiFoundationFacade
    ) {
    }

    public function handleCustomerInquiry(string $customerMessage): string
    {
        $promptRequest = (new PromptRequestTransfer())
            ->setAiConfigurationName('openai')
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent($customerMessage)
            )
            ->addToolSetName(CustomerServiceToolSet::NAME)
            ->addToolSetName(OrderToolSet::NAME)
            ->setMaxRetries(2);

        $promptResponse = $this->aiFoundationFacade->prompt($promptRequest);

        if ($promptResponse->getIsSuccessful() !== true) {
            return 'I apologize, but I encountered an error processing your request.';
        }

        return $promptResponse->getMessage()->getContent();
    }
}

The AI model has access to all tools from all specified tool sets.

Example: Support ticket creation via AI

Here is a complete example showing how the AI can automatically create support tickets using the CreateSupportTicketTool:

<?php

namespace Pyz\Zed\YourModule\Business;

use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Pyz\Zed\YourModule\Plugin\AiFoundation\CustomerServiceToolSet;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

class SupportTicketAssistant
{
    public function __construct(
        protected AiFoundationFacadeInterface $aiFoundationFacade
    ) {
    }

    public function processCustomerMessage(string $customerMessage): void
    {
        // Request AI to process the message with access to support tools
        $promptRequest = (new PromptRequestTransfer())
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent($customerMessage)
            )
            ->addToolSetName(CustomerServiceToolSet::NAME) // Includes CreateSupportTicketTool
            ->setMaxRetries(2);

        $promptResponse = $this->aiFoundationFacade->prompt($promptRequest);

        if ($promptResponse->getIsSuccessful() !== true) {
            throw new Exception('Failed to process customer message');
        }

        // Check if the AI invoked the create support ticket tool
        foreach ($promptResponse->getToolInvocations() as $toolInvocation) {
            if ($toolInvocation->getName() === 'create_support_ticket') {
                $ticketId = $toolInvocation->getResult();
                echo sprintf('Support ticket created: %s', $ticketId);
            }
        }

        // Send the AI response to the customer
        $response = $promptResponse->getMessage()->getContent();
        echo $response;
    }
}

In this example, when the customer sends a message like “I need to report a critical bug”, the AI can:

Understand the customer’s intent
Extract the ticket title, description, and priority
Invoke the create_support_ticket tool through the facade
Receive the ticket ID from the tool result
Incorporate the ticket information into its response to the customer

Handle tool call results

Tool calls are automatically executed and their results are included in the response:

$promptResponse = $this->aiFoundationFacade->prompt($promptRequest);

if ($promptResponse->getIsSuccessful() === true) {
    // Get the final AI response
    $finalMessage = $promptResponse->getMessage()->getContent();

    // Access tool invocation information
    foreach ($promptResponse->getToolInvocations() as $toolInvocation) {
        $toolName = $toolInvocation->getName();
        $toolArguments = $toolInvocation->getArguments();
        $toolResult = $toolInvocation->getResult();

        // content and reasoning are populated when the provider returns them alongside the tool call
        $content = $toolInvocation->getContent();   // e.g. "I will search for that now."
        $reasoning = $toolInvocation->getReasoning(); // chain-of-thought, when available

        // Log or process tool invocations
        $this->logger->info(sprintf(
            'AI invoked tool "%s" with arguments: %s. Result: %s',
            $toolName,
            json_encode($toolArguments),
            $toolResult
        ));
    }
}

Tool call flow

The complete flow when tools are used:

AI receives the prompt and available tools
AI decides to call one or more tools
AiFoundation automatically executes the tools with provided arguments
Tool results are sent back to the AI
AI incorporates results and may call additional tools
Process continues until AI provides final response
Final response and all tool invocations are returned in ToolInvocationTransfer objects

Best practices

Provide clear tool descriptions

Write descriptions that help the AI understand when and how to use tools:

// Good: Clear, specific description
public function getDescription(): string
{
    return 'Searches for products by name, category, or SKU. Returns product name, price, and availability status.';
}

// Avoid: Vague description
public function getDescription(): string
{
    return 'Product search';
}

Design focused tools

Create tools with single, well-defined purposes:

// Good: Focused tool
class GetOrderStatusTool implements ToolPluginInterface
{
    public const NAME = 'get_order_status';

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

// Avoid: Tool that does too much
class ManageOrdersTool implements ToolPluginInterface
{
    public function execute(...$arguments): mixed
    {
        $action = $arguments['action']; // create, update, cancel, status...
        // Too many responsibilities
    }
}

Return structured data

Return JSON-encoded data for complex results:

public function execute(...$arguments): mixed
{
    $order = $this->getOrderDetails($arguments['order_id']);

    return json_encode([
        'order_id' => $order->getOrderId(),
        'status' => $order->getStatus(),
        'total' => $order->getTotal(),
        'items' => $order->getItems(),
        'created_at' => $order->getCreatedAt(),
    ]);
}

Validate tool arguments

Always validate arguments before execution:

public function execute(...$arguments): mixed
{
    $orderId = $arguments['order_id'] ?? null;

    if ($orderId === null || !is_string($orderId)) {
        return json_encode([
            'error' => 'Invalid order_id parameter',
        ]);
    }

    // Proceed with execution
}

Handle errors gracefully

Return error information in a consistent format:

public function execute(...$arguments): mixed
{
    try {
        $result = $this->performOperation($arguments);

        return json_encode([
            'success' => true,
            'data' => $result,
        ]);
    } catch (\Exception $e) {
        return json_encode([
            'success' => false,
            'error' => $e->getMessage(),
            'error_code' => $e->getCode(),
        ]);
    }
}

Security considerations

Validate permissions. Always check user permissions before executing sensitive operations;
Sanitize inputs. Sanitize all inputs before using them in queries or operations;

Limitations

Provider-specific constraints

Different AI providers have varying limitations:

Maximum number of tools per request
Maximum tool description length
Supported parameter types
Tool execution timeout limits

Performance considerations

Tool execution adds latency to AI requests:

Each tool call requires additional round-trip to the AI provider
Complex tools may take time to execute
Multiple sequential tool calls increase total response time

Consider these factors when designing time-sensitive features.

Token usage

Tool definitions and results consume tokens from your AI provider quota. Monitor token consumption when using tools extensively.

AI Commerce overview

Thu, 13 Aug 2026 05:03:30 +0000

AI Commerce is a SprykerFeature package (spryker-feature/ai-commerce) that provides AI-powered storefront capabilities. All features in this package are built on top of the AiFoundation abstraction layer, which decouples business logic from the underlying AI provider.

Package structure

The spryker-feature/ai-commerce package follows the standard Spryker module structure and ships modules across the Zed, Yves, Client, and Shared layers. Each AI feature within the package is self-contained — it registers its own plugins, configuration, and translations.

AiFoundation integration

Every AI feature in the package communicates with an AI provider exclusively through AiFoundation. This means:

Provider-agnostic — the AI provider (for example, OpenAI) is configured outside the feature code. Switching providers requires only a configuration change.
Named configurations — each feature can use a dedicated named configuration entry in AiFoundation. This isolates provider settings per feature and keeps audit log entries separate, making it easy to review or debug AI interactions for a specific feature.
Audit logging — all AI calls made through AiFoundation are recorded in the audit log. Using a named configuration per feature lets you filter the log by feature.

For the base AiFoundation setup, see Install AI Commerce.

Available features

FEATURE	DESCRIPTION
Visual Add to Cart	Lets buyers upload a product image on the Quick Order page. AI recognizes products and quantities in the image and pre-fills the quick order form with matching SKUs.
Back Office Assistant	An AI-powered chat widget embedded in the Back Office. Admin users can ask natural language questions, navigate the Back Office, diagnose order issues, and create or update discounts.
Smart PIM	An AI assistant embedded in the Back Office product creation and editing pages. Helps catalog managers fill in product attributes, descriptions, and metadata through a conversational interface.
Smart CMS Content Assistant	An AI-powered panel in the Back Office CMS Page and CMS Block glossary editors. Lets Back Office users generate and refine placeholder content per locale through a conversational AI interface.

Installation

To install the AI Commerce base package, see Install AI Commerce. Individual features require additional installation steps — see their respective installation guides linked in the table above.

Customization

To let a feature or agent work with data that no built-in tool covers, add a project-level tool and toolset. For instructions and the security rules that apply, see Extend AI Commerce agents with custom toolsets.

Add a custom Back Office Assistant agent

Thu, 13 Aug 2026 05:03:30 +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.

To add tools to an agent or feature that already exists instead of creating a new agent, see Extend AI Commerce agents with custom toolsets.

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.

For a full tool implementation example and the security rules that apply to every tool you expose, see Extend AI Commerce agents with custom toolsets.

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.

Security release notes 202608.0

Wed, 12 Aug 2026 15:37:31 +0000

This document describes the security-related issues that have been recently resolved. For additional support with this content, [contact our support](https://support.spryker.com/). If you found a new security vulnerability, contact us at [security@spryker.com](mailto:security@spryker.com). ## Removal of eval() function Use of the eval() function has been removed from the codebase. Even though no security issues were identified due to its use, it was removed in order to follow security best practices. ### Affected modules - `spryker/testify`: < 3.66.0 ### Fix the vulnerability Update the affected Spryker package: ```bash composer update spryker/testify:"^3.66.0" composer show spryker/testify # Verify the version ``` Add or adjust the $config[TestifyConstants::IS_DATA_BUILDER_RULE_EVAL_ENABLED] line within the `config/Shared/config_default.php` file: ```bash use Spryker\Shared\Testify\TestifyConstants; if (class_exists(TestifyConstants::class)) { $config[TestifyConstants::IS_DATA_BUILDER_RULE_EVAL_ENABLED] = false; } ``` ## Vulnerabilities in third-party dependencies Several third-party dependencies were updated to address publicly known vulnerabilities present in earlier versions. The updated dependencies are listed below. ### Affected packages - `symfony/twig-bridge`: < 6.4.43 - `nikic/php-parser` : < 5.8.0 - `aws/aws-sdk-php` : < 3.389.3 - `symfony/security-core` : < 6.4.43 ### Fix the vulnerability ```bash composer update symfony/twig-bridge nikic/php-parser aws/aws-sdk-php symfony/security-core ```

Workflows feature overview

Tue, 11 Aug 2026 14:34:40 +0000

The Workflows feature lets Back Office users design and operate state machines directly from the Back Office. A workflow describes how a subject moves through a sequence of states as events occur, conditions are met, or timeouts elapse. A subject can be anything — a company, a user, a product, or a custom entity. A workflow starts when its subject reaches a specific application event, defined in a trigger: for example a company being created, a user registering, or a merchant being updated. From then on, each subject runs through the workflow independently. Unlike classic state machines, which are defined in XML files and require a deployment to change, a workflow is created and adjusted by a Back Office user. This puts process design in the hands of the people who own the process. ## An example Consider onboarding a new B2B company. When a company is created, a workflow starts and walks it through a series of states: *business verification*, then *contract agreement*, then *customer group assignment*, and finally *approved*. Some steps advance on their own once a condition is met (for example, the business has been verified); others wait for a Back Office user to confirm; and a step can time out if nothing happens. The whole process — its states, the order of the steps, and the rules between them — is defined and adjusted in the Back Office, not in code. ## How a workflow works The clearest way to understand the feature is to follow one small workflow from start to finish. The example below is a company-onboarding process: a new company moves from `created` to `approved`, passing a verification check and an automatic waiting step along the way. A workflow definition is an XML document in the `state-machine-01` format. It has three parts: `states`, `transitions`, and `events`: ```xml {% raw %} created business verification initiate business verification approved verify business business verification denied verify business {% endraw %} ``` Here is how a company travels through this definition: 1. **The instance starts.** A trigger (see [Triggers](#triggers)) starts an instance for a new company. The instance begins in the initial state you set when you author the version — here, `created`. 2. **An `onEnter` event fires automatically.** The `initiate` event is marked `onEnter="true"`, so the engine fires it as soon as the instance is in `created`, moving the company to `business verification`. 3. **A timeout waits, then a condition decides.** The `verify business` event has a `timeout="3 second"`. After the timeout elapses, the engine evaluates the two `verify business` transitions in order. The first is guarded by the `CompanyOnboarding/IsBusinessVerified` condition: if it returns `true`, the company moves to `approved`. If not, the unguarded transition sends it to `denied`. Three ideas in that trace do the heavy lifting, and each maps to a piece of project code a developer can plug in: | In the definition | What it means | You provide | |-------------------|---------------|-------------| | `event` | A named step. It can fire automatically (`onEnter`), after a delay (`timeout`), on a user action (`manual`), or from application code. | Nothing — events are declared in the XML. | | `condition="…"` | A guard that lets a transition fire only when a business rule is true. | A [condition plugin](#conditions). | | `command="…"` | Project logic to run during a transition (not shown above — for example, "mark the company approved"). | A [command plugin](#commands). | ## Core concepts A workflow is built from four entities. The example above is a *version* of a *process*; running it for one company creates an *instance*; and what starts that instance is a *trigger*. You manage all of them in the Back Office under **Administration > Workflows**. | Concept | What it is | |---------|------------| | Process | The workflow itself: a named process bound to a subject type (for example `Company`). It is created once and never replaced — all versions and instances belong to it. | | Version | One complete definition of the process at a point in time (the XML above): its states, transitions, and events, plus the initial state. A process can have many versions, but only one is *active* at a time. | | Trigger | Connects an application event (for example "a company was created") to the process, so that event automatically starts a new instance. | | Instance | One subject running through the workflow — for example one specific company being onboarded. It tracks the subject's current state. | ### Why versions matter Every instance is pinned to the version it started on. When you activate a newer version, running instances do **not** jump to it — they finish on the version they began with. Only *new* instances start on the newly active version. This is what makes editing a live process safe. You publish an improved version for future subjects, while in-flight subjects complete on the exact rules they started with — no half-migrated instances and no transitions that suddenly point at states that no longer exist. ## Subjects A workflow is attached to a *subject type*, which you choose when you create the process. It is not limited to companies: the subject type is a label you define — `Company`, `Customer`, `Product`, or anything your project needs. The trigger you configure decides which application event starts an instance for that subject. For example, a process with subject type `Company` and a trigger on company creation starts one instance per created company, and each company then runs its own instance independently. ## Instances An *instance* is a single subject running through a workflow — for example one specific company being onboarded. Each instance is pinned to the version it started on and tracks its current state. In the Back Office you can inspect instances, see their current state, and trigger any manual actions the workflow defines (for example, a step that a Back Office user must confirm before the workflow continues). {% info_block infoBox "Instance history retention" %} Each instance and its transition history are kept in the database. This MVP does not ship an automated cleanup or retention job, so plan for periodic housekeeping if you expect a high volume of instances. {% endinfo_block %} ## Transitions A workflow advances through three kinds of transitions: - **Event transitions**: triggered by an application event or a manual action in the Back Office. - **Condition transitions**: advance automatically once a business condition becomes true. - **Timeout transitions**: advance automatically after a defined period elapses. Condition and timeout transitions have no incoming event to push them, so two console commands advance them on a schedule: - `workflow:check-condition` — advances every condition transition whose condition has become `true`. - `workflow:check-timeout` — advances every timeout transition whose timeout has elapsed. Without them, an instance that reaches a condition or timeout transition waits forever. These commands are **not** scheduled out of the box; the [installation guide](/docs/dg/dev/integrate-and-configure/integrate-workflow-feature.html) shows how to register them as recurring jobs so workflows progress on their own. ## Triggers A *trigger* connects an application event to a workflow so that a new instance starts automatically. For example, creating a company can trigger a new onboarding instance. You select the trigger event in the Back Office when you configure the process; the available events are provided by trigger plugins (see [Extending a workflow](#extending-a-workflow)). ## Extending a workflow The definition references project code by name in two places: `condition="…"` and `command="…"`. A developer implements each as a plugin and registers it in the project `WorkflowDependencyProvider` (see the [installation guide](/docs/dg/dev/integrate-and-configure/integrate-workflow-feature.html)). The engine matches a plugin to a definition by two values: its `getName()` (the string used in the XML) and its `getSubjectType()` (so the same name can behave differently for different subjects). ### Commands A *command* runs project logic during a transition — for example, marking a company approved when it enters the `approved` state. Reference it in the definition as `command="CompanyOnboarding/MarkCompanyActiveAndApproved"`, then implement `WorkflowCommandPluginInterface` so `getName()` returns that same string: ```php interface WorkflowCommandPluginInterface extends CommandPluginInterface { public function getName(): string; public function getSubjectType(): string; } ``` ### Conditions A *condition* guards a transition: the workflow takes that transition only when the condition returns `true` — for example, "the business is verified." Reference it as `condition="CompanyOnboarding/IsBusinessVerified"`, then implement `WorkflowConditionPluginInterface`: ```php interface WorkflowConditionPluginInterface extends ConditionPluginInterface { public function getName(): string; public function getSubjectType(): string; } ``` ### Trigger plugins A trigger plugin provides an application event that can start an instance. Unlike commands and conditions — which are named inside the definition XML — a trigger is chosen in the Back Office when you configure the process. A trigger plugin binds an application event (`getEventName()`, for example `Entity.spy_company.create`) to a subject type, so that whenever that event fires for that subject, a new instance starts. Implement `StateMachineProcessTriggerPluginInterface`: ```php interface StateMachineProcessTriggerPluginInterface { public function getEventName(): string; public function getName(): string; public function getSubjectType(): string; public function getDescription(): string; } ``` ## Provisioning workflows on installation Workflows can be shipped with a project and provisioned automatically during installation through data import. This means a demo or production workflow is available immediately after setup, and re-importing the same workflow does not create duplicates. See the [installation guide](/docs/dg/dev/integrate-and-configure/integrate-workflow-feature.html) for details.

Install the Workflows feature

Tue, 11 Aug 2026 13:42:49 +0000

This document describes how to install the Workflow feature. ## Prerequisites Install the required modules: | MODULE | VERSION | |--------|---------| | spryker/workflow | ^1.0.0 | | spryker/state-machine | ^2.26.0 | | spryker/data-import | ^1.27.1 | | spryker/gui | ^5.3.2 | | spryker/kernel | ^3.84.0 | ## Install feature core ### 1) Install the required modules Install the Workflow module and update its dependencies to the required versions: ```bash composer require spryker/workflow:"^1.0.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules are available in `vendor/spryker/`: | MODULE | |--------| | spryker/workflow | | spryker/state-machine | | spryker/data-import | | spryker/gui | {% endinfo_block %} ### 2) Set up the database schema and transfer objects Apply the database changes and generate the transfer objects: ```bash docker/sdk cli console propel:install docker/sdk cli console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following tables exist in the database: | DATABASE ENTITY | TYPE | EVENT | |-----------------|------|-------| | spy_state_machine_process | table | created | | spy_state_machine_process_definition | table | created | | spy_state_machine_process_definition_instance | table | created | | spy_state_machine_process_definition_trigger | table | created | {% endinfo_block %} ### 3) Configure navigation The Workflow Back Office menu entry is added under **Administration**. Add the following node to `config/Zed/navigation.xml`: ```xml Workflows Workflows workflow process index ``` Rebuild the navigation cache: ```bash docker/sdk cli console navigation:build-cache docker/sdk cli console cache:empty-all ``` {% info_block warningBox "Verification" %} In the Back Office, go to **Administration > Workflows** and make sure the page opens. {% endinfo_block %} ### 4) Create a workflow in the Back Office Once the feature is installed, a Back Office user can author a workflow through the UI: 1. Go to **Administration > Workflows** and create a process. Give it a name and a subject type (for example `Company`). 2. Open the process's **Workflow Versions**, then **Create Version**: paste the definition XML (in the `state-machine-01` format) and set the initial state, which is the process's entry point. Save the version. 3. **Activate** the version. 4. Open the process's **Workflow Triggers**. The page lists the trigger events registered for the process's subject type ("Select events that start this workflow"). Select one or more and **Save Triggers**. 5. **Activate** the process. The workflow is now live: whenever a selected trigger event fires for a subject of the configured type, a new instance starts on the active version. {% info_block infoBox "Provisioning instead of manual authoring" %} To ship a ready-made workflow with your project instead of creating it by hand, use the data import in the following steps. The two approaches are interchangeable — both produce the same process, versions, and triggers. {% endinfo_block %} ### 5) Register command, condition, and trigger plugins Register your project's commands, conditions, and start triggers by extending the core `WorkflowDependencyProvider`. **src/Pyz/Zed/Workflow/WorkflowDependencyProvider.php** ```php */ protected function getCommandPlugins(): array { return [ // new MyCommandPlugin(), ]; } /** * @return array<\Spryker\Zed\Workflow\Dependency\Plugin\WorkflowConditionPluginInterface> */ protected function getConditionPlugins(): array { return [ // new MyConditionPlugin(), ]; } /** * @return array<\Spryker\Zed\Workflow\Dependency\Plugin\StateMachineProcessTriggerPluginInterface> */ protected function getTriggerPlugins(): array { return [ // new MyProcessTriggerPlugin(), ]; } } ``` For the plugin interfaces and how the engine resolves them, see [Extending a workflow](/docs/pbc/all/back-office/latest/base-shop/workflow-feature-overview.html#extending-a-workflow). ### 6) Register the data importer Register the Workflow data import plugin so workflows can be provisioned from CSV. **src/Pyz/Zed/DataImport/DataImportDependencyProvider.php** ```php use Spryker\Zed\Workflow\Communication\Plugin\DataImport\WorkflowDataImportPlugin; /** * @return array<\Spryker\Zed\DataImport\Dependency\Plugin\DataImportPluginInterface> */ protected function getDataImporterPlugins(): array { return [ new WorkflowDataImportPlugin(), ]; } ``` ### 7) Provide the import data The import uses two files: a definition XML file that describes the state machine (its states, transitions, and events, in the same `state-machine-01` format used by the OMS), and a CSV that provisions the workflow and points at that XML file. Storing the definition in its own file keeps the CSV readable and lets you edit the state machine like any other XML process. The `definition` column in the CSV holds the path to the XML file, relative to the project root. **data/import/common/common/workflow/company_onboarding.xml** ```xml {% raw %} {% endraw %} ``` **data/import/common/common/workflow.csv** ```csv name,subject_type,description,initial_state,version,definition,trigger_events,is_active CompanyOnboarding,Company,B2B company onboarding demo workflow,created,1,data/import/common/common/workflow/company_onboarding.xml,"Entity.spy_company.create,Entity.spy_company.update",1 ``` | COLUMN | REQUIRED | DESCRIPTION | |--------|----------|-------------| | name | yes | Workflow (process) name. | | subject_type | yes | The subject the workflow applies to, for example `Company`. | | description | no | Human-readable description. | | initial_state | yes | The state a new instance starts in. | | version | yes | Version number. The importer upserts on `(name, version)`, so re-imports do not create duplicates. | | definition | yes | Path to the definition XML file, relative to the project root — for example `data/import/common/common/workflow/company_onboarding.xml`. | | trigger_events | no | The Publish & Synchronize event names custom type of triggers that start an instance, for example `Entity.spy_company.create`. To list several events, separate them with commas and wrap the whole cell in double quotes so the commas are not read as CSV column separators: `"Entity.spy_company.create,Entity.spy_company.update"`. | | is_active | no | `1` activates this version and its process. | Run the importer directly to verify: ```bash docker/sdk cli console data:import workflow ``` ### 8) Add the importer to the install recipe Register the workflow importer in the data import configuration so it runs during deployment. Add it to the region import config that the install recipes invoke through `data:import`. Add the following entry to the import config of **every region and environment you deploy** — the local files (`data/import/local/full_.yml`) and the production files (`data/import/production/full_.yml`). Adding it to only one file provisions the workflow only for that region and environment. **data/import/local/full_EU.yml** (and the other `full_.yml` files, local and production) ```yaml - data_entity: workflow source: data/import/common/common/workflow.csv ``` Place the entry after the modules whose subjects the workflow attaches to (for example `company`), so those subjects exist before the workflow is provisioned. The install recipes already call `data:import` with the region import config, so no recipe change is required beyond this entry. {% info_block warningBox "Verification" %} Run the install recipe and make sure the workflow with its versions appears under **Administration > Workflows**. {% endinfo_block %} ### 9) Schedule the condition and timeout jobs Condition and timeout transitions have no event, so they must be advanced by two console commands: `workflow:check-condition` and `workflow:check-timeout`. These commands are **not** scheduled out of the box — register them as recurring jobs the same way the OMS and state machine checks are scheduled. Add the following jobs to `config/Zed/cronjobs/jenkins.php`: ```php $jobs[] = [ 'name' => 'workflow-check-conditions', 'command' => '$PHP_BIN vendor/bin/console workflow:check-condition', 'schedule' => '* * * * *', 'enable' => true, 'stores' => $allStores, ]; $jobs[] = [ 'name' => 'workflow-check-timeouts', 'command' => '$PHP_BIN vendor/bin/console workflow:check-timeout', 'schedule' => '* * * * *', 'enable' => true, 'stores' => $allStores, ]; ``` {% info_block warningBox "Verification" %} Start an instance, then run `docker/sdk cli console workflow:check-condition` and confirm the instance advances in `spy_state_machine_process_definition_instance`. {% endinfo_block %}

Typed collections in the published contract

Tue, 11 Aug 2026 12:00:31 +0000

This document explains what an object collection publishes in the OpenAPI contract, and the constraints that make typing an existing list field a deliberate decision. For the schema syntax itself, see [Object collections](/docs/integrations/spryker-api/api-platform/resource-schemas.html#object-collections). This page covers what that syntax produces for API consumers and what to check before adopting it. ## What an object collection publishes A `type: array` property whose `items` are a typed object publishes the element as a referenced component schema, so the contract describes a single element as precisely as it describes a single nested object. Given this property on the `Products` resource: ```yaml prices: type: array writable: false description: 'Prices per store and currency' items: type: object properties: grossAmount: { type: integer } currency: { type: string } ``` the published contract references a generated element schema: ```json "prices": { "type": "array", "description": "Prices per store and currency", "items": { "$ref": "#/components/schemas/ProductsPricesBackendObject" } } ``` and registers that schema in the same document, so the reference always resolves: ```json "ProductsPricesBackendObject": { "type": "object", "properties": { "grossAmount": { "type": "integer" }, "currency": { "type": "string" } } } ``` Without an `items` block, the same property publishes as a bare `"type": "array"` with no element description. Consumers cannot see the element shape, and SDK generators produce an untyped collection. {% info_block infoBox "Reference prefix" %} The prefix depends on the document flavor. The OpenAPI document uses `#/components/schemas/`, while a plain JSON Schema document uses `#/definitions/`. Both point at the same generated element schema. {% endinfo_block %} ### How the element type reaches the contract PHP has no generics, so the property itself stays a plain `array` and the element type travels in a docblock on the generated resource class: ```php /** * @var array<\Generated\Api\Backend\Products\ProductsPricesBackendObject> */ public array $prices = []; ``` API Platform reads that docblock through its property-metadata chain while building the schema, which is what lets it emit the reference and register the element schema itself. This matters when you are debugging: if the docblock is missing from the generated class, the contract falls back to an untyped array. See [Troubleshooting](/docs/integrations/spryker-api/api-platform/troubleshooting.html). ## Lists of scalars A list of scalars needs no element class and produces no reference: ```yaml skus: type: array items: type: string ``` The property stays a plain typed array. This is complete as it is — there is nothing further to declare. ## Edge cases and constraints ### A typed element is a closed shape This is the most important constraint on this page. Generated value objects copy only the fields you declare. Both `fromArray()` and `toArray()` iterate the declared properties and nothing else. Adding an `items` block to a list that is already part of a released response therefore **silently drops every payload key you did not declare** in `items.properties`. Nothing warns you. The response loses fields, and consumers relying on them break. For a **new** field this never arises — declare `items` from the start and the shape is complete by construction. For an **existing** field, treat adoption as a backward-compatibility decision: 1. Capture a real response payload for the endpoint. 2. List the keys present on a single element of the list. 3. Compare them against the `items.properties` you intend to declare. 4. Add every missing key before adopting, or do not adopt yet. {% info_block warningBox "Check the payload, not the transfer object" %} Compare against a real response, not the transfer object behind it. A provider can add, rename, or omit keys on the way out, so the transfer object is not a reliable description of what consumers receive. {% endinfo_block %} ### `openapiContext.items` does not type anything This is the most common mistake, because the two forms look almost identical in YAML. An `items` block nested under `openapiContext` is documentation passthrough. It describes the element in the OpenAPI document, but it generates no class and produces no reference: ```yaml # Documentation only — no generated class, no typed reference categories: type: array openapiContext: items: type: object properties: categoryKey: { type: string } ``` Only a sibling of `type: array` produces a typed element schema: ```yaml # Typed — generates a class and publishes a reference categories: type: array items: type: object properties: categoryKey: { type: string } ``` ### Declaring both forms is rejected A property must not declare both `items` and `openapiContext.items`. Schema validation rejects the combination, because `openapiContext` is merged on top of the derived schema: the hand-written shape would win and the typed element schema would be discarded without a trace. Keep the `items` sibling and remove the `openapiContext.items` block. ### Relationship properties cannot declare `items` A property that is a relationship target declared in `includes` must not also declare a sibling `items` block. Schema validation rejects the combination. Only one docblock is emitted per property, and a relationship property already receives one describing its target resource. The two declarations compete for the same slot, so the ambiguity is rejected rather than silently resolved. A property is either a relationship to another resource or an inline object list — not both. See [Relationships](/docs/integrations/spryker-api/api-platform/relationships.html). ### Nested lists inside `openapiContext` stay hand-written A list nested inside an `openapiContext` block is as hand-described as the block containing it. It never becomes a typed reference, however it is declared, because nothing under `openapiContext` reaches the generator. ### Providers can keep assigning raw arrays Declaring `items` does not break a provider that assigns plain arrays instead of value objects. The generated mapping code guards both directions: `toArray()` maps an element through its `toArray()` only when the element is an instance of the generated class, and `fromArray()` hydrates an element only when it is an array. Anything else passes through unchanged. You can therefore improve a field's published contract without rewriting its provider at the same time. ### Nullable collections preserve null A nullable typed collection preserves `null` rather than coercing it to an empty array. `toArray()` returns `null` when the property is `null`, and `fromArray()` falls back to `null` instead of `[]` when the key is absent or is not an array. ### Canonical objects behave slightly differently When the element shape is shared across resources through a canonical object, the collection form and the single form differ: - A canonical **single** object is typed directly to the shared class. - A canonical **collection** stays a plain `array` and names its element class through the docblock, for the same reason any collection does — PHP has no generics. Both publish a reference to the same shared component schema. See [Project-defined canonical nested objects](/docs/integrations/spryker-api/api-platform/resource-schemas.html#project-defined-canonical-nested-objects). ## Adoption status No property in the code base declares a sibling `items` block on a resource yet. The capability is available, and adoption happens per field so each one can be checked against a real payload first, as described in [A typed element is a closed shape](#a-typed-element-is-a-closed-shape). If you are looking for an existing example to copy, there is not one yet — use this page and [Object collections](/docs/integrations/spryker-api/api-platform/resource-schemas.html#object-collections) instead.

Troubleshooting API Platform

Tue, 11 Aug 2026 12:00:31 +0000

This document provides solutions to common issues when working with API Platform in Spryker. ## Generation issues ### Resources not generating **Symptom:** Running `docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate` completes but no resources are created. **Possible causes:** 1. **Schema file location is incorrect** ```bash ❌ src/Pyz/Glue/Customer/api/customers.resource.yml ✅ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml ``` 2. **API type not configured** Check `config/{APPLICATION}/packages/spryker_api_platform.php`: ```php return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void { $sprykerApiPlatform->apiTypes([ 'backend', // Must match directory name ]); }; ``` 3. **Bundle not registered** Verify `config/{APPLICATION}/bundles.php` includes: ```php SprykerApiPlatformBundle::class => ['all' => true], ``` **Solution:** ```bash # Debug to see what's being discovered docker/sdk cli glue api:debug --list # Check schema validation docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Force regeneration docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --force ``` ### Schema validation errors **Symptom:** Generation fails with schema validation errors. **Common errors:** ```bash # Error: Invalid operation type ❌ operations: - type: CREATE ✅ operations: - type: Post # Error: Invalid property type ❌ type: int ✅ type: integer # Error: Missing resource name ❌ resource: shortName: customers ✅ resource: name: Customers shortName: customers # Error: Property declares both "items" and "openapiContext.items" # openapiContext is merged on top of the derived schema, so the hand-written # shape would win and the typed element schema would be discarded silently. ❌ categories: type: array items: type: object properties: categoryKey: { type: string } openapiContext: items: type: object properties: categoryKey: { type: string } ✅ categories: type: array items: type: object properties: categoryKey: { type: string } # Error: Property is both a relationship and an inline object list # A relationship property already receives a docblock describing its target # resource, and only one docblock is emitted per property. ❌ includes: - relationshipName: addresses targetResource: CustomersAddresses properties: addresses: type: array items: type: object properties: city: { type: string } ✅ includes: - relationshipName: addresses targetResource: CustomersAddresses ``` **Solution:** 1. Check schema against examples in documentation 2. Use `--validate-only` flag for detailed validation: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` 3. Inspect merged schema: ```bash docker/sdk cli glue api:debug resource-name --show-merged ``` ### A list property still publishes as an untyped array **Symptom:** A `type: array` property has an `items` block, but the published contract shows `"type": "array"` with no `items` reference, and SDK generators produce an untyped collection. **Possible causes:** 1. **`items` is nested under `openapiContext` instead of being a sibling of `type: array`** Only a sibling triggers typing. An `items` block under `openapiContext` is documentation passthrough: it generates no class and produces no reference. ```yaml ❌ categories: type: array openapiContext: items: type: object properties: categoryKey: { type: string } ✅ categories: type: array items: type: object properties: categoryKey: { type: string } ``` 2. **`items.type` is a scalar** A list of scalars generates no element class and no reference. This is expected — there is nothing to type. 3. **The resource was not regenerated after the schema change** ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate ``` 4. **Stale generated code is still being served** See [Inspecting generated code](#inspecting-generated-code) to confirm what is on disk. **Solution:** Confirm the generated resource class carries a `@var array<\Generated\…>` docblock on the property. That docblock is what API Platform reads to build the element reference — if it is absent, the contract falls back to an untyped array. See [Typed collections in the published contract](/docs/integrations/spryker-api/api-platform/typed-collections.html). ## Runtime issues ### Provider/Processor not found **Symptom:** ```bash Error: Class "Pyz\Glue\Customer\Api\Backend\Provider\CustomerBackendProvider" not found ``` **Possible causes:** 1. Class doesn't exist or namespace is wrong 2. Not registered in the Dependency Injection container 3. Typo in the schema file **Solution:** 1. Verify the class exists and namespace matches: ```php namespace Pyz\Glue\Customer\Api\Backend\Provider; class CustomerBackendProvider implements ProviderInterface ``` 2. Ensure services are auto-discovered in `ApplicationServices.php`: ```php $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); ``` 3. Check class name in the resource schema file of the module matches exactly: ```yaml provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" ``` ### Validation not working **Symptom:** API accepts invalid data despite validation rules. **Possible causes:** 1. Validation schema file not found 2. Wrong operation name in validation schema 3. Validation groups not matching **Solution:** 1. Ensure validation file exists: ```bash ✅ resources/api/backend/customers.validation.yml ``` 2. Match operation names to HTTP methods: ```yaml post: # For POST /customers email: - NotBlank patch: # For PATCH /customers/{id} email: - Optional: constraints: - Email ``` 3. Check generated resource class (for example `Generated\Api\Storefront\CustomersStorefrontResource`) has validation attributes: ```php #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; ``` ### API documentation UI not displaying correctly **Symptom:** When accessing the root URL of your API application, you see: - Missing styles/CSS - Broken JavaScript functionality - Plain HTML without formatting - "Failed to load resource" errors in the browser console **Cause:** Assets were not installed after API Platform integration. **Solution:** Run the appropriate assets:install command for your application: #### For Glue application ```bash docker/sdk cli glue assets:install public/Glue/assets --symlink ``` #### For GlueStorefront ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue assets:install public/GlueStorefront/assets/ --symlink ``` #### For GlueBackend ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue assets:install public/GlueBackend/assets/ --symlink ``` Then verify the documentation UI loads correctly by visiting the root URL: - Storefront: `https://glue-storefront.mysprykershop.com/` - Backend: `https://glue-backend.mysprykershop.com/` {% info_block warningBox "Required after integration" %} The `assets:install` command must be run after integrating API Platform and whenever API Platform assets are updated. This is a required step documented in [Integrate API Platform](/docs/integrations/spryker-api/migrate-from-glue-to-api-platform/integrate-api-platform.html). {% endinfo_block %} ### 404 Not Found for API endpoints **Symptom:** API requests return 404. **Possible causes:** 1. Router not configured 2. Routes not loaded 3. Wrong URL format **Solution:** 1. Verify `SymfonyFrameworkRouterPlugin` is registered: ```php // RouterDependencyProvider protected function getRouterPlugins(): array { return [ new GlueRouterPlugin(), new SymfonyFrameworkRouterPlugin(), // Must be present ]; } ``` 2. Check API documentation for correct URLs: ```bash Storefront: https://glue-storefront.mysprykershop.com/ Backend: https://glue-backend.mysprykershop.com/ ``` The interactive API documentation is available at the root URL of each application. 3. Use correct URL format: ```bash ❌ /api/v1/customers ✅ /customers ``` ### Requests without an `Accept` header are rejected or return the wrong format **Symptom:** A client request that omits the `Accept` header — or sends only `Accept: */*` — returns `406 Not Acceptable`, or a response in a format other than the legacy `application/vnd.api+json`. The legacy Glue REST API silently accepted the same request and answered with `application/vnd.api+json`. **Cause:** API Platform runs content negotiation that requires a satisfiable `Accept` header and does not assume the legacy Glue default. This is a behavioral difference from the legacy Glue REST stack. **Solution:** 1. Upgrade `spryker/api-platform` to **1.15.0 or higher**. Its `AcceptHeaderFallbackSubscriber` restores the legacy behavior — a missing or `*/*` `Accept` header defaults to `application/vnd.api+json`: ```bash composer update spryker/api-platform --with-dependencies ``` 2. If you cannot upgrade, send an explicit `Accept` header from the client: ```bash curl -H "Accept: application/vnd.api+json" https://glue-backend.mysprykershop.com/customers ``` ### Pagination not working **Symptom:** All results returned instead of paginated response. **Solution:** 1. Enable pagination in the schema file of the defining module: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 ``` 2. Return `PaginatorInterface` from provider: ```php use ApiPlatform\State\Pagination\TraversablePaginator; return new TraversablePaginator( new \ArrayObject($results), $currentPage, $itemsPerPage, $totalItems ); ``` 3. Use pagination query parameters: ```bash GET /customers?page=2&itemsPerPage=20 ``` ### Client cannot change items per page **Symptom:** The `itemsPerPage` query parameter is ignored. **Solution:** Enable client-side items-per-page control and set a maximum limit in the resource schema: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 paginationClientItemsPerPage: true paginationMaximumItemsPerPage: 100 ``` Without `paginationClientItemsPerPage: true`, the `itemsPerPage` query parameter has no effect. The `paginationMaximumItemsPerPage` option prevents clients from requesting excessively large pages. ### Client cannot disable pagination **Symptom:** The `pagination=false` query parameter is ignored and results are still paginated. **Solution:** Enable client-side pagination control in the resource schema: ```yaml resource: paginationClientEnabled: true ``` Without `paginationClientEnabled: true`, the `pagination` query parameter has no effect. For a full reference of all pagination options, see [Resource schemas — Pagination](/docs/integrations/spryker-api/api-platform/resource-schemas.html#pagination). ## Dependency Injection issues ### Services not autowired **Symptom:** ```bash Cannot autowire service "CustomerBackendProvider": argument "$customerFacade" references class "CustomerFacadeInterface" but no such service exists. ``` **Solution:** 1. Register facade in the respective applications `ApplicationServices.php`: ```php use Pyz\Zed\Customer\Business\CustomerFacadeInterface; use Pyz\Zed\Customer\Business\CustomerFacade; $services->set(CustomerFacadeInterface::class, CustomerFacade::class); ``` 2. Ensure constructor uses interface type hints: ```php public function __construct( private CustomerFacadeInterface $customerFacade, // ✅ Interface ) {} ``` ## Performance issues ### Slow API responses **Symptom:** API endpoints respond slowly. **Solution:** 1. Verify that Opcache is enabled (`opcache.enable: 1`). Without it, PHP recompiles the whole application on every request, which adds a flat overhead of seconds to every endpoint regardless of the amount of data. See [Opcache activation](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html#opcache-activation). 2. Enable Symfony cache: ```bash docker/sdk cli glue cache:warmup ``` 3. Use pagination for collections 4. Optimize database queries in Provider 5. Use API Platform's built-in caching features ## Development tips ### Debugging schema merging See which schemas contribute to final resource: ```bash docker/sdk cli glue api:debug customers --api-type=backend --show-sources ``` Output: ```bash Source Files (priority order): ✓ vendor/spryker/customer/resources/api/backend/customers.resource.yml (CORE) ✓ src/SprykerFeature/CRM/resources/api/backend/customers.resource.yml (FEATURE) ✓ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml (PROJECT) ``` ### Inspecting generated code View the generated resource class: ```bash cat src/Generated/Api/Backend/CustomersBackendResource.php ``` Check for: - Correct property types - Validation attributes - API Platform metadata ### Testing with dry-run Preview generation without writing files: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run ``` ## Getting help If you encounter issues not covered here: 1. **Check logs:** ```bash tail -f var/log/application.log tail -f var/log/exception.log ``` 2. **Enable debug mode:** ```php debug(true); }; ``` 3. **Validate environment:** ```bash php -v # Check PHP version (8.3+) composer show | grep api-platform docker/sdk cli glue debug:container | grep -i api ``` 4. **Common error patterns:** | Error | Likely cause | Solution | |-------|--------------|----------| | `Class not found` | Autoloading issue | Run `composer dump-autoload` | | `Service not found` | DI configuration | Check `ApplicationServices.php` | | `Route not found` | Router not configured | Add `SymfonyFrameworkRouterPlugin` | | `Validation failed` | Schema mismatch | Regenerate with `--force` | | `Cache is stale` | Outdated cache | Run `cache:clear` | | API docs UI broken/unstyled | Assets not installed | Run `docker/sdk cli glue assets:install` | ## Next steps - [API Platform](/docs/integrations/spryker-api/api-platform/api-platform.html) - Overview and concepts - [Integrate API Platform](/docs/integrations/spryker-api/migrate-from-glue-to-api-platform/integrate-api-platform.html) - Setup guide - [Implement an API Platform resource](/docs/integrations/spryker-api/api-platform/enablement.html) - Creating resources - [Resource schemas](/docs/integrations/spryker-api/api-platform/resource-schemas.html) - Resource schema reference - [Validation schemas](/docs/integrations/spryker-api/api-platform/validation-schemas.html) - Validation schema reference - [Test API Platform resources](/docs/integrations/spryker-api/api-platform/testing.html) - Testing guide

Spryker Documentation

Extend AI Commerce agents with custom toolsets

How toolsets are resolved

1) Implement the tool plugin

2) Implement the toolset plugin

3) Register the toolset plugin

4) Enable the toolset for a feature

Smart CMS Content Assistant

Back Office Assistant agents

5) Adjust the system prompt

6) Verify the toolset

Smart CMS Content Assistant

Use AI tools with the AiFoundation module

Overview

Prerequisites

Use cases

Data retrieval

Calculations and processing

Business logic execution

Create tool sets

Organizing tools into sets

Register tool sets

Use tools in AI requests

Example: Support ticket creation via AI

Handle tool call results

Tool call flow

Best practices

Provide clear tool descriptions

Design focused tools

Return structured data

Validate tool arguments

Handle errors gracefully

Security considerations

Limitations

Provider-specific constraints

Performance considerations

Token usage

Related documentation

AI Commerce overview

Package structure

AiFoundation integration

Available features

Installation

Customization

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

Security release notes 202608.0

Workflows feature overview

Install the Workflows feature

Typed collections in the published contract

Troubleshooting API Platform

4.2) Resolve the configuration name from `AiCommerceConfig`