Installation & Enablement

The AI Agent connector ships with the CIB seven distributions as a removable overlay. This chapter explains how it’s delivered, how to enable or disable it per distribution, and how to set the deployment-wide default model.

Delivery model

The connector and its AI dependencies — LangChain4j, the bundled ONNX embedding model, pdfbox, pgvector — are packaged separately from the always-loaded engine libraries. The design goal is non-invasiveness: if the overlay is absent, the engine behaves exactly as before and loads no AI dependencies. So enabling/disabling is, in every distribution, about whether the overlay is on the classpath — not about a code change.

run / run4

The overlay lives in configuration/userlib-ai/ (separate from the always-loaded configuration/userlib/). The start script adds it to the Spring Boot loader path only when AI is enabled. The logic in run.sh / run.bat:

  • Default / dev mode: enabled.
  • --production: disabled (the AI dependencies stay off the classpath).
  • --ai / --ai-agent / --agent flag: force-enable (e.g. to use it under --production).
  • AI_AGENT_ENABLED environment variable (true/false): overrides all of the above — this is the control surface used by the Docker image.
./start.sh                 # AI Agent enabled (dev/default)
./start.sh --production    # AI Agent disabled
./start.sh --production --ai   # AI Agent re-enabled under production
AI_AGENT_ENABLED=false ./start.sh   # force disabled regardless of mode

The script prints AI Agent connector enabled / disabled at startup so you can confirm.

Tomcat

The overlay jars ship in server/apache-tomcat-<version>/lib-ai/ (separate from the always-loaded lib/). The distribution’s conf/catalina.properties is generated at build time from the stock file plus one appended entry that puts lib-ai/ on Tomcat’s common.loader — so the connector shares the engine’s classloader and the Connect SPI picks it up. It is active by default.

To disable on a standalone Tomcat, either:

  • delete the lib-ai/ folder, or
  • remove the lib-ai entries from common.loader in conf/catalina.properties.

WildFly

The connector ships as a JBoss module org/cibseven/connect/cibseven-connect-ai-agent/ (a “fat” module bundling all its transitive jars, including the native ONNX runtime). It is wired in by an import in the cibseven-engine-plugin-connect module:

<module name="org.cibseven.connect.cibseven-connect-ai-agent" services="import" optional="true" />
  • services="import" registers the connector via the Connect SPI.
  • optional="true" means the engine still boots if the module directory is removed.

It is active by default. To disable, remove the module directory (or the import line above). WildFly deployments should allow extra metaspace for the LangChain4j/ONNX footprint (the Docker image sets -XX:MaxMetaspaceSize=1024m).

Setting the default model

Operators set the organisation-wide default model (used when a task leaves Model empty) via:
JVM system property -Dcibseven.connect.ai-agent.defaultModel=<provider-model>
Environment variable CIBSEVEN_CONNECT_AI_AGENT_DEFAULT_MODEL=<provider-model>

Resolution is property → env → built-in fallback (gpt-5.4-nano). The run distro’s default.yml documents this stanza. See also Configuration Reference. Provider endpoint/key defaults come from OPENAI_BASE_URL / OPENAI_API_KEY (see Configuring the Agent).

Element templates in the Modeler

The connector’s two element templates ship inside the connector JAR under /element-templates/. The webclient modeler discovers them on the classpath, e.g. in the run distro’s default.yml:

templates:
  paths:
    - "classpath*:element-templates/*.json"     # bundled templates (incl. ai-agent)
    - "file:configuration/element-templates/*.json"  # operator-supplied templates

So once the overlay is on the classpath, CIB seven - AI Agent and CIB seven - Knowledge Ingestor appear in the template picker automatically. Operators can drop additional templates into configuration/element-templates/.

Docker

The official images ship the connector active by default (ENV AI_AGENT_ENABLED=true) and use AI_AGENT_ENABLED as the single toggle, applied by the entrypoint at startup:

  • Tomcat image (cibseven-tomcat.sh): AI_AGENT_ENABLED=false strips the lib-ai entries from common.loader in conf/catalina.properties.
  • WildFly image (cibseven-wildfly.sh): AI_AGENT_ENABLED=false removes the cibseven-connect-ai-agent module import; the script also sizes metaspace (MaxMetaspaceSize=1024m) for the LangChain4j/ONNX footprint.
docker run -e AI_AGENT_ENABLED=false ...   # disable the connector in a container

Enable / disable at a glance

Distribution Overlay location Default Disable
run / run4 configuration/userlib-ai/ on (dev) / off (--production) --production without --ai, or AI_AGENT_ENABLED=false
Tomcat lib-ai/ on common.loader on delete lib-ai/ or strip the common.loader entries (Docker: AI_AGENT_ENABLED=false)
WildFly JBoss module + import on remove the module dir / import (Docker: AI_AGENT_ENABLED=false)

Footprint, sizing & egress

The overlay is heavier than the HTTP/SOAP connectors — plan for it:

  • Disk: the connector plus its LangChain4j / ONNX / pdfbox / pgvector dependencies add on the order of hundreds of MB to the distribution.
  • Memory / metaspace: LangChain4j and the bundled local ONNX embedding model load into the JVM. Allow extra metaspace (the WildFly image sets -XX:MaxMetaspaceSize=1024m) and headroom in the heap; the embedding model is loaded into memory on first use.
  • First-call latency: the local embedding model initialises on first RAG/ingestion use, so the first such call is slower than subsequent ones. LLM calls themselves take seconds (more with tools/RAG/reasoning) — run agent tasks with camunda:asyncBefore so they don’t block request threads.
  • Outbound network (egress): the engine JVM makes outbound HTTPS calls to the configured baseUrl (the LLM endpoint) and to any MCP server url. With a remote embedding model it also calls the public OpenAI endpoint (regardless of baseUrl — see RAG). Ensure that egress is permitted, or route it through an approved proxy/gateway. Full data-flow detail is in Security & Data Handling.

Once enabled, head to Getting Started or Configuring the Agent.

On this Page: