[Agent][RFC] Add a graph-based AI workflow engine (LangGraph-style) to Symfony/ai

[emreakay]

Hi,

Building anything more complex than a single prompt/response quickly becomes hard.

Developers need to:
chain multiple LLM calls and tool calls,
branch or loop based on llm results,
resume long-running tasks after a crash,
inject human approval at steps

The Python ecosystem already has LangGraph, which tackles these points.

If the core team is open to the idea
Feedback welcome!

Thanks for considering

[chr-hertel]

Hi @emreakay, that is indeed really interesting and support on the Agent component is super welcome!

Do you have a concrete example in mind that you like with langgraph (or a bunch) that we can use to align on interfaces and classes first? Or do you just want to create a POC PR?

[emreakay]

Hi @chr-hertel,

I’ve already created a graph‑style (graph) conversational agent with the prism-php/prism package and would be delighted to help align interfaces with LangGraph.

⚙️ Key building blocks

Component	Purpose
Flow	Orchestrates execution, deciding which step runs next.
Memory	Persists conversation context (messages + the next step to resume from).
State	Immutable snapshot of the current turn.
Step	A single node in the graph; returns either another Step or a Result.
Result	Terminates the flow or yields the final message to the user.

📄 Minimal proof of concept

class ExampleStep1 implements Step
{
    private ?string $stopMessage = null;

    public function getSupportedState(): string
    {
        return ChatState::class;
    }

    public function run(State $state): Step|Result
    {
        $schema = new ObjectSchema(
            name: 'sentiment',
            description: 'Sentiment analysis',
            properties: [
                new EnumSchema('mood', 'user mood', ['happy', 'angry']),
            ],
            requiredFields: ['mood']
        );

        $response = Prism::structured()
            ->using(Provider::OpenAI, 'gpt‑4o')
            ->withSchema($schema)
            ->withMessages($state->getMessages())
            ->withSystemPrompt(
                'You are a sentiment analyst; segment the user’s sentence accordingly.'
            )
            ->asStructured();

        $state->addMessages($response->responseMessages);

        return match ($response->structured['mood'] ?? null) {
            'happy' => new ExampleStep2($this),
            'angry' => new ExampleStep1a($this),
            default  => $this->stop('Sorry, I’m unable to detect the mood.')
        };
    }

    /* …requiresHumanInteraction(), stop(), etc. … */
}

class ChatFlow implements Flow
{
    public function __construct(
        private Step $nextStep,
        private readonly ChatState $state
    ) {}

    public function run(): Result
    {
        // Restore unfinished step from memory
        if ($stored = $this->state->getChatMemory()->getNextStep()) {
            $this->nextStep = new $stored();
        }

        $step = $this->nextStep;
        do {
            $step   = $step->run($this->state);
            $resume = $step instanceof Step ? $step::class : null;
            $this->state->getChatMemory()->storeNextStep($resume);
        } while ($step instanceof Step && !$step->requiresHumanInteraction());

        return $step instanceof Result
            ? $step
            : new ChatResult($step->requiresHumanInteraction());
    }
}

[chr-hertel]

Thanks for that snippet - that really gets me thinking.

Two things that catched my eyes

1. You write that the Flow decides which next step to run, but than the Step has that match statement
2. how does that getSupportedState matter? at least in that short example it's not used

---

I understand the Flow as outer loop, as high level service that we in user land in the end call. It provides the input and manages interaction.

The Step is one isolated and custom operation, that creates a result.

I'm missing the middle layer between the outer loop and the single steps, that takes the decisions. has some kind of rule engine - like that match statement you provided as part of the step. I'd say from a design point of view, it's another player here.

---

The agent component could provide the infrastructure for Steps, e.g. interface/contract, and a way to standardize those rules. And on top, I would assume we provide the Flow loop as well. library users implement steps and rules.

Makes sense?