Agentic workflows with LangChain4j and Quarkus Flow

Quarkus Flow integrates deeply with the LangChain4j Agentic Workflow API so you can describe agentic patterns (sequence, parallel, nested workflows, and more) using annotations and let Quarkus Flow execute them as first-class workflows.

This page explains the architecture of that integration and how it complements the Quarkus Flow DSL.

1. What is the LangChain4j Agentic Workflow API?

LangChain4j provides an “agentic” module that models agents and their workflows in a declarative way:

@Agent – defines a single autonomous agent method.
@SequenceAgent – chains multiple sub-agents, passing results along.
@ParallelAgent – runs multiple sub-agents concurrently and joins their outputs.
Other patterns (for example conditional or nested workflows) build on top of these.

In Quarkus, these APIs are exposed via the quarkus-langchain4j-agentic extension. You usually combine them with @RegisterAiService so the framework can create beans for your agents.

2. Where Quarkus Flow fits

Quarkus Flow is a workflow engine and Dev UI powered by the CNCF Workflow Specification. It lets you define workflows using:

YAML/JSON workflow definitions.
The Quarkus Flow Java DSL (for example Flow, CallHTTP, Listen, etc.).
LangChain4j tasks (agent(…) / function(…)) as described in Orchestrate LangChain4j agents with the Quarkus Flow Java DSL.

The quarkus-flow-langchain4j module also supports a fourth option:

Detect LangChain4j agentic workflows (@SequenceAgent, @ParallelAgent, …).
Automatically build WorkflowDefinition instances that mirror those agentic patterns.
Register them in the Workflow Registry so they appear alongside your other workflows in the Quarkus Flow Dev UI.

3. From agentic annotations to WorkflowDefinition

At build time, the quarkus-flow-langchain4j extension:

Scans @RegisterAiService interfaces for methods annotated with the Agentic Workflow API annotations (@SequenceAgent, @ParallelAgent, …).
For each such method, computes a WorkflowDefinitionId (namespace, name, version) derived from the agent interface.
Uses the Quarkus Flow Java DSL internally to construct a WorkflowDefinition whose structure encodes the agentic pattern:
- A @SequenceAgent becomes a linear chain of tasks that call the sub-agents.
- A @ParallelAgent becomes a fork-join structure with one branch per sub-agent.
Wires each sub-agent call as a function task that calls the underlying LC4J agent via the existing Quarkus LangChain4j integration.

4. AgenticScope and data model

LangChain4j workflows use an AgenticScope object to hold both input parameters and intermediate results shared between agents. Quarkus Flow needs to understand this model to provide a good experience.

The integration provides an AgenticScope-aware workflow model:

When a workflow originates from an agentic method, Quarkus Flow uses a model implementation that:
- Exposes the AgenticScope.state() as the workflow data map.
- Allows tasks to read/write scope variables via normal workflow data access.
- Keeps the underlying AgenticScope object as the “raw” Java object for use by LangChain4j’s output mappers.

5. Execution model and Dev UI

When you launch a workflow from the Quarkus Flow Dev UI, the engine decides how to execute it:

If the workflow has an associated bean invoker (for example, an agentic interface method), the Dev UI will execute the workflow through that bean to preserve the LangChain4j semantics (agent proxies, AgenticScope, output mappers, etc.).
Otherwise, the engine runs the workflow definition directly with whatever input you provide.

6. When to use which approach

You can choose between:

Java DSL tasks (agent/function) — best when you want full control over workflow structure and to mix AI with non-AI tasks.
Annotations → generated workflows — best when you already use LangChain4j Agentic annotations and want those workflows to appear in Quarkus Flow with Dev UI, schemas, diagrams, traces, and robustness.
Hybrid — best when you want the annotation-defined agentic pattern, but also need a bigger business process around it (HTTP, messaging, timers, approvals, long-running instances). In this model, you call the annotated workflow from a Java DSL workflow via function(…).
Pure Quarkus LangChain4j agentic (no Flow) — best when you only need agentic control flow within a single request/response, and you do not care about workflow-level tracing or Dev UI.