feature #1125 [Platform] Decouple Platform Token Usage handling from Agent by introducing new interface (chr-hertel)

This PR was merged into the main branch.

Discussion
----------

[Platform] Decouple Platform Token Usage handling from Agent by introducing new interface

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         | no
| Issues        |
| License       | MIT

- [x] adopt bundle: remove config
- [x] adopt tests in platform

Mistral is more or less flaky anyways
<img width="1527" height="902" alt="image" src="https://github.com/user-attachments/assets/27141fb4-ff57-4b94-a42c-b825573a91d8" />

Commits
-------

286acc5 Decouple Platform Token Usage handling from Agent by introducing new interface

Author: chr-hertel

deptrac.yaml

@@ -473,11 +473,4 @@ deptrac:
       - PlatformComponent
   # Baseline of known violations to be skipped for now
   skip_violations:
-    Symfony\AI\Platform\Bridge\Anthropic\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
-    Symfony\AI\Platform\Bridge\DeepSeek\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
-    Symfony\AI\Platform\Bridge\Gemini\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
-    Symfony\AI\Platform\Bridge\Mistral\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
-    Symfony\AI\Platform\Bridge\OpenAi\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
     Symfony\AI\Platform\Bridge\Perplexity\SearchResultProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
-    Symfony\AI\Platform\Bridge\Perplexity\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]
-    Symfony\AI\Platform\Bridge\VertexAi\TokenOutputProcessor: [Symfony\AI\Agent\OutputProcessorInterface, Symfony\AI\Agent\Output]

docs/bundles/ai-bundle.rst

@@ -67,7 +67,6 @@ Advanced Example with Multiple Agents
         agent:
             rag:
                 platform: 'ai.platform.azure.gpt_deployment'
-                track_token_usage: true # Enable tracking of token usage for the agent, default is true
                 model: 'gpt-4o-mini'
                 memory: 'You have access to conversation history and user preferences' # Optional: static memory content
                 prompt: # The system prompt configuration
@@ -899,8 +898,8 @@ Token Usage Tracking
 Token usage tracking is a feature provided by some of the Platform's bridges, for monitoring and analyzing the
 consumption of tokens by your agents. This feature is particularly useful for understanding costs and performance.
 
-When enabled, the agent will automatically track token usage information and add it
-to the result metadata. The tracked information includes:
+In case a Platform bridge supports token usage tracking, the Platform will automatically track token usage information
+and add it to the result metadata. The tracked information includes:
 
 * **Prompt tokens**: Number of tokens used in the input/prompt
 * **Completion tokens**: Number of tokens generated in the response
@@ -932,19 +931,6 @@ The token usage information can be accessed from the result metadata::
         }
     }
 
-Disable Tracking
-~~~~~~~~~~~~~~~~
-
-To disable token usage tracking for an agent, set the ``track_token_usage`` option to ``false``:
-
-.. code-block:: yaml
-
-    ai:
-        agent:
-            my_agent:
-                model: 'gpt-4o-mini'
-                track_token_usage: false
-
 Vectorizers
 -----------
 

examples/anthropic/token-metadata.php

@@ -11,15 +11,14 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\Anthropic\PlatformFactory;
-use Symfony\AI\Platform\Bridge\Anthropic\TokenOutputProcessor;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('ANTHROPIC_API_KEY'), http_client());
 
-$agent = new Agent($platform, 'claude-sonnet-4-5-20250929', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'claude-sonnet-4-5-20250929');
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),

examples/bootstrap.php

@@ -14,8 +14,8 @@
 use Symfony\AI\Agent\Exception\ExceptionInterface as AgentException;
 use Symfony\AI\Platform\Exception\ExceptionInterface as PlatformException;
 use Symfony\AI\Platform\Metadata\Metadata;
-use Symfony\AI\Platform\Metadata\TokenUsage;
 use Symfony\AI\Platform\Result\DeferredResult;
+use Symfony\AI\Platform\TokenUsage\TokenUsage;
 use Symfony\AI\Store\Exception\ExceptionInterface as StoreException;
 use Symfony\Component\Console\Helper\Table;
 use Symfony\Component\Console\Logger\ConsoleLogger;

examples/deepseek/token-metadata.php

@@ -11,15 +11,14 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\DeepSeek\PlatformFactory;
-use Symfony\AI\Platform\Bridge\DeepSeek\TokenOutputProcessor;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('DEEPSEEK_API_KEY'), http_client());
 
-$agent = new Agent($platform, 'deepseek-chat', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'deepseek-chat');
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),

examples/gemini/token-metadata.php

@@ -11,15 +11,14 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\Gemini\PlatformFactory;
-use Symfony\AI\Platform\Bridge\Gemini\TokenOutputProcessor;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('GEMINI_API_KEY'), http_client());
 
-$agent = new Agent($platform, 'gemini-2.0-flash', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'gemini-2.0-flash');
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),

examples/mistral/token-metadata.php

@@ -11,15 +11,14 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\Mistral\PlatformFactory;
-use Symfony\AI\Platform\Bridge\Mistral\TokenOutputProcessor;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('MISTRAL_API_KEY'), http_client());
 
-$agent = new Agent($platform, 'mistral-large-latest', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'mistral-large-latest');
 
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),

examples/openai/token-metadata.php

@@ -11,15 +11,14 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
-use Symfony\AI\Platform\Bridge\OpenAi\TokenOutputProcessor;
 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());
 
-$agent = new Agent($platform, 'gpt-4o-mini', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'gpt-4o-mini');
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),

examples/perplexity/token-metadata.php

@@ -11,14 +11,13 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\Perplexity\PlatformFactory;
-use Symfony\AI\Platform\Bridge\Perplexity\TokenOutputProcessor;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('PERPLEXITY_API_KEY'), http_client());
-$agent = new Agent($platform, 'sonar', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'sonar');
 
 $messages = new MessageBag(
     Message::forSystem('You are a pirate and you write funny.'),

examples/vertexai/token-metadata.php

@@ -11,15 +11,14 @@
 
 use Symfony\AI\Agent\Agent;
 use Symfony\AI\Platform\Bridge\VertexAi\PlatformFactory;
-use Symfony\AI\Platform\Bridge\VertexAi\TokenOutputProcessor;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Message\MessageBag;
 
 require_once __DIR__.'/bootstrap.php';
 
 $platform = PlatformFactory::create(env('GOOGLE_CLOUD_LOCATION'), env('GOOGLE_CLOUD_PROJECT'), adc_aware_http_client());
 
-$agent = new Agent($platform, 'gemini-2.0-flash-lite', outputProcessors: [new TokenOutputProcessor()]);
+$agent = new Agent($platform, 'gemini-2.0-flash-lite');
 $messages = new MessageBag(
     Message::forSystem('You are an expert assistant in animal study.'),
     Message::ofUser('What does a cat usually eat?'),