Agentic AI Topology and Internals

Quarkus Flow provides deep, native integration with the LangChain4j Agentic Workflow API through two complementary approaches:

  • Build-time compilation of @SequenceAgent, @ParallelAgent, @LoopAgent, and @ConditionalAgent annotations

  • Runtime workflow creation via FlowAgentsBuilderService for dynamic UntypedAgent workflows

This page explains the internal architecture of that integration: how Quarkus Flow compiles these external annotations into standard workflows, and how the engine bridges the gap between AI memory and workflow state.

For practical instructions on building these workflows, see Orchestrate LangChain4j Agents and Patterns.

1. The Build-Time Compiler

When you add the quarkus-flow-langchain4j extension to your project, Quarkus Flow acts as an Ahead-of-Time (AoT) compiler for your AI patterns.

It does not run a separate "AI Engine" at runtime. Instead, during the Quarkus build phase, it translates LangChain4j semantics directly into the CNCF Serverless Workflow vocabulary.

The Compilation Process

  1. Scanning: The extension scans your @RegisterAiService interfaces for methods annotated with Agentic routing annotations (like @SequenceAgent or @ParallelAgent).

  2. Translation: For each annotated method, it programmatically generates a standard WorkflowDefinition bean.

    • A @SequenceAgent is translated into a linear sequence of standard call tasks.

    • A @ParallelAgent is translated into a fork / join state topology.

  3. Registration: These generated definitions are injected into the Workflow Registry.

Because of this build-time translation, the generated AI workflows benefit from the exact same runtime execution speeds, tracing, and Dev UI visualizers as a workflow you wrote manually using the Java DSL.

2. The Runtime Workflow Factory

While build-time compilation provides optimal performance for known AI patterns, some use cases require creating workflows dynamically at runtime:

  • Multi-tenant applications where each customer has custom workflow logic

  • Workflow editors or no-code platforms

  • A/B testing different agent orchestration strategies

  • Temporary, ephemeral workflows created on-demand

The FlowAgentsBuilderService

FlowAgentsBuilderService is a CDI-managed bean that provides factory methods for creating LangChain4j workflows programmatically:

@Inject
FlowAgentsBuilderService builderService;

UntypedAgent workflow = builderService.newSequential()
    .subAgents(agent1, agent2, agent3)
    .build();

Each builder method (newSequential(), newParallel(), newLoop(), newConditional()) creates a Runtime*AgenticFlow instance that:

  1. Collects workflow metadata as you call builder methods (.subAgents(), .exitCondition(), etc.)

  2. Generates a WorkflowDefinition when .build() is called

  3. Creates a fresh WorkflowApplication instance with isolated workflow definition cache

  4. Returns a proxy UntypedAgent that delegates to the generated workflow

This approach mirrors LangChain4j’s own runtime builder API while generating standard CNCF Serverless Workflow definitions under the hood.

Isolation and State Management

Unlike build-time workflows (which share a global WorkflowApplication), runtime workflows receive a new WorkflowApplication instance on each build. This ensures:

  • Cache isolation: Each runtime workflow has its own workflow definition cache

  • No conflicts: Multiple tests or concurrent workflow creations don’t interfere

  • Clean state: No residual data from previous workflow executions

The isolation is achieved through RuntimeWorkflowApplicationProvider, which creates a new WorkflowApplication instance per call instead of caching a singleton.

3. The Memory Bridge (AgenticScope vs. Workflow Context)

The biggest architectural challenge when integrating an external AI framework with a workflow engine is state management.

  • LangChain4j relies on an AgenticScope object to hold input parameters, intermediate LLM generations, and conversation history.

  • Quarkus Flow relies on a structured JSON document (the Global Context) that is passed between tasks.

How the Bridge Works

To prevent data duplication and ensure state consistency, Quarkus Flow implements an AgenticScope-aware workflow data model.

When a generated AI workflow executes:

  1. The engine intercepts the underlying AgenticScope created by LangChain4j.

  2. It dynamically maps the AgenticScope.state() directly to the Workflow Data Context.

  3. The Result: This means that standard tasks (and jq expressions) can seamlessly read and write variables directly into the AI’s memory scope, and the AI agents can read data injected by standard HTTP or Messaging tasks, all without manual data marshaling.

4. Runtime Execution Semantics

When a generated AI workflow is triggered (either via the Dev UI or by an incoming event), Quarkus Flow must preserve the specific execution semantics required by LangChain4j (such as triggering specific output mappers or respecting AgenticScope lifecycles).

To achieve this, Quarkus Flow uses a Bean Invoker strategy. Instead of evaluating the compiled WorkflowDefinition natively from scratch, the engine executes the workflow through the CDI proxy of the annotated agentic interface method.

This ensures that LangChain4j remains the ultimate authority on how the prompt is formed and how the LLM is called, while Quarkus Flow remains the authority on observability, retries, and task transitions.

See also