[Agent] Add AgentWorkflow

[Guikingone]

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	Inspired by #155 - Part of #1301
License	MIT

This PR introduces a workflow system for orchestrating multi-step agent pipelines, built on top of the
Symfony Workflow component for place/transition logic.

Agent component (src/agent/)

Orchestration — AgentWorkflow implements AgentWorkflowInterface with two entry points: run() (execution
from an initial state) and resume() (resumption from a persisted state). At each workflow place, an
ExecutorInterface is executed, then a TransitionResolverInterface determines the next transition (or
terminates the workflow).

Executors — Three implementations provided:

• AgentExecutor: delegates execution to an existing AgentInterface (configurable prompt per place,
  read/write keys from/to state)
• ProcessExecutor: runs a symfony/process (static command or closure)
• FiberExecutor: executes a closure inside a Fiber

State — WorkflowState is a mutable bag carrying data, current place, completed places, and an optional
_next_transition hint. WorkflowStateStoreInterface handles persistence with 4 implementations: InMemory,
Cache (psr/cache), Filesystem, Redis.

Guards & Transition resolver — GuardInterface enables pre-execution checks per place.
StateBasedTransitionResolver reads _next_transition from the state or automatically selects the single
available transition.

Dedicated exceptions: WorkflowExecutorException, WorkflowGuardException, TransitionResolutionException,
WorkflowStateNotFoundException.

AI Bundle (src/ai-bundle/)

Configuration — New workflow section in the bundle config. Each workflow references an existing Symfony
Workflow (defined in config/packages/workflow.yaml) and maps executors to places. Supports stores
(memory/cache/filesystem/redis/service), guards per place, and a custom transition resolver.

Profiler — TraceableAgentWorkflow and TraceableWorkflowStateStore trace run/resume/save/load/etc. calls.
The DataCollector and DebugCompilerPass integrate this data into the Symfony debug toolbar.

Documentation & examples

• RST documentation in docs/bundles/ai-bundle.rst (configuration, executors, stores, guards, profiler)
• RST documentation in docs/components/agent.rst (standalone usage)
• 4 examples: linear, linear-with-cache, conditional-branching, process-executor

Tests

64 tests for the Agent component (workflow), covering AgentWorkflow, all 3 executors, the transition
resolver, state, normalizer, and all 4 stores. On the bundle side: configuration tests, compiler pass,
profiler/data collector.

[94noni]

small comment passing by :)

workflow component is very powerful so this on top I think could be a valuable addition in the tooling chain of ai/agent 👍🏻

[Guikingone]

@94noni If you have time, I pushed a rework of the PR, I resolved your previous comments as most of them were obsolete due to recent changes, I let you review it when you have time 🙂

[chr-hertel]

Hi! Version 0.7 has been released. This PR has changelog/upgrade entries under the 0.7 heading, which is now a released version.

Please update the following files to place your entries under the next version 0.8:

• src/agent/CHANGELOG.md
• src/ai-bundle/CHANGELOG.md

For CHANGELOG.md files: change the version heading from 0.7 to 0.8
For UPGRADE.md: place entries under UPGRADE FROM 0.7 to 0.8

Thank you!

---

_{🤖 This comment was generated automatically by an agent.}