feature #585 [Agent][Platform] Add support for native union types and list of polymporphic* types by using DiscriminatorMap (HaKIMus)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Agent][Platform] Add support for native union types and list of polymporphic* types by using `DiscriminatorMap`

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Docs?         | yes <!-- required for new features -->
| Issues        | Fix #559  <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

It's a draft, because, primarily, I want to ask if the DiscriminatorMap approach is ok with you.

**Why the discriminator map usage?**
I've achieved the native `list<Foo|Bar>` union type support for agent json schema output, but Symfony Serializer wasn't working with it correctly (`list<TableDataVisualizationDto|ChartDataVisualizationDto>`), outputting an array in `\Symfony\Component\Serializer\SerializerInterface::deserialize::112`. If you know how to make the serializer work with the "nested" union types correctly, then let me know and we might achieve a native support without the DiscriminatorMap usage.

**Example**
This is an example from my project I want the feature to work on.

Model I tried it with: `gpt-5-nano` with the `Symfony\AI\Platform\Bridge\OpenAi\Gpt`model class.

Prompt:
```
{
    "message": "Provide me with a table representing my latest orders and a chart representing amount of orders for last 10 months."
}
```

Schema produced:
<details>
    <summary>Schema dump</summary>

    ```
     array:2 [
      "type" => "json_schema"
      "json_schema" => array:3 [
        "name" => "ChatStructuredOutput"
        "schema" => array:4 [
          "type" => "object"
          "properties" => array:4 [
            "title" => array:1 [
              "type" => "string"
            ]
            "finalAnswer" => array:1 [
              "type" => "string"
            ]
            "parts" => array:2 [
              "type" => "array"
              "items" => array:1 [
                "anyOf" => array:3 [
                  0 => array:4 [
                    "type" => "object"
                    "properties" => array:6 [
                      "title" => array:1 [
                        "type" => "string"
                      ]
                      "chartType" => array:2 [
                        "type" => "string"
                        "enum" => array:3 [
                          0 => "bar"
                          1 => "line"
                          2 => "pie"
                        ]
                      ]
                      "labels" => array:2 [
                        "type" => "array"
                        "items" => array:1 [
                          "type" => "string"
                        ]
                      ]
                      "datasets" => array:2 [
                        "type" => "array"
                        "items" => array:4 [
                          "type" => "object"
                          "properties" => array:3 [
                            "label" => array:1 [
                              "type" => "string"
                            ]
                            "data" => array:2 [
                              "type" => "array"
                              "items" => array:1 [
                                "type" => "number"
                              ]
                            ]
                            "bgColor" => array:2 [
                              "type" => "string"
                              "description" => "Optional param, default to empty string."
                            ]
                          ]
                          "required" => array:3 [
                            0 => "label"
                            1 => "data"
                            2 => "bgColor"
                          ]
                          "additionalProperties" => false
                        ]
                      ]
                      "options" => array:2 [
                        "type" => "array"
                        "items" => array:1 [
                          "type" => "string"
                        ]
                      ]
                      "type" => array:2 [
                        "type" => "string"
                        "pattern" => "^chart$"
                      ]
                    ]
                    "required" => array:6 [
                      0 => "title"
                      1 => "chartType"
                      2 => "labels"
                      3 => "datasets"
                      4 => "options"
                      5 => "type"
                    ]
                    "additionalProperties" => false
                  ]
                  1 => array:4 [
                    "type" => "object"
                    "properties" => array:4 [
                      "columns" => array:2 [
                        "type" => "array"
                        "items" => array:1 [
                          "type" => "string"
                        ]
                      ]
                      "rows" => array:2 [
                        "type" => "array"
                        "items" => array:2 [
                          "type" => "array"
                          "items" => array:1 [
                            "type" => "string"
                          ]
                        ]
                      ]
                      "meta" => array:2 [
                        "type" => "array"
                        "items" => array:1 [
                          "type" => "string"
                        ]
                      ]
                      "type" => array:2 [
                        "type" => "string"
                        "pattern" => "^table$"
                      ]
                    ]
                    "required" => array:4 [
                      0 => "columns"
                      1 => "rows"
                      2 => "meta"
                      3 => "type"
                    ]
                    "additionalProperties" => false
                  ]
                  2 => array:4 [
                    "type" => "object"
                    "properties" => array:2 [
                      "text" => array:1 [
                        "type" => "string"
                      ]
                      "type" => array:2 [
                        "type" => "string"
                        "pattern" => "^text$"
                      ]
                    ]
                    "required" => array:2 [
                      0 => "text"
                      1 => "type"
                    ]
                    "additionalProperties" => false
                  ]
                ]
              ]
            ]
            "reasoningStep" => array:2 [
              "type" => "array"
              "items" => array:4 [
                "type" => "object"
                "properties" => array:1 [
                  "reasoning" => array:1 [
                    "type" => "string"
                  ]
                ]
                "required" => array:1 [
                  0 => "reasoning"
                ]
                "additionalProperties" => false
              ]
            ]
          ]
          "required" => array:4 [
            0 => "title"
            1 => "finalAnswer"
            2 => "parts"
            3 => "reasoningStep"
          ]
          "additionalProperties" => false
        ]
        "strict" => true
      ]
    ]
    ```
</details>

The description is long enough, so I'd skip the PHP DTOs structure. They look almost identical to the ones I used in tests in the PR.

Output (the data are fake):
<details>
<summary>Output dump</summary>

```
 App\Agent\Application\StructuredOutput\ChatStructuredOutput {#2041
  +title: "Latest orders and orders by month (last 10 months)"
  +finalAnswer: "Here is a table with your latest orders and a bar chart showing the number of orders per month for the last 10 months."
  +parts: array:3 [
    0 =>
App\Agent\Application\StructuredOutput
\
TablePart
 {#1596
      +type: "table"
      +columns: array:5 [
        0 => "Order #"
        1 => "Date Created"
        2 => "Status"
        3 => "Total PLN"
        4 => "Customer Email"
      ]
      +rows: array:10 [
        0 => array:5 [
          0 => "115"
          1 => "2025-09-14 11:46:11"
          2 => "failed"
          3 => "24902.21"
          4 => "N/A"
        ]
        1 => array:5 [
          0 => "117"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "28029.39"
          4 => "[email protected]"
        ]
        2 => array:5 [
          0 => "124"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "28424.05"
          4 => "[email protected]"
        ]
        3 => array:5 [
          0 => "122"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "8692.10"
          4 => "[email protected]"
        ]
        4 => array:5 [
          0 => "121"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "10583.07"
          4 => "[email protected]"
        ]
        5 => array:5 [
          0 => "120"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "14509.36"
          4 => "[email protected]"
        ]
        6 => array:5 [
          0 => "119"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "36850.59"
          4 => "[email protected]"
        ]
        7 => array:5 [
          0 => "116"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "19252.16"
          4 => "[email protected]"
        ]
        8 => array:5 [
          0 => "118"
          1 => "2025-09-14 11:46:11"
          2 => "on-hold"
          3 => "33717.00"
          4 => "N/A"
        ]
        9 => array:5 [
          0 => "123"
          1 => "2025-09-14 11:46:11"
          2 => "completed"
          3 => "33392.61"
          4 => "[email protected]"
        ]
      ]
      +meta: []
    }
    1 =>
App\Agent\Application\StructuredOutput
\
ChartPart
 {#2100
      +type: "chart"
      +title: "Orders in the last 10 months"
      +chartType:
App\Agent\Application\StructuredOutput
\
ChartPartType
 {#1107
        +name: "BAR"
        +value: "bar"
      }
      +labels: array:10 [
        0 => "Dec 2024"
        1 => "Jan 2025"
        2 => "Feb 2025"
        3 => "Mar 2025"
        4 => "Apr 2025"
        5 => "May 2025"
        6 => "Jun 2025"
        7 => "Jul 2025"
        8 => "Aug 2025"
        9 => "Sep 2025"
      ]
      +datasets: array:1 [
        0 =>
App\Agent\Application\StructuredOutput
\
DatasetPart
 {#2079
          +label: "Number of orders"
          +data: array:10 [
            0 => 0
            1 => 0
            2 => 0
            3 => 0
            4 => 0
            5 => 0
            6 => 0
            7 => 0
            8 => 0
            9 => 85
          ]
          +bgColor: "#4e79a7"
        }
      ]
      +options: array:2 [
        0 => "responsive"
        1 => "scales: {y: {beginAtZero: true}}"
      ]
    }
    2 =>
App\Agent\Application\StructuredOutput
\
TextPart
 {#2120
      +type: "text"
      +text: "Note: The chart shows order counts per month for the last 10 months. In this dataset, only Sep 2025 contains orders (85 orders)."
    }
  ]
  +reasoningStep: array:2 [
    0 =>
App\Agent\Application\StructuredOutput
\
ReasoningStep
 {#2069
      +reasoning: "I retrieved the latest orders using the WooCommerce orders endpoint and prepared a compact table with key fields: Order #, Date Created, Status, Total PLN, and Customer Email. Since the dataset appears to be current (all entries dated 2025-09-14), I listed the ten most recent orders as they appear from the data source."
    }
    1 =>
App\Agent\Application\StructuredOutput
\
ReasoningStep
 {#2148
      +reasoning: "For the chart, I computed a 10-month window ending in Sep 2025. Based on the provided data, all orders fall in Sep 2025, so Sep 2025 has 85 orders and the preceding months have 0 orders. This yields a bar chart with a single non-zero bar for Sep 2025. If you’d like a different window (e.g., moving 10 months from a different start date) I can adjust the chart accordingly."
    }
  ]
}
```
</details>
As you can see all data have been correctly mapped from schema to php objects.
<!--
Replace this notice by a description of your feature/bugfix.
This will help reviewers and should be a good start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - For new features, provide some code snippets to help understand usage.
 - Features and deprecations must be submitted against branch main.
 - Update/add documentation as required (we can help!)
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
 - Never break backward compatibility (see https://symfony.com/bc).
-->

Commits
-------

36f5bb4 [Agent][Platform] Add support for native union types and list of polymporphic* types by using `DiscriminatorMap`

Author: OskarStark

examples/openai/structured-output-list-of-polymorphic-items.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Agent\Agent;
+use Symfony\AI\Agent\StructuredOutput\AgentProcessor;
+use Symfony\AI\Fixtures\StructuredOutput\PolymorphicType\ListOfPolymorphicTypesDto;
+use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+$model = new Gpt(Gpt::GPT_4O_MINI);
+
+$processor = new AgentProcessor();
+$agent = new Agent($platform, $model, [$processor], [$processor], logger: logger());
+$messages = new MessageBag(
+    Message::forSystem('You are a persona data collector! Return all the data you can gather from the user input.'),
+    Message::ofUser('Hi! My name is John Doe, I am 30 years old and I live in Paris.'),
+);
+$result = $agent->call($messages, ['output_structure' => ListOfPolymorphicTypesDto::class]);
+
+dump($result->getContent());

examples/openai/structured-output-union-types.php

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Agent\Agent;
+use Symfony\AI\Agent\StructuredOutput\AgentProcessor;
+use Symfony\AI\Fixtures\StructuredOutput\UnionType\UnionTypeDto;
+use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
+$model = new Gpt(Gpt::GPT_4O_MINI);
+
+$processor = new AgentProcessor();
+$agent = new Agent($platform, $model, [$processor], [$processor], logger: logger());
+$messages = new MessageBag(
+    Message::forSystem(<<<PROMPT
+        You are a time assistant! You can provide time either as a unix timestamp or as a human readable time format.
+        If you don't know the time, return null.
+    PROMPT),
+    Message::ofUser('What is the current time?'),
+);
+$result = $agent->call($messages, ['output_structure' => UnionTypeDto::class]);
+
+dump($result->getContent());

fixtures/StructuredOutput/PolymorphicType/ListItemAge.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\PolymorphicType;
+
+use Symfony\AI\Platform\Contract\JsonSchema\Attribute\With;
+
+final class ListItemAge implements ListItemDiscriminator
+{
+    public function __construct(
+        public int $age,
+        #[With(pattern: '^age$')]
+        public string $type = 'age',
+    ) {
+    }
+}

fixtures/StructuredOutput/PolymorphicType/ListItemDiscriminator.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\PolymorphicType;
+
+use Symfony\Component\Serializer\Attribute\DiscriminatorMap;
+
+#[DiscriminatorMap(
+    typeProperty: 'type',
+    mapping: [
+        'name' => ListItemName::class,
+        'age' => ListItemAge::class,
+    ]
+)]
+/**
+ * @property string $type
+ *
+ * With the PHP 8.4^ you can replace the property annotation with a property hook:
+ * public string $type {
+ *     get;
+ * }
+ */
+interface ListItemDiscriminator
+{
+}

fixtures/StructuredOutput/PolymorphicType/ListItemName.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\PolymorphicType;
+
+use Symfony\AI\Platform\Contract\JsonSchema\Attribute\With;
+
+class ListItemName implements ListItemDiscriminator
+{
+    public function __construct(
+        public string $name,
+        #[With(pattern: '^name$')]
+        public string $type = 'name',
+    ) {
+    }
+}

fixtures/StructuredOutput/PolymorphicType/ListOfPolymorphicTypesDto.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\PolymorphicType;
+
+/**
+ * Useful when you need to tell an agent that any of the items are acceptable types.
+ * Real life example could be a list of possible analytical data visualization like charts or tables.
+ */
+final class ListOfPolymorphicTypesDto
+{
+    /**
+     * @param list<ListItemDiscriminator> $items
+     */
+    public function __construct(public array $items)
+    {
+    }
+}

fixtures/StructuredOutput/UnionType/HumanReadableTimeUnion.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\UnionType;
+
+final class HumanReadableTimeUnion
+{
+    public function __construct(public string $readableTime)
+    {
+    }
+}

fixtures/StructuredOutput/UnionType/UnionTypeDto.php

@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\UnionType;
+
+final class UnionTypeDto
+{
+    public function __construct(
+        public UnixTimestampUnion|HumanReadableTimeUnion|null $time,
+    ) {
+    }
+}

fixtures/StructuredOutput/UnionType/UnixTimestampUnion.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Fixtures\StructuredOutput\UnionType;
+
+final class UnixTimestampUnion
+{
+    public function __construct(public int $timestamp)
+    {
+    }
+}

src/agent/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 0.1
 ---
 
+ * Add support for union types and polymorphic types via DiscriminatorMap
  * Add Agent class as central orchestrator for AI interactions through the Platform component
  * Add input/output processing pipeline:
    - `InputProcessorInterface` for pre-processing messages and options