Skip to main content
v2

New Consumer Onboarding

This is the current onboarding path for teams integrating ConvEngine on the active v2 release line.

The older onboarding page was written around the original 2.0.0 launch assumptions. The framework has moved on. The current line includes:

  • CorrectionStep
  • ce_mcp_planner
  • ce_verbose
  • extra rule phases (POST_SCHEMA_EXTRACTION, PRE_AGENT_MCP, POST_DIALOGUE_ACT)
  • richer MCP metadata
  • shared Thymeleaf prompt rendering

So a modern integration should be set up with those capabilities in mind from day one.

Start with the right baseline​

Day-0 decisions

DecisionWhy it mattersRecommended default
Java baselineConvEngine compiles against Java 21.Standardize on Java 21 in all environments.
Conversation concurrencyThe framework does not enforce optimistic locking for `ce_conversation`.Allow only one active turn per `conversationId`.
TransportStreaming is optional but changes operational setup.Start with SSE only; enable STOMP later if you truly need it.
Prompt contract disciplineCurrent v2 uses prompts for both text generation and turn behavior metadata.Treat `ce_prompt_template` as a runtime contract, not just copy.
MCP adoptionThe current MCP model is powerful, but it adds scope, planner, and tool-governance responsibilities.Start with one narrow intent-scoped tool flow before scaling out.

Dependency version​

Use the current framework version from the repo:

  • convengine:2.0.9

1. Add the framework dependency​

Maven dependency
XML
<dependency>
<groupId>com.github.salilvnair</groupId>
<artifactId>convengine</artifactId>
<version>2.0.9</version>
</dependency>

2. Enable the framework in your Spring Boot app​

The minimal production-friendly baseline is:

  • @EnableConvEngine
  • @EnableConvEngineCaching
  • @EnableConvEngineAsyncConversation

Add async audit dispatch only if your deployment needs it.

Application bootstrap
JAVA
@SpringBootApplication
@EnableConvEngine(stream = true)
@EnableConvEngineCaching
@EnableConvEngineAsyncConversation
public class DemoApplication {
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}

3. Provide required consumer-side beans​

You still need consumer-owned infrastructure:

  • one production-grade LlmClient bean
  • datasource + JPA configuration
  • your own tool handlers / task executors / transformers when you use those features

LLM adapter expectations​

Your LlmClient should be treated as production infrastructure, not demo glue code:

  • define strict timeout policy
  • define retry policy appropriate to your provider
  • log failures in a trace-friendly way
  • make request identity and conversation correlation observable

4. Apply the framework schema​

Before you test any conversation flow, create the ce_* tables from the current DDL for your dialect.

At minimum, new consumers usually need these control-plane areas seeded:

  • ce_intent
  • ce_intent_classifier
  • ce_output_schema
  • ce_prompt_template
  • ce_response
  • ce_rule

Use these only when the feature is actually in scope:

  • ce_pending_action
  • ce_mcp_tool
  • ce_mcp_planner
  • ce_verbose
  • ce_container_config
  • ce_policy

5. Seed one complete vertical slice first​

Do not try to model your entire product on day one.

Build one narrow, fully testable path:

  • one intent
  • one or two states
  • one response path
  • one optional schema
  • zero or one tool

That first slice should prove:

  • intent resolves correctly
  • state transitions are deterministic
  • a final response always exists
  • audit/trace output is understandable

6. Treat prompt templates as behavior contracts​

This is one of the biggest differences in the current v2 line.

ce_prompt_template is no longer just prompt text. In 2.0.9+, prompt rows also document how a state is expected to behave.

Relevant metadata:

  • interaction_mode
  • interaction_contract

Recommended contract patterns:

  • collection state:
    • interaction_mode=COLLECT
    • interaction_contract={"expects":["structured_input"]}
  • confirmation state:
    • interaction_mode=CONFIRM
    • interaction_contract={"allows":["affirm","edit","reset"]}
  • in-flight processing state:
    • interaction_mode=PROCESSING
    • interaction_contract={"allows":["retry","reset"]}
  • final state:
    • interaction_mode=FINAL

