OpenTelemetry instrumentation

Thu, 23 Apr 2026 06:51:36 +0000

This document describes how to configure and instrument application for OpenTelemetry (OTel). It contains a brief overview of basic OTel concepts, but reading [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/) first is recommended. ## Convention The current implementation version (1.20.0) follows [OpenTelemetry Semantic Conventions 1.38.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/README.md). ## Trace A trace represents a single transaction. It has a unique ID and all spans are related to it. Each trace has a name that is defined automatically or can be changed as described in [Integration](#integration). ## Span A span represents a unit of work or operation, similar to executing a single method. As the building blocks of traces, spans contain the following information: - Name - Parent span ID (empty for root spans) - Start and End Timestamps - Span Context - Attributes - Span Events - Span Links - Span Status ## Hook A hook is a function that executes a closure before and after method execution, providing a way to instrument code without modifying it directly. When you execute a method, a `pre` closure is executed and opens a span. After the method is executed, a `post` closure is executed and caught. Then, missing attributes are added and the span is closed. All hooks that are autogenerated or provided by a library, such as Propel or key-value store (Redis or Valkey) hooks provided by Spryker, are registered automatically. If you want to register a hook for a class, make sure the registration is executed before the method you want to instrument is called.

Hook example

```php tracer() ->spanBuilder('ModuleName-MyClass::methodName')//Span name can be not unique, but it would easier to make it such if you want to find it easily. ->setParent($context)//Here parent span is attached to the current span. ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_FUNCTION, $function)//You can attach almost everything as a param as long as the value is scalar. Null value means that attribute will be omitted. ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_NAMESPACE, $class) ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_FILEPATH, $filename) ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_LINENO, $lineno) ->startSpan(); //Here span is attached to the global context \OpenTelemetry\Context\Context::storage()->attach($span->storeInContext($context)); }, post: static function ( $instance, array $params, $returnValue, //Result of the method execution. ?\Throwable $exception //Exception if one was thrown during the execution ) { $scope = \OpenTelemetry\Context\Context::storage()->scope(); if (null === $scope) { return; } //Here you can just check the $exception value. But in some cases you might want to take if from other places. E.g. if method that thrown exception was not instrumented, parent span should still have it. $error = error_get_last(); if (is_array($error) && in_array($error['type'], [E_ERROR, E_CORE_ERROR, E_COMPILE_ERROR, E_PARSE], true)) { $exception = new \Exception( 'Error: ' . $error['message'] . ' in ' . $error['file'] . ' on line ' . $error['line'] ); } $scope->detach(); $span = \Spryker\Service\Opentelemetry\Instrumentation\Span\Span::fromContext($scope->context()); if ($exception !== null) { $span->recordException($exception);//Exception will be attached as an event into the span. $span->setAttribute('error_message', $exception->getMessage()); $span->setAttribute('error_code', $exception->getCode()); } //Status code adds some visibility. Error status code will mark your span as a one with an error for easier navigation. $span->setStatus($exception !== null ? \OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR : \OpenTelemetry\API\Trace\StatusCode::STATUS_OK); //Span ends and sent into a span processor to be validated and prepared for exporting. $span->end(); } ); ```

## Collector Collector collects traces and sends them to a monitoring platform. Traces are sent to collector after that request is sent so it doesn't affect response time. Collector operates separately from the application and should be set up by a Cloud engineer or you can add one for you local setup yourself. ## Integration Run the latest version of the script from the [Installer repo](https://github.com/spryker/opentelemetry-installer/). If you want to integrate manually, the following sections describe all steps of the scripts. Be advised that Opentelemetry integration works with PHP 8.2 and above. if you are using older versions you must upgrade your PHP version first. ### Install required packages OTel provides instrumentation via packages that can be installed to register hooks automatically. If you want to instrument additional parts of an application, such as Symfony code, you can install respective packages from [Registry](https://opentelemetry.io/ecosystem/registry/?language=php) or other sources. {% info_block warningBox %} Install third-party packages at your own risk. {% endinfo_block %} The [spryker/opentelemetry](https://packagist.org/packages/spryker/opentelemetry) package covers the essential parts of the integration: - The entry point for instrumentation - Plugin to wire in your monitoring service - A console command to generate [hooks](https://opentelemetry.io/docs/zero-code/php/#how-it-works) for project's code, which creates spans automatically - Instrumentation of Propel, key-value store (Redis or Valkey), ElasticSearch, RabbitMQ, and Guzzle calls ### Optional: Install the Monitoring module The Monitoring module enables you to add custom attributes and events, change trace names during the request execution, and add exceptions to the root span for visibility. You can get the Monitoring module from the [Packagist](https://packagist.org/packages/spryker/monitoring). Install the module and wire the Monitoring plugin. ```php */ protected function getMonitoringExtensions(): array { return [ new OpentelemetryMonitoringExtensionPlugin(), ]; } } ``` You can call methods from Monitoring service, and they will be translated to OTel actions. Some methods act as placeholders because they're are not implemented in OTel–for example, `\Spryker\Service\Opentelemetry\Plugin\OpentelemetryMonitoringExtensionPlugin::markStartTransaction()`. ### Wire a console command Spryker is a large application, so manually creating all hooks is impractical. The `OpentelemetryGeneratorConsole` command automates hook generation for classes you want to cover with spans. ```php

Test console commands

Wed, 22 Apr 2026 12:15:12 +0000

Spryker supports several [test helpers](/docs/dg/dev/guidelines/testing-guidelines/test-helpers/test-helpers.html) to assist you in testing your project. This article provides details of how to test console commands with ConsoleHelper. To test console commands, do the following: 1. Add `\SprykerTest\Zed\Console\Helper\ConsoleHelper` to the `codeception.yml` file: ```yml suites: Communication: path: Communication actor: {ModuleName}CommunnicationTester modules: enabled: - \SprykerTest\Zed\Console\Helper\ConsoleHelper - ... ``` For more information about the `codeception.yml` file, see [Test framework](/docs/dg/dev/guidelines/testing-guidelines/test-framework.html). 2. Create the test directory `tests/PyzTests/Zed/FooModule/Communication/Plugin/Console/`, if it's not available yet. 3. Add the test class: ```php tester->getConsoleTester($command); $input = [ MyConsoleCommand::ARGUMENT_FOO => 'foo-argument', '--' . MyConsoleCommand::OPTION_BAR => 'bar-option', ]; $commandTester->execute($input); $this->assertSame(MyConsoleCommand::CODE_SUCCESS, $commandTester->getStatusCode()); // When you expect some output from the console command you can assert it with: $this->assertStringContainsString('My console command output.', $commandTester->getDisplay()); } ``` That's it. You are all set to test the console commands.

New Relic transactions grouping by queue names

Wed, 22 Apr 2026 12:15:12 +0000

By default, the `spryker/monitoring` module groups all New Relic transactions generated from a console command by the command's name. For example, `ooms:check-timeout`. This strategy works in most cases, and you can still query the data from a needed queue using [NRQL](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions/). But you might want to override this behavior. For example, you run multiple commands like `queue:task:start publish.product_abstract` and `queue:task:start sync.storage.url`. With the default naming strategy, all the calls of the command will be grouped together by `queue:task:start`. Transaction data is aggregated under the same name for all types of queue processors. In New Relic dashboard, this looks as follows: ![Transactions under the same name](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/guidelines/performance-guidelines/elastic-computing/enable-queue-task-flow-in-new-relic.md/transactions-under-the-same-name.png) ## Group transactions by queue name As queue name usually comes as the first argument of a command, to enable grouping by names, you need to need to enable grouping by the first argument as follows: 1. Integrate the `spryker/monitoring` module. 2. Provide an advanced extendable infrastructure for [New relic monitoring transaction](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/) naming strategies. This lets you implement, configure, and override the default transaction naming behavior. 3. Implement the strategy that enables configured console commands to apply naming that groups transaction by command name and first argument. 4. Enable the new strategy for `queue:task:start` on the project level. As a result, the transactions are displayed as follows: ![Aggregation of transactions](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/guidelines/performance-guidelines/elastic-computing/enable-queue-task-flow-in-new-relic.md/aggregation-of-transactions.png) ## Integrate New Relic transactions grouping by queue names For instructions, see [Integrate New Relic transactions grouping by queue names](/docs/dg/dev/integrate-and-configure/integrate-elastic-computing.html#integrate-new-relic-monitoring). ## Implementation details ![New Relic transaction grouping by name implementation details](https://confluence-connect.gliffy.net/embed/image/59eaf32b-df1e-4fb9-a5e7-64b77c8ab870.png?utm_medium=live&utm_source=custom)

Install the Configuration Management feature

Wed, 22 Apr 2026 12:15:12 +0000

This document describes how to install the Configuration Management feature. ## Prerequisites Update the required modules: | NAME | VERSION | |----|---------| | Kernel | ^3.82 | | Store | ^1.36 | | Translator | ^1.15 | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/configuration:"^0.1.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | | --- | --- | | Configuration | vendor/spryker/configuration | {% endinfo_block %} ### 2) Set up configuration Add the following configuration to extend scope support with store-level configuration: | CONFIGURATION | SPECIFICATION | NAMESPACE | | --- | --- | --- | | ConfigurationConfig | Adds `store` scope to available scopes and defines scope hierarchy (store inherits from global). | Pyz\Shared\Configuration | **src/Pyz/Shared/Configuration/ConfigurationConfig.php** ```php