This is what allows CorrectionStep to safely do in-place confirm/edit/retry routing.

7. Start with a safe configuration baseline​

Recommended starter config
YAML

8. If you adopt MCP, start narrow​

Current MCP is much stronger than earlier docs implied:

  • ce_mcp_tool uses mandatory scoped intent_code and state_code
  • ce_mcp_planner selects prompts by scoped fallback order
  • PRE_AGENT_MCP and POST_AGENT_MCP can drive rule-based branching
  • context.mcp.lifecycle.* and context.mcp.toolExecution.* expose deterministic state for rule matching

Good first MCP rollout:

  • one tool
  • one intent
  • exact scope, not ANY
  • one planner row plus one fallback row
  • one explicit ce_response path for success and one for failure/fallback

Bad first MCP rollout:

  • many ANY-scoped tools
  • no response coverage
  • no rule inspection of lifecycle outcomes
  • no handler-level business authorization

9. Use ce_verbose early​

Modern onboarding should include ce_verbose, not just raw audit inspection.

Why:

  • it gives clearer runtime progress for UI and QA
  • it exposes skipped/error/step transitions more readably
  • it turns invisible config mistakes into visible operator signals

Even a small first rollout should seed a handful of verbose rows for:

  • STEP_ENTER
  • STEP_ERROR
  • INTENT_RESOLVED
  • SCHEMA_STATUS
  • RESOLVE_RESPONSE_SELECTED
  • MCP_TOOL_CALL / MCP_TOOL_ERROR if you use MCP

10. Validate with a real pre-production checklist​

Minimum readiness checklist

AreaMust prove before rolloutCommon failure if skipped
Single-turn deterministic pathOne happy-path intent works end-to-end from `/message` to final payload.Basic config is incomplete or inconsistent.
Multi-turn slot collectionMissing fields converge cleanly and stop asking once complete.Infinite or unstable clarification loops.
Confirmation / correction routing`AFFIRM`, `EDIT`, and `retry` do what the active prompt contract says.Unexpected reclassification or incorrect in-place continuation.
State coverageEvery reachable state has a valid response strategy.Fallback or misleading output in production.
Concurrency guardParallel same-ID requests do not corrupt state.Last-write-wins drift.
Trace usabilityYour team can read audit + trace and explain a bad turn quickly.Slow incident resolution.
1

Wire framework and LLM

Add the 2.0.9 dependency, enable ConvEngine, and provide a production-grade LlmClient.

2

Apply schema and seed one narrow flow

Create the ce_* tables and seed one intent with one clean end-to-end conversation path.

3

Enable traceability

Turn on audit, inspect /api/v1/conversation/audit/{conversationId} and /api/v1/conversation/audit/{conversationId}/trace, and seed a minimal ce_verbose layer.

4

Exercise correction and failure paths

Test missing fields, user edits, retries, guardrail skips, and no-response edge cases.

5

Add MCP or pending actions only after the core path is stable

Expand into tools or task execution after the base conversational path is deterministic and traceable.

Common onboarding mistakes in the current framework​

Mistakes to avoid

MistakeWhy it hurts nowSafer alternative
Using old examples as if v2 were still `2.0.0`You miss newer behavior like `CorrectionStep`, `ce_mcp_planner`, and richer rule phases.Model your rollout on the current repo and current docs.
Overusing `ANY` scope for toolsThe engine stays valid, but your blast radius gets too broad too early.Prefer exact intent/state scope first.
Treating prompt rows as plain copyModern v2 uses prompt metadata for routing semantics.Design prompt rows as both text and behavior contracts.
Skipping trace reviewMost production issues are config mistakes, not Java exceptions.Make audit + trace review mandatory in QA.
Launching without conversation-level serializationThe framework still does not solve ingress concurrency for you.Enforce one active turn per conversation.
Best first milestone

The right first milestone is not "all features enabled." It is one narrow, testable, traceable business flow that your team can explain end-to-end from input to persisted state to final response.