``` #### 3.2) Apply database changes and generate transfers ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied by checking your database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_configuration_value | table | created | | spy_configuration_storage | table | created | {% endinfo_block %} {% info_block warningBox "Verification" %} Make sure the following changes in transfer objects have been applied: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | ConfigurationSetting | class | created | src/Generated/Shared/Transfer/ConfigurationSettingTransfer | | ConfigurationValue | class | created | src/Generated/Shared/Transfer/ConfigurationValueTransfer | | ConfigurationScope | class | created | src/Generated/Shared/Transfer/ConfigurationScopeTransfer | | ConfigurationFeature | class | created | src/Generated/Shared/Transfer/ConfigurationFeatureTransfer | | ConfigurationTab | class | created | src/Generated/Shared/Transfer/ConfigurationTabTransfer | | ConfigurationGroup | class | created | src/Generated/Shared/Transfer/ConfigurationGroupTransfer | | ConfigurationConstraint | class | created | src/Generated/Shared/Transfer/ConfigurationConstraintTransfer | | ConfigurationDependency | class | created | src/Generated/Shared/Transfer/ConfigurationDependencyTransfer | | ConfigurationSyncResponse | class | created | src/Generated/Shared/Transfer/ConfigurationSyncResponseTransfer | | ConfigurationSettingCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingCollectionTransfer | | ConfigurationScopeCollection | class | created | src/Generated/Shared/Transfer/ConfigurationScopeCollectionTransfer | | ConfigurationValueRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueRequestTransfer | | ConfigurationValueResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueResponseTransfer | | ConfigurationValidationRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValidationRequestTransfer | | ConfigurationValidationResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValidationResponseTransfer | | ConfigurationError | class | created | src/Generated/Shared/Transfer/ConfigurationErrorTransfer | | ConfigurationValueCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionRequestTransfer | | ConfigurationValueDeletion | class | created | src/Generated/Shared/Transfer/ConfigurationValueDeletionTransfer | | ConfigurationValueCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionResponseTransfer | | ConfigurationSettingValuesCriteria | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValuesCriteriaTransfer | | ConfigurationSettingValues | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValuesTransfer | | ConfigurationStorage | class | created | src/Generated/Shared/Transfer/ConfigurationStorageTransfer | {% endinfo_block %} ### 4) Configure navigation Add the Configuration Management entry to `config/Zed/navigation.xml`: ```xml Configuration Configuration Management settings configuration manage index 1 ``` Execute the following command to clear the navigation cache: ```bash console navigation:cache:remove ``` {% info_block warningBox "Verification" %} Log in to the Back Office and verify that the **Configuration** menu item appears in the main navigation sidebar. {% endinfo_block %} ### 5) Set up behavior #### 5.1) Register console commands Register the configuration sync console command: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationSyncConsole | Synchronizes configuration schemas from YAML files and generates the merged schema and settings map. | None | Spryker\Zed\Configuration\Communication\Console | **src/Pyz/Console/src/Pyz/Zed/Console/ConsoleDependencyProvider.php** Add the import statement and register the console command in `getConsoleCommands()`: ```php use Spryker\Zed\Configuration\Communication\Console\ConfigurationSyncConsole; ``` ```php protected function getConsoleCommands(Container $container): array { $commands = [ // ... new ConfigurationSyncConsole(), // ... ]; } ``` {% info_block warningBox "Verification" %} Run `console configuration:sync` and verify that it outputs the number of processed settings. {% endinfo_block %} #### 5.2) Set up queue configuration Register the Configuration storage synchronization queue in both message broker implementations. **src/Pyz/RabbitMq/src/Pyz/Client/RabbitMq/RabbitMqConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` **src/Pyz/SymfonyMessenger/src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` {% info_block warningBox "Verification" %} Run `console queue:setup` and verify that the `sync.storage.configuration` queue is created in RabbitMQ. {% endinfo_block %} #### 5.3) Register queue message processor Register the synchronization storage queue message processor for the Configuration sync queue: **src/Pyz/Queue/src/Pyz/Zed/Queue/QueueDependencyProvider.php** Add the import statements: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the processor to `getProcessorMessagePlugins()`: ```php protected function getProcessorMessagePlugins(Container $container): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION => new SynchronizationStorageQueueMessageProcessorPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Run `console queue:worker:start --stop-when-empty`. 3. Verify that the `sync.storage.configuration` queue is processed without errors. {% endinfo_block %} #### 5.4) Register publisher plugins Enable Publish & Synchronize for configuration values by registering the publisher plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationValueWritePublisherPlugin | Publishes storefront-visible, non-secret configuration values to `spy_configuration_storage` when `spy_configuration_value` entities are created, updated, or deleted. | None | Spryker\Zed\Configuration\Communication\Plugin\Publisher | **src/Pyz/Publisher/src/Pyz/Zed/Publisher/PublisherDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Publisher\ConfigurationValueWritePublisherPlugin; ``` Register the plugin group in `getPublisherPlugins()`: ```php protected function getPublisherPlugins(): array { return array_merge( // ... $this->getConfigurationStoragePlugins(), ); } ``` Add the new method: ```php /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherPluginInterface> */ protected function getConfigurationStoragePlugins(): array { return [ new ConfigurationValueWritePublisherPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Check that the `spy_configuration_storage` table contains the published value. 3. Verify that secret settings are NOT published to storage. {% endinfo_block %} #### 5.5) Register scope identifier provider plugins Register the store scope identifier provider to resolve the current store name as the scope identifier: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreConfigurationScopeIdentifierProviderPlugin | Provides the current store name as the scope identifier for the `store` scope. | Store module installed | Spryker\Zed\Store\Communication\Plugin\Configuration | **src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php** ```php */ protected function getScopeIdentifierProviderPlugins(): array { return [ new StoreConfigurationScopeIdentifierProviderPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Switch the scope selector to a specific store. 3. Verify that the scope identifier resolves to the store name (for example `DE`, `AT`). {% endinfo_block %} #### 5.6) Register Client-level request expander plugins Register the store scope expander to attach the current store scope to configuration value requests: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreScopeConfigurationValueRequestExpanderPlugin | Expands the configuration value request with the current store scope and store name as scope identifier. | Store module installed | Spryker\Client\Store\Plugin\Configuration | **src/Pyz/Configuration/src/Pyz/Client/Configuration/ConfigurationDependencyProvider.php** ```php

E2E Testing with Cypress

Wed, 22 Apr 2026 12:15:12 +0000

Cypress is an end-to-end testing framework that provides a modern approach to testing web applications. Spryker provides a Cypress boilerplate project with pre-configured setup, best practices, and examples for testing Spryker-based applications.

Cypress boilerplate

For comprehensive information on setting up and using Cypress with Spryker, refer to the cypress-boilerplate repository.

The boilerplate includes:

Pre-configured Cypress setup optimized for Spryker projects
Example test cases and patterns
Documentation and best practices
Integration guides

The boilerplate does NOT include:

Complete test coverage - you should add and adjust example tests to fit your project
Correct locators - the locators in the boilerplace are based on Spryker demo shops, adjust the locators in accordance with your project

Internal Cypress tests

Cypress tests are used by Spryker for internal testing of the core Spryker features as well. You should remove the mentions of cypress-tests from composer.json. You can re-use and customize these tests for your project, however, Spryker does not guarantee these tests will work on your project, if you keep them. Spryker recommends you use the boilerplate instead.

Resources

Repository: spryker-projects/cypress-boilerplate
Wiki: cypress-boilerplate Wiki

Architecture

Wed, 22 Apr 2026 12:15:12 +0000

One of the main tasks of a commerce platform is the possibility to customize, extend, and integrate it with external services, such as payment providers, order processors, and the like. To provide a clear path for the Spryker Commerce OS development and extension, its architecture is based on strict modularity and separation. These principles are strongly supported by the OS architecture. This architecture guide helps you understand how they are implemented on different levels.

In this section, you can learn the following topics:

The Spryker architecture and concepts.
What technologies we use.
What applications the Spryker Commerce OS is composed of.
How we enable the development of high-performance applications and their scalability.

Also, this guide is especially useful for developers, architects, and integrators dealing with Spryker Cloud Commerce OS.

Architecture as Code

Wed, 22 Apr 2026 12:15:12 +0000

Well-documented project architecture enables faster internal and external onboarding, passes audits cleanly and aligns teams on requirements. Without it, your system becomes a black box that only the original developers understand.

Architecture as Code treats architecture documentation like code, similarly to the Infrastructure-as-Code concept. Instead of storing architecture in binary formats or external tools (Word, PowerPoint, Visio, Confluence) that become outdated quickly, you store and maintain architecture documentation in version control alongside your implementation.

Spryker ships the architecture/ folder with a complete Architecture as Code structure with its demoshop codebase. You can refer to architecture/README.md that describes how to work with it. Below, you find all the general information about the structure and principles. We go into the details of each aspect to help you understand and extend this architecture documentation in your project.

Existing projects

If your project is based on a Spryker release before 202602.0, refer to the Spryker B2B Demo Marketplace master branch source code to see how the Architecture as Code structure is implemented and to copy the “architecture/” folder into your project.

Why Architecture as Code

Traditional architecture documentation suffers from several challenges:

Documentation drift - Binary formats stored separately from code become outdated quickly
Version control gaps - Specialized tools do not integrate with Git workflows
Collaboration barriers - Requires specialized software and binary file merging
AI limitations - AI tools understand code and Markdown effectively but struggle with proprietary formats and binary documents

Architecture as Code solves these problems:

Version controlled - Store in Git alongside implementation. Track every change with full history.
AI-ready - Markdown and diagrams-as-code enable AI assistance, automated validation, and intelligent analysis.
Standard formats - Use industry standards (arc42, C4, ADRs, Mermaid) that external teams understand immediately.
Collaborative - Review through pull requests. No special tools required — only a text editor.
Living documentation - Update during development, not after. Documentation evolves with your system.

Core Principles

Standards over invention - Use industry-proven formats and standards (arc42, C4, ADRs, Mermaid) instead of custom documentation.

Minimal but sufficient - Start simple. Prioritize clarity and expansion over completeness on day one.

Architecture is code - Write in plain text, store in Git, review through pull requests, deploy automatically.

Concepts and Choices

arc42

arc42 is a proven template for architecture documentation used globally across industries.

Why arc42 fits Spryker projects:

Spryker projects vary dramatically in complexity — from simple B2C shops to complex B2B marketplaces with extensive integrations and order management systems. arc42 is flexible enough to cover architecture of any complexity and scales as your Spryker implementation grows. You can start simple with minimal sections and expand as your architecture requires more detail.

The template includes 12 sections (described below) covering all architectural aspects. Section 4 (Solution Designs) provides RFC-style exploration templates. Section 9 (Architecture Decisions) uses ADRs to document decisions with context and consequences. This workflow — explore with Solution Designs, then document decisions with ADRs — ensures thoughtful architecture evolution.

C4 Model

C4 Model provides a hierarchical approach to system visualization with four levels of abstraction.

Why C4 fits Spryker architecture:

Spryker architecture unfolds naturally through C4 layers — start with the system context, zoom into containers (Yves, Zed, Client, databases, services), then dive deeper into layers and components as needed. This progressive detail matches how Spryker complexity reveals itself. The entire Spryker feature set can be shown using this unfolding approach.

Flexibility advantage:

You control the depth. Start at C1 (context) and continue only as deep as your documentation needs require. Given limited architect time, this flexibility is essential — stop at the level appropriate for your stakeholders and complexity.

Mermaid and PlantUML

Mermaid - Our primary choice for diagramming-as-code:

Renders automatically in GitHub and GitLab, and can be rendered via plugins in popular IDEs
No proprietary tools required
Covers 90% of diagram needs: flowcharts, sequences, C4 diagrams
Online editor at mermaid.live for convenient editing and better visualization than most IDEs

PlantUML - For precision when needed:

Essential for Entity-Relationship Diagrams where field-level precision matters
Online editor at plantuml.com for live editing and preview

What Comes Out of the Box

We provide templates with clear structure and minimal context, plus examples of the most common diagram types (C4, data flow, integration, sequence) and documentation patterns (ADRs, Solution Designs). AI tools work most efficiently when they see the methodology (like arc42), understand the structure, and have examples to follow. This approach enables you to generate architecture documentation much faster with AI assistance.

Templates provide examples and structural guidance — you should adapt content to your project’s context. You do not need to implement all sections immediately; remove or keep unused sections based on your documentation strategy.

Folder Structure

architecture/
├── 01-introduction-and-goals.md           # Requirements, quality goals, stakeholders
├── 02-constraints.md                      # Technical, organizational constraints
├── 03-system-scope-and-context.md         # System boundaries, external interfaces
│                                          # Includes: External systems and integration tables
├── 04-solution-designs/                   # RFC-style exploration documents
│   ├── README.md                          # Workflow explanation
│   └── sd-000-template.md                 # Solution design template
├── 05-building-block-view.md              # System decomposition
├── 06-runtime-view.md                     # Behavior and interactions
├── 07-deployment-view.md                  # Infrastructure topology
├── 08-crosscutting-concepts.md            # Patterns spanning components
├── 09-architecture-decisions/             # Architecture decision records
│   ├── README.md                          # ADR workflow and sources
│   └── adr-000-template.md                # ADR template
├── 10-quality-requirements.md             # Performance, scalability, testing
│                                          # Includes: Volume planning, testing strategy
├── 11-risks-and-technical-debt.md         # Known issues and mitigation
├── 12-glossary.md                         # Domain terminology
├── diagrams/
│   ├── c4/
│   │   ├── c1-system-context.mmd          # System context diagram
│   │   ├── c2-spryker-container.mmd       # Container diagram
│   │   └── c3-component-diagram.mmd       # Component diagram
│   ├── data-flow/
│   │   └── product-price-data-flow.mmd    # Price data flow example
│   ├── integration/
│   │   └── product-price-integration.mmd  # Integration overview with protocols
│   ├── sequence/
│   │   ├── api-payment.mmd                # Payment flow
│   │   ├── publish-sync.mmd               # Publish and Sync process
│   │   └── punchout-greenwing-integration.mmd  # PunchOut example
│   └── erd/                               # Entity-relationship diagrams (PlantUML)
└── README.md                              # Quick start and overview

Diagram Organization and Best Practices

You have two approaches to managing diagrams. Choose based on your documentation use case.

Approach 1: Inline Diagrams

Write diagram code directly in markdown using code fences:

>flowchart LR
    A --> B

Pros: Diagrams are visible immediately; self-contained

Cons: Increases file size; duplicates code if reused

Approach 2: External Diagram Files

Store diagram code in /diagrams/ folder and reference via links:

[C1 System Context](diagrams/c4/c1-system-context.mmd)

Pros: Single source-of-truth; cleaner markdown; scalable

Cons: Requires clicking to view (less immediate)

Choosing Your Approach

This template uses Approach 2 for scalability and maintainability, but projects can mix both — use external files for core views, inline for one-off diagrams.

Universal Color Scheme:

All diagrams use colors optimized for both light and dark modes:

Orange #E67E22 - Communication layer
Blue #2980B9 - Backend services, APIs
Green #27AE60 - Web apps, external systems
Purple #9B59B6 - Storage (databases, caches)
Gray #95A5A6 - Infrastructure

Templates and Guidelines

Solution Design Template (04-solution-designs/sd-000-template.md):

Metadata section (status, date, stakeholders)
Problem statement
Goals and requirements
Proposed solution with diagrams
Implementation plan
Trade-offs and alternatives

ADR Template (09-architecture-decisions/adr-000-template.md):

Standard ADR structure
Status tracking
Context, decision, consequences
Links to related decisions

Volume Planning Table (Section 10):

Pre-structured table for capacity planning covering:

Catalog entities (products, categories, prices)
Cart constraints
User load projections
B2B customers structure
Marketplace metrics
Internationalization requirements
Orders and infrastructure

Getting Help

Resources

arc42 Documentation: https://arc42.org/
C4 Model Guide: https://c4model.com/
Mermaid Syntax: https://mermaid.js.org/
ADR Guidelines: https://adr.github.io/

Common Questions

Q: Do I need to fill in every arc42 section?

A: No. Fill in what is relevant for your project. Some sections may remain minimal.

Q: Can I add custom sections?

A: First, check all 12 arc42 sections — the standard format covers most architectural concerns. If no existing section fits your content, you can add a custom section. Ensure the section purpose is clear and describe it in the README.md file.

Q: How detailed should diagrams be?

A: For C4 diagrams, follow the levels: Context (high-level), Container (more detail), Component (detailed). For other diagram types (data flow, integration, sequence), follow industry standards for that specific notation.

Q: When should I create an ADR vs Solution Design?

A: Use Solution Design for exploration. Use ADR for documenting the final decision.

Q: Can I use different diagram notations?

A: Yes. The choice is yours — we do not limit you to Mermaid or PlantUML. Ensure your notation follows the core principles: viewable by people, understandable by AI tools, and ideally diagrams-as-code (text-based format in version control).

Q: Will diagrams-as-code replace whiteboards and visual editing tools?

A: No. The art of creating and drawing diagrams — whether on whiteboards, visual tools, or pen and paper — remains valuable. Diagrams-as-code is for documenting what you have drawn and decided. Use whatever tools help you think and collaborate, then capture the final result as code for version control and documentation.

Q: Can I use images as diagrams instead of diagrams-as-code?

A: Yes, it is better to have image diagrams than no diagrams at all, but understand the trade-off. Hand-drawn or visually edited diagrams often look more polished than generated ones. However, images are not as understandable or generable by AI (at least currently) and lack version control benefits. You can use both: include beautiful images for presentations and stakeholder communication, alongside diagrams-as-code for AI assistance and documentation processes.

AI workflow orchestration with state machines

Wed, 22 Apr 2026 12:15:12 +0000

This guide shows you how to build multi-step, multi-agent AI workflows using Spryker state machines. By combining state machines with the AiFoundation module, you can orchestrate complex AI processes where agents execute tasks, make decisions based on results, and trigger subsequent steps.

Overview

Spryker state machines provide a powerful framework for orchestrating AI workflows:

States: Represent stages in your workflow (for example, “analysis_done”, “awaiting_review”)
Events: Trigger state transitions (for example, “analyze_agent” executes an AI call)
Commands: Execute AI operations, tool calls, or business logic
Conditions: Evaluate workflow item data to decide the next state (for example, “is_successful?”)
Context data: Passed through the workflow to accumulate results and drive decisions

This creates a directed graph where conditions act as edges determining the next state based on AI-generated outputs.

Key concepts

Context data: A key-value array that flows through the state machine, allowing commands to read input and write results for conditions to evaluate
Structured response: AI responses converted to structured data, enabling deterministic decision-making
Command plugins: Execute AI calls and update context with results
Condition plugins: Evaluate context data to determine workflow progression
Process name: Links XML definition to PHP configuration and state machine execution

Create a workflow process example

1. Define the state machine XML

Example: IntelligentTask01

Create config/Zed/StateMachine/AiWorkflow/IntelligentTask01.xml:

<?xml version="1.0"?>
<statemachine
    xmlns="spryker:state-machine-01"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="spryker:state-machine-01 http://static.spryker.com/state-machine-01.xsd">

    <process name="IntelligentTask01" main="true">
        <states>
            <state name="new"/>
            <state name="analysis done"/>
            <state name="analysis successful"/>
            <state name="analysis failed"/>
        </states>

        <events>
            <!-- onEnter="true" triggers the command automatically when entering source state -->
            <event name="analyze agent" onEnter="true" command="OryxAgent/Analyze"/>
            <event name="pass" onEnter="true"/>
            <event name="restart" manual="true"/>
        </events>

        <transitions>
            <!-- Initial transition: execute command on entry -->
            <transition happy="true">
                <source>new</source>
                <target>analysis done</target>
                <event>analyze agent</event>
            </transition>

            <!-- Happy path: condition passes -->
            <transition happy="true" condition="OryxAgent/Success">
                <source>analysis done</source>
                <target>analysis successful</target>
                <event>pass</event>
            </transition>

            <!-- Unhappy path: condition fails (no condition = default) -->
            <transition>
                <source>analysis done</source>
                <target>analysis failed</target>
                <event>pass</event>
            </transition>

            <!-- Recovery: manual restart from failed state -->
            <transition>
                <source>analysis failed</source>
                <target>new</target>
                <event>restart</event>
            </transition>
        </transitions>
    </process>
</statemachine>

2. Create command plugins

Command plugin example: Analyze data with Oryx Agent

<?php

use Generated\Shared\Transfer\AiWorkflowItemCollectionRequestTransfer;
use Generated\Shared\Transfer\StateMachineItemTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Spryker\Zed\StateMachine\Dependency\Plugin\CommandPluginInterface;

class OryxAgentAnalyzeCommandPlugin extends AbstractPlugin implements CommandPluginInterface
{
    public function run(StateMachineItemTransfer $stateMachineItemTransfer): void
    {
        $aiWorkflowItemTransfer = $this->loadWorkflowItem($stateMachineItemTransfer);

        $this->executeAnalysis($aiWorkflowItemTransfer);

        $request = (new AiWorkflowItemCollectionRequestTransfer())
            ->setIsTransactional(true)
            ->addAiWorkflowItem($aiWorkflowItemTransfer);

        $this->getAiFoundationFacade()->updateAiWorkflowItemCollection($request);
    }

    protected function loadWorkflowItem(
        StateMachineItemTransfer $stateMachineItemTransfer
    ): AiWorkflowItemTransfer {
        $idAiWorkflowItem = $stateMachineItemTransfer->getIdentifierOrFail();

        $aiWorkflowItemConditionsTransfer = (new AiWorkflowItemConditionsTransfer())
            ->addAiWorkflowItemId($idAiWorkflowItem);

        $aiWorkflowItemCriteriaTransfer = (new AiWorkflowItemCriteriaTransfer())
            ->setAiWorkflowItemConditions($aiWorkflowItemConditionsTransfer);

        $aiWorkflowItemCollection = $this->getAiFoundationFacade()
            ->getAiWorkflowItemCollection($aiWorkflowItemCriteriaTransfer);

        return $aiWorkflowItemCollection->getAiWorkflowItems()->offsetGet(0);
    }

    protected function executeAnalysis(AiWorkflowItemTransfer $aiWorkflowItemTransfer): void
    {
        $contextData = $aiWorkflowItemTransfer->getContextData();
        $promptMessage = $contextData['prompt'] ?? 'Please analyze this data.';

        $promptRequestTransfer = (new PromptRequestTransfer())
            ->setPromptMessage($promptMessage);

        $promptResponseTransfer = $this->getAiFoundationFacade()->prompt($promptRequestTransfer);

        $contextData['analysis_result'] = $promptResponseTransfer->getMessage();
        $contextData['success'] = $promptResponseTransfer->getIsSuccessful();
        $contextData['analyzed_at'] = time();

        $aiWorkflowItemTransfer->setContextData($contextData);
    }
}

3. Create condition plugins

Condition plugin example: Check Oryx Agent success flag

<?php

namespace Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Condition;

use Generated\Shared\Transfer\StateMachineItemTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Spryker\Zed\StateMachine\Dependency\Plugin\ConditionPluginInterface;

class OryxAgentSuccessConditionPlugin extends AbstractPlugin implements ConditionPluginInterface
{
    public function check(StateMachineItemTransfer $stateMachineItemTransfer): bool
    {
        // Load workflow item
        $aiWorkflowItemTransfer = $this->loadWorkflowItem($stateMachineItemTransfer);

        // Read success flag set by command
        $contextData = $aiWorkflowItemTransfer->getContextData();
        return $contextData['success'] ?? false;
    }
}

4. Register plugins in AiFoundation dependency provider

<?php

namespace Pyz\Zed\AiFoundation;

use Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Command\OryxAgentAnalyzeCommandPlugin;
use Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Condition\OryxAgentSuccessConditionPlugin;
use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    protected function getAiWorkflowCommandPlugins(): array
    {
        return [
            'OryxAgent/Analyze' => new OryxAgentAnalyzeCommandPlugin(),
        ];
    }

    protected function getAiWorkflowConditionPlugins(): array
    {
        return [
            'OryxAgent/Success' => new OryxAgentSuccessConditionPlugin(),
        ];
    }
}

5. Configure active processes

Create or update src/Pyz/Zed/AiFoundation/AiFoundationConfig.php:

<?php

namespace Pyz\Zed\AiFoundation;

use Spryker\Zed\AiFoundation\AiFoundationConfig as SprykerAiFoundationConfig;

class AiFoundationConfig extends SprykerAiFoundationConfig
{
    public function getAiWorkflowActiveProcesses(): array
    {
        return [
            'IntelligentTask01',
        ];
    }

    protected function getAiWorkflowInitialStateMapForProcess(): array
    {
        return [
            'IntelligentTask01' => 'new',
        ];
    }
}

6. Enable state machine handler

Update src/Pyz/Zed/StateMachine/StateMachineDependencyProvider.php:

<?php

use Pyz\Zed\StateMachine\Communication\Plugin\StateMachine\AiWorkflowStateMachineHandlerPlugin;

protected function getStateMachineHandlerPlugins(Container $container): array
{
    return [
        new AiWorkflowStateMachineHandlerPlugin(),
    ];
}

7. Set up cron jobs to process state machine events

Update config/Zed/cronjobs/jenkins.php:

$jobs[] = [
    'name' => 'check-ai-workflow-conditions',
    'command' => '$PHP_BIN vendor/bin/console state-machine:check-condition AiWorkflow',
    'schedule' => '* * * * *',
    'enable' => true,
];

$jobs[] = [
    'name' => 'check-ai-workflow-timeouts',
    'command' => '$PHP_BIN vendor/bin/console state-machine:check-timeout AiWorkflow',
    'schedule' => '* * * * *',
    'enable' => true,
];

$jobs[] = [
    'name' => 'clear-state-machine-locks',
    'command' => '$PHP_BIN vendor/bin/console state-machine:clear-locks',
    'schedule' => '0 6 * * *',
    'enable' => true,
];

8. Trigger a workflow with state machine

To start a workflow, create a workflow item with initial context data and trigger the state machine for it.

Create a workflow item and trigger the state machine:

<?php

use Generated\Shared\Transfer\AiWorkflowItemCollectionRequestTransfer;
use Generated\Shared\Transfer\AiWorkflowItemTransfer;
use Generated\Shared\Transfer\StateMachineProcessTransfer;
use Spryker\Shared\AiFoundation\AiFoundationConstants;

// 1. Create a workflow item with initial context data
$request = (new AiWorkflowItemCollectionRequestTransfer())
    ->setIsTransactional(true)
    ->addAiWorkflowItem(
        (new AiWorkflowItemTransfer())->setContextData([
            'prompt' => 'Analyze this data.',
            'status' => 'initialized',
        ]),
    );

$response = $this->aiFoundationFacade->createAiWorkflowItemCollection($request);
$workflowItem = $response->getAiWorkflowItems()->offsetGet(0);

// 2. Trigger the state machine for the newly created item
$processTransfer = (new StateMachineProcessTransfer())
    ->setProcessName('IntelligentTask01')
    ->setStateMachineName(AiFoundationConstants::AI_WORKFLOW_STATE_MACHINE_NAME);

$this->stateMachineFacade->triggerForNewStateMachineItem($processTransfer, $workflowItem->getIdAiWorkflowItem());

Trigger a manual event:

<?php

use Generated\Shared\Transfer\StateMachineItemTransfer;

$stateMachineItemTransfer = (new StateMachineItemTransfer())
    ->setIdentifier($workflowItem->getIdAiWorkflowItem())
    ->setStateMachineName(AiFoundationConstants::AI_WORKFLOW_STATE_MACHINE_NAME)
    ->setProcessName('IntelligentTask01');

$this->stateMachineFacade->triggerEvent('restart', $stateMachineItemTransfer);

Multi-agent orchestration patterns

There are many possible patterns for multi-agent orchestration. The following are a couple of examples implemented using the Spryker AiWorkflow state machine.

Multi-agent routing workflow

Multi-agent supervision workflow

To enable navigation to the Workflows in the Zed admin panel, add navigation items to your config/Zed/navigation.xml file.

Update config/Zed/navigation.xml to include the Workflows menu:

<config>
    <ai-foundation>
        <label>Intelligence</label>
        <title>Intelligence</title>
        <icon>network_intel_node</icon>
        <pages>
            <ai-workflow>
                <label>Workflows</label>
                <title>Workflows</title>
                <bundle>ai-foundation</bundle>
                <controller>ai-workflow</controller>
                <action>index</action>
            </ai-workflow>
        </pages>
    </ai-foundation>
</config>

This navigation configuration:

Adds an Intelligence menu item in the Zed admin panel
Includes a Workflows submenu to access the workflows monitoring interface
Sets the icon and labels for improved user experience
Defines URLs to route to the workflows overview and detail pages

Monitoring

You can monitor AI workflows in the Spryker Zed administration panel. The monitoring interface provides visibility into workflow execution, state transitions, and context data.

View workflow details

To view detailed information about a specific workflow item, click the View button in the actions column. The detail page displays the following information:

Current State: Shows the workflow item ID, process name, and current state
Context Data: Displays the JSON context data that flows through the workflow, including input data and results from executed commands
State History: A table showing all states the workflow item has passed through and the timestamps when each state was entered
Manual Events: If manual events are available for the current state, you can trigger them directly from the admin panel (useful for testing or recovery scenarios)
Process Graph: A visual representation of the state machine process with the current state highlighted

Trigger manual events

If a workflow is waiting for a manual event or you need to change its course, you can trigger manual events from the workflow detail page. Manual events appear as buttons under the Manual Events section. Only events that are valid for the current state are displayed.

Best practices

Keep context simple: Store only the data that conditions need to evaluate the next step and that subsequent commands need to process
Use structured responses: Convert AI responses to structured data before storing in context
Name explicitly: Use descriptive command and condition names matching the process name
Document context schema: Define what keys each command and condition expects in context data

Use structured responses with the AiFoundation module

Wed, 22 Apr 2026 12:15:12 +0000

This document describes how to use structured responses with the AiFoundation module to receive validated, type-safe data from AI providers in the format of Spryker Transfer objects.

Overview

Structured responses enable AI providers to return data in a predefined schema defined by Spryker Transfer objects. Instead of receiving free-form text, you can request the AI to return data that matches your Transfer object structure, making it easier to integrate AI responses directly into your application workflows and business logic.

The Zed facade handles structured response validation and automatically maps the data to your Transfer object, ensuring type safety and data integrity. The client provides a simple interface to request structured responses, delegating all processing to the Zed backend.

Prerequisites

AiFoundation module installed and configured. For details, see AiFoundation module Overview.
Transfer objects generated with console transfer:generate
Configured AI provider that supports structured responses (OpenAI, Anthropic Claude)

Provider compatibility

Not all AI providers support structured responses. Ensure your configured provider supports this feature. OpenAI and Anthropic Claude have native support for structured outputs.

Use cases

Structured responses are ideal for scenarios where you need predictable, validated data from AI:

Product data extraction

Extract structured product information from unstructured descriptions:

// Request AI to extract product attributes
$productDataTransfer = new ProductDataTransfer();
$response = $this->aiFoundationFacade->prompt(
    (new PromptRequestTransfer())
        ->setPromptMessage(
            (new PromptMessageTransfer())->setContent($rawProductDescription)
        )
        ->setStructuredMessage($productDataTransfer)
);

/** @var \Generated\Shared\Transfer\ProductDataTransfer $extractedData */
$extractedData = $response->getStructuredMessage();
$sku = $extractedData->getSku();
$price = $extractedData->getPrice();

Customer intent classification

Classify customer inquiries into predefined categories:

// Request AI to categorize customer message
$categoryTransfer = new CustomerIntentTransfer();
$response = $this->aiFoundationFacade->prompt(
    (new PromptRequestTransfer())
        ->setPromptMessage(
            (new PromptMessageTransfer())->setContent($customerMessage)
        )
        ->setStructuredMessage($categoryTransfer)
);

/** @var \Generated\Shared\Transfer\CustomerIntentTransfer $intent */
$intent = $response->getStructuredMessage();
$category = $intent->getCategory(); // 'support', 'sales', 'feedback'
$priority = $intent->getPriority(); // 'high', 'medium', 'low'

Content generation with metadata

Generate content with structured metadata:

// Request AI to generate content with SEO metadata
$contentTransfer = new ContentWithMetadataTransfer();
$response = $this->aiFoundationFacade->prompt(
    (new PromptRequestTransfer())
        ->setPromptMessage(
            (new PromptMessageTransfer())->setContent('Write a product description for ' . $productName)
        )
        ->setStructuredMessage($contentTransfer)
);

/** @var \Generated\Shared\Transfer\ContentWithMetadataTransfer $content */
$content = $response->getStructuredMessage();
$description = $content->getDescription();
$keywords = $content->getKeywords(); // array of strings
$metaDescription = $content->getMetaDescription();

Define Transfer objects for structured responses

Define Transfer objects in XML that represent the structure you expect from the AI provider.

Example: Product analysis Transfer

Create a Transfer definition file src/Pyz/Shared/YourModule/Transfer/your_module.transfer.xml:

<?xml version="1.0"?>
<transfers xmlns="spryker:transfer-01"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="spryker:transfer-01 http://static.spryker.com/transfer-01.xsd">

    <transfer name="ProductAnalysis">
        <property name="productName" type="string" description="Name of the product"/>
        <property name="category" type="string" description="Product category"/>
        <property name="price" type="float" description="Estimated price"/>
        <property name="features" type="array" singular="feature" description="List of product features"/>
        <property name="targetAudience" type="string" description="Target customer segment"/>
        <property name="sentiment" type="ProductSentiment" description="Sentiment analysis of product reviews"/>
    </transfer>

    <transfer name="ProductSentiment">
        <property name="score" type="float" description="Sentiment score from -1 to 1"/>
        <property name="label" type="string" description="Sentiment label: positive, neutral, negative"/>
        <property name="confidence" type="float" description="Confidence level of sentiment analysis"/>
    </transfer>

</transfers>

Generate the Transfer classes:

console transfer:generate

This creates ProductAnalysisTransfer and ProductSentimentTransfer classes in src/Generated/Shared/Transfer/.

Request structured responses

Use the PromptRequestTransfer.structuredMessage property to specify the Transfer object schema.

<?php

namespace Pyz\Zed\YourModule\Business\Analyzer;

use Generated\Shared\Transfer\ProductAnalysisTransfer;
use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

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

    public function analyzeProduct(string $productDescription): ProductAnalysisTransfer
    {
        $promptRequest = (new PromptRequestTransfer())
            ->setAiConfigurationName('openai')
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent(
                    sprintf('Analyze this product: %s', $productDescription)
                )
            )
            ->setStructuredMessage(new ProductAnalysisTransfer())
            ->setMaxRetries(2);

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

        if ($promptResponse->getIsSuccessful() !== true) {
            // Handle errors
            $errors = $promptResponse->getErrors();
            throw new AnalysisFailedException('Failed to analyze product');
        }

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

        return $analysis;
    }
}

Handle structured responses

The AI Foundation validates and maps the response to your Transfer object automatically.

Success handling

When PromptResponseTransfer.isSuccessful is true, the structured response is available:

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

if ($promptResponse->getIsSuccessful() === true) {
    /** @var \Generated\Shared\Transfer\ProductAnalysisTransfer $analysis */
    $analysis = $promptResponse->getStructuredMessage();

    // The type matches the Transfer you provided in the request
    // Access properties with full type safety
    $productName = $analysis->getProductName(); // string
    $features = $analysis->getFeatures(); // array
    $sentiment = $analysis->getSentiment(); // ProductSentimentTransfer|null

    // Work with nested Transfer objects
    if ($sentiment !== null) {
        $sentimentScore = $sentiment->getScore(); // float
        $sentimentLabel = $sentiment->getLabel(); // string
    }
}

Retry configuration

Configure retry attempts for improved reliability:

$promptRequest = (new PromptRequestTransfer())
    ->setPromptMessage($message)
    ->setStructuredMessage($transfer)
    ->setMaxRetries(3); // Retry up to 3 times on failure

The facade automatically retries failed requests up to maxRetries times before returning with isSuccessful = false.

Transfer object property types

Structured responses support all Spryker Transfer property types:

Scalar types

<transfer name="Example">
    <property name="stringValue" type="string"/>
    <property name="intValue" type="int"/>
    <property name="floatValue" type="float"/>
    <property name="boolValue" type="bool"/>
</transfer>

Arrays

<transfer name="Example">
    <property name="tags" type="string[]" singular="tag" description="Array of strings"/>
    <property name="metadata" type="array" singular="metadata" description="Associative array"/>
</transfer>

Nested Transfer objects

<transfer name="Order">
    <property name="customer" type="Customer" description="Customer information"/>
    <property name="items" type="OrderItem[]" singular="item" description="Order line items"/>
</transfer>

<transfer name="Customer">
    <property name="name" type="string"/>
    <property name="email" type="string"/>
</transfer>

<transfer name="OrderItem">
    <property name="sku" type="string"/>
    <property name="quantity" type="int"/>
    <property name="price" type="float"/>
</transfer>

Collections

For collections of Transfer objects, use the array notation with []:

<transfer name="AnalysisResult">
    <property name="products" type="ProductData[]" singular="product" description="List of products"/>
</transfer>

<transfer name="ProductData">
    <property name="name" type="string"/>
    <property name="category" type="string"/>
</transfer>

In code, collections are accessed as ArrayObject:

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

foreach ($result->getProducts() as $product) {
    echo $product->getName(); // Each element is ProductDataTransfer
}

Best practices

Design focused Transfer schemas

Create Transfer objects specifically for AI responses rather than reusing business logic Transfers:

<!-- Good: Focused schema for AI -->
<transfer name="ProductExtractionResult">
    <property name="name" type="string"/>
    <property name="category" type="string"/>
    <property name="price" type="float"/>
</transfer>

<!-- Avoid: Complex business Transfer with many optional fields -->
<transfer name="ProductEntity" strict="true">
    <property name="idProduct" type="int"/>
    <property name="fkProductAbstract" type="int"/>
    <!-- ... many other fields ... -->
</transfer>

Provide clear property descriptions

Use descriptions to guide the AI provider:

<transfer name="CustomerIntent">
    <property name="category" type="string" description="Category: support, sales, or feedback"/>
    <property name="priority" type="string" description="Priority level: high, medium, or low"/>
    <property name="requiresHumanReview" type="bool" description="Whether this inquiry requires human review"/>
</transfer>

Validate AI responses

Always check isSuccessful and validate critical data:

if ($promptResponse->getIsSuccessful() !== true) {
    return $this->handleFailure($promptResponse->getErrors());
}

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

// Validate critical fields
if ($analysis->getPrice() === null || $analysis->getPrice() <= 0) {
    throw new InvalidPriceException('AI returned invalid price');
}

Use appropriate retry counts

Configure retries based on request importance:

// Critical business logic: more retries
$promptRequest->setMaxRetries(3);

// Non-critical features: fewer retries
$promptRequest->setMaxRetries(1);

Avoid deeply nested Transfer objects

Prefer flat Transfer structures over deeply nested ones for AI responses. Deeply nested structures increase complexity and make null handling cumbersome.

Limitations

Provider-specific constraints

Different AI providers have varying limitations on structured responses:

Maximum schema complexity
Supported data types
Nesting depth limits
Array size limits

Test with your specific provider to understand constraints.

Performance considerations

Structured responses may have higher latency than regular text responses due to validation overhead. Consider this when implementing real-time features.

Schema evolution

Changes to Transfer schemas may affect AI responses. Test thoroughly when modifying Transfer definitions used in production AI requests.

Use AI tools with the AiFoundation module

Wed, 22 Apr 2026 12:15:12 +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();

        // 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.

Spryker Documentation

OpenTelemetry instrumentation

Test console commands

New Relic transactions grouping by queue names

Install the Configuration Management feature

E2E Testing with Cypress

Cypress boilerplate

Internal Cypress tests

Resources

Architecture

Architecture as Code

Why Architecture as Code

Core Principles

Concepts and Choices

arc42

C4 Model

Mermaid and PlantUML

What Comes Out of the Box

Folder Structure

Diagram Organization and Best Practices

Templates and Guidelines

Getting Help

Resources

Common Questions

AI workflow orchestration with state machines

Overview

Key concepts

Create a workflow process example

1. Define the state machine XML

2. Create command plugins

3. Create condition plugins

4. Register plugins in AiFoundation dependency provider

5. Configure active processes

6. Enable state machine handler

7. Set up cron jobs to process state machine events

8. Trigger a workflow with state machine

Multi-agent orchestration patterns

Multi-agent routing workflow

Multi-agent supervision workflow

Navigation configuration

Add navigation XML

Monitoring

View workflow details

Trigger manual events

Best practices

Use structured responses with the AiFoundation module

Overview

Prerequisites

Use cases

Product data extraction

Customer intent classification

Content generation with metadata

Define Transfer objects for structured responses

Example: Product analysis Transfer

Request structured responses

Handle structured responses

Success handling

Retry configuration

Transfer object property types

Scalar types

Arrays

Nested Transfer objects

Collections

Best practices

Design focused Transfer schemas

Provide clear property descriptions

Validate AI responses

Use appropriate retry counts

Avoid deeply nested Transfer objects

Limitations

Provider-specific constraints

Performance considerations

Schema evolution

Use AI tools with the AiFoundation module

Overview

Prerequisites

Use cases

Data retrieval

Calculations and processing

Business logic execution