Package org.cibseven.connect.ai.agent

Interface AgentConnector

All Superinterfaces:
Connector<AgentRequest>
All Known Implementing Classes:
AgentConnectorImpl
public interface AgentConnector extends Connector<AgentRequest>
Marker interface and constants for the LangChain4j agent connector.

Use the connector ID "cibseven-ai-agent" in a BPMN service task. The example below shows every supported input/output parameter; only agentName and message are required, the rest are optional. When instruction is empty, the bundled default system prompt from /org/cibseven/connect/ai/agent/default-instruction.txt is used. 


 <camunda:connector>
     <camunda:connectorId>cibseven-ai-agent</camunda:connectorId>
     <camunda:inputOutput>
       <!-- Core agent configuration -->
       <camunda:inputParameter name="agentName">my-agent</camunda:inputParameter>
       <camunda:inputParameter name="agentDescription">Customer support agent</camunda:inputParameter>
       <camunda:inputParameter name="instruction">You are a helpful assistant.</camunda:inputParameter>
       <camunda:inputParameter name="instructionMode">append</camunda:inputParameter>
       <camunda:inputParameter name="model">gpt-5.4-nano</camunda:inputParameter>
       <camunda:inputParameter name="message">${userMessage}</camunda:inputParameter>

       <!-- LLM endpoint / authentication -->
       <camunda:inputParameter name="baseUrl">http://localhost:11434/v1</camunda:inputParameter>
       <camunda:inputParameter name="apiKey">${secrets.OPENAI_API_KEY}</camunda:inputParameter>
       <camunda:inputParameter name="customHeaders">{"Authorization": "Basic dXNlcjpwYXNz", "X-Tenant": "acme"}</camunda:inputParameter>

       <!-- Reasoning controls -->
       <camunda:inputParameter name="reasoningEffort">medium</camunda:inputParameter>
       <camunda:inputParameter name="reasoningSummary">auto</camunda:inputParameter>

       <!-- Tools: Java @Tool classes -->
       <camunda:inputParameter name="toolClasses">com.example.WeatherTools,com.example.CalendarTools</camunda:inputParameter>

       <!-- Tools: MCP servers (JSON array) -->
       <camunda:inputParameter name="mcpServers">
         [
           {"url": "http://server1/mcp", "headers": {"Authorization": "Bearer abc"}},
           {"url": "http://server2/mcp"}
         ]
       </camunda:inputParameter>

       <!-- Chat memory (e.g. human-feedback loop) -->
       <camunda:inputParameter name="useChatMemory">true</camunda:inputParameter>
       <camunda:inputParameter name="memoryId">${execution.getVariable('memoryId')}</camunda:inputParameter>
       <camunda:inputParameter name="chatMemoryMaxMessages">20</camunda:inputParameter>

       <!-- EU AI Act audit -->
       <camunda:inputParameter name="persistChatLog">true</camunda:inputParameter>

       <!-- RAG / pgvector embedding store -->
       <camunda:inputParameter name="pgHost">localhost</camunda:inputParameter>
       <camunda:inputParameter name="pgPort">5432</camunda:inputParameter>
       <camunda:inputParameter name="pgDatabase">vectors</camunda:inputParameter>
       <camunda:inputParameter name="pgUser">postgres</camunda:inputParameter>
       <camunda:inputParameter name="pgPassword">${secrets.PG_PASSWORD}</camunda:inputParameter>
       <camunda:inputParameter name="pgTable">embeddings</camunda:inputParameter>
       <camunda:inputParameter name="maxRagResults">5</camunda:inputParameter>
       <camunda:inputParameter name="minRagScore">0.7</camunda:inputParameter>
       <camunda:inputParameter name="embeddingDimension">384</camunda:inputParameter>
       <camunda:inputParameter name="embeddingModelName">text-embedding-3-small</camunda:inputParameter>

       <!-- Output -->
       <camunda:outputParameter name="agentOutput">${output}</camunda:outputParameter>
       <camunda:outputParameter name="agentOutput_aiMeta">${outputAiMeta}</camunda:outputParameter>
       <camunda:outputParameter name="memoryId">${memoryId}</camunda:outputParameter>
     </camunda:inputOutput>
 </camunda:connector>

The chat log is persisted automatically into a process-scoped variable named AGENT_CONNECTOR_LOG_PREFIX + <activityId> and updated on every request/response/error event of the underlying chat model. If a variable with that name already exists when the connector runs, its content is deserialised and used as the starting point — so multiple invocations of the same service task within one process instance accumulate into a single timeline. The chat log is not exposed as an output parameter because its serialised form regularly exceeds the VARCHAR(4000) limit of Camunda's TEXT_ column.

  • Field Details

    • ID

      static final String ID
      Connector ID used in <camunda:connectorId>.
      See Also:

    • PARAM_NAME_AGENT_NAME

      static final String PARAM_NAME_AGENT_NAME
      Required. Logical name of the agent (passed to LlmAgent.builder().name()).
      See Also:

    • PARAM_NAME_AGENT_DESCRIPTION

      static final String PARAM_NAME_AGENT_DESCRIPTION
      Optional. Human-readable description of the agent.
      See Also:

    • PARAM_NAME_INSTRUCTION

      static final String PARAM_NAME_INSTRUCTION
      Optional. System instruction for the LLM. When null or empty, the connector falls back to the bundled default prompt at /org/cibseven/connect/ai/agent/default-instruction.txt, which describes the generic CIB seven agent role and its possible capabilities (tools, RAG, chat memory, reasoning). Override this parameter to specialise the agent for a concrete task. See PARAM_NAME_INSTRUCTION_MODE for how this value is combined with the bundled default.
      See Also:

    • PARAM_NAME_INSTRUCTION_MODE

      static final String PARAM_NAME_INSTRUCTION_MODE
      Optional. Controls how the caller-supplied PARAM_NAME_INSTRUCTION is combined with the bundled default system prompt. Allowed values:
      • "replace" (default) — the bundled default is discarded and only instruction is sent to the LLM. Matches the historical behaviour.
      • "append" — the bundled default is sent first, followed by instruction, separated by a blank line.
      • "prepend" — instruction is sent first, followed by the bundled default, separated by a blank line.
      When instruction is empty the mode is ignored — only the bundled default is used. An unknown value causes the connector to reject the request with AgentConnectorException.
      See Also:

    • PARAM_NAME_MODEL

      static final String PARAM_NAME_MODEL
      Optional. LLM model identifier (e.g. gpt-5.4-nano, claude-opus-4.7, gemma-4-26b; on OpenRouter prefix with provider, e.g. openai/gpt-5.4-nano). Defaults to "gpt-5.4-nano".
      See Also:

    • PARAM_NAME_MESSAGE

      static final String PARAM_NAME_MESSAGE
      Required. The user message to send to the agent.
      See Also:

    • PARAM_NAME_TOOL_CLASSES

      static final String PARAM_NAME_TOOL_CLASSES
      Optional. Comma-separated list of fully qualified class names whose @Tool-annotated methods are registered with the agent. Each class must have a public no-arg constructor. Example: "com.example.WeatherTools,com.example.CalendarTools"
      See Also:

    • PARAM_NAME_BASE_URL

      static final String PARAM_NAME_BASE_URL
      Optional. OpenAI-compatible base URL (e.g. for Ollama: "http://localhost:11434/v1" or Azure OpenAI endpoints). When omitted, the standard OpenAI API endpoint is used.
      See Also:

    • PARAM_NAME_API_KEY

      static final String PARAM_NAME_API_KEY
      Optional. Override the OPENAI_API_KEY for this specific request. The environment variable OPENAI_API_KEY is the recommended approach.
      See Also:

    • PARAM_NAME_CUSTOM_HEADERS

      static final String PARAM_NAME_CUSTOM_HEADERS
      Optional. Custom HTTP headers attached to every request sent to the OpenAI-compatible endpoint. Format: JSON object of String → String pairs. Example: {"Authorization": "Basic dXNlcjpwYXNz", "X-Tenant": "acme"}
      See Also:

    • PARAM_NAME_MCP_SERVERS

      static final String PARAM_NAME_MCP_SERVERS
      Optional. JSON array describing one or more MCP (Model Context Protocol) servers, each with its own URL and (optional) custom HTTP headers. Tools exposed by each server are registered with the agent in addition to any toolClasses.

      Each entry must have a url string; headers is an optional object of String → String pairs. Example: 

      
 [
   {"url": "http://server1/mcp", "headers": {"Authorization": "Bearer abc"}},
   {"url": "http://server2/mcp"}
 ]
      See Also:

    • PARAM_NAME_REASONING_EFFORT

      static final String PARAM_NAME_REASONING_EFFORT
      Optional. Reasoning effort hint for reasoning-capable models (e.g. "low", "medium", "high"). Allowed values are model-dependent and forwarded as-is to the OpenAI builder.
      See Also:

    • PARAM_NAME_REASONING_SUMMARY

      static final String PARAM_NAME_REASONING_SUMMARY
      Optional. Enables reasoning-summary text in AiMessage.thinking() (e.g. "auto", "concise", "detailed"). Setting this value switches the connector to the OpenAI Responses API (OpenAiResponsesChatModel), which is required for reasoning summaries. Allowed values are model-dependent and forwarded as-is to the OpenAI builder.
      See Also:

    • PARAM_NAME_USE_CHAT_MEMORY

      static final String PARAM_NAME_USE_CHAT_MEMORY
      Optional. Activates the per-conversation chat memory backed by AgentChatMemoryStore. When true, the agent's prior messages — keyed by PARAM_NAME_MEMORY_ID — are replayed on every invocation so a BPMN process can resume the same conversation, typically after a human-feedback user task. Defaults to false (stateless).
      See Also:

    • PARAM_NAME_MEMORY_ID

      static final String PARAM_NAME_MEMORY_ID
      Optional. Identifier of the chat memory entry to reuse across invocations. Used together with PARAM_NAME_USE_CHAT_MEMORY. When the flag is active and this parameter is null or empty, the connector generates a new UUID and exposes it as the PARAM_NAME_MEMORY_ID output so the caller can persist it (e.g. into a process variable) and pass it back on the next invocation.
      See Also:

    • PARAM_NAME_CHAT_MEMORY_MAX_MESSAGES

      static final String PARAM_NAME_CHAT_MEMORY_MAX_MESSAGES
      Optional. Sliding window size (max number of messages retained) for the chat memory of a given PARAM_NAME_MEMORY_ID. Defaults to 20.
      See Also:

    • PARAM_NAME_PERSIST_CHAT_LOG

      static final String PARAM_NAME_PERSIST_CHAT_LOG
      Optional. Per-activity override for the EU AI Act chat-log audit variable (cibseven-connect-ai-agent_<activityId>). Tri-state:
      • null / empty / unset — fall through to the deployment-wide default (system property cibseven.connect.ai-agent.chatLogVariable.enabled or env var CIBSEVEN_CONNECT_AI_AGENT_CHAT_LOG_VARIABLE_ENABLED; built-in default true for compliance).
      • true — write the chat-log variable for this activity, overriding a global false.
      • false — skip the chat-log variable for this activity, overriding a global true.
      In all cases the in-memory event timeline is still built and still emitted to SLF4J / the HistoryEventHandler chain, so external audit sinks keep working. Disabling here without an external sink breaks EU AI Act Art. 12 / 26(6) record-keeping — the modeler is responsible for that trade-off.
      See Also:

    • PARAM_NAME_PG_HOST

      static final String PARAM_NAME_PG_HOST
      Optional. PostgreSQL host for the pgvector embedding store. When present, RAG is activated for this request. Example: "localhost" or "pg.internal.example.com"
      See Also:

    • PARAM_NAME_PG_PORT

      static final String PARAM_NAME_PG_PORT
      Optional. PostgreSQL port. Defaults to "5432".
      See Also:

    • PARAM_NAME_PG_DATABASE

      static final String PARAM_NAME_PG_DATABASE
      Optional. PostgreSQL database name.
      See Also:

    • PARAM_NAME_PG_USER

      static final String PARAM_NAME_PG_USER
      Optional. PostgreSQL user.
      See Also:

    • PARAM_NAME_PG_PASSWORD

      static final String PARAM_NAME_PG_PASSWORD
      Optional. PostgreSQL password.
      See Also:

    • PARAM_NAME_PG_TABLE

      static final String PARAM_NAME_PG_TABLE
      Optional. Name of the pgvector table holding embeddings. Defaults to "langchain4j_embeddings".
      See Also:

    • PARAM_NAME_MAX_RAG_RESULTS

      static final String PARAM_NAME_MAX_RAG_RESULTS
      Optional. Maximum number of documents returned by the retriever per query. Defaults to 5.
      See Also:

    • PARAM_NAME_MIN_RAG_SCORE

      static final String PARAM_NAME_MIN_RAG_SCORE
      Optional. Minimum cosine-similarity score (0.0–1.0) for retrieved documents. Defaults to 0.0.
      See Also:

    • PARAM_NAME_EMBEDDING_DIMENSION

      static final String PARAM_NAME_EMBEDDING_DIMENSION
      Optional. Dimension of the embedding vectors stored in pgvector. Must match the model used during ingestion. Defaults to 384 (AllMiniLmL6V2EmbeddingModel).
      See Also:

    • PARAM_NAME_EMBEDDING_MODEL_NAME

      static final String PARAM_NAME_EMBEDDING_MODEL_NAME
      Optional. Embedding model name (e.g. "text-embedding-3-small"). When set, OpenAiEmbeddingModel is used with the supplied apiKey. When empty or absent, the local AllMiniLmL6V2EmbeddingModel is used as fallback.
      See Also:

    • PARAM_NAME_OUTPUT

      static final String PARAM_NAME_OUTPUT
      The final text response produced by the agent.
      See Also:

    • PARAM_NAME_OUTPUT_AI_META

      static final String PARAM_NAME_OUTPUT_AI_META
      EU AI Act Art. 50(2) machine-readable marker for AI-generated output.

      A Map<String,Object> carrying aiGenerated=true, the runId that produced the answer, the model identity (provider, model, responseId), and a generatedAt ISO-8601 timestamp. BPMN designers map it as a sibling of the main output variable, e.g. <camunda:outputParameter name="agentOutput_aiMeta">${outputAiMeta}</camunda:outputParameter>, so downstream Human Tasks, gateways, and history consumers can distinguish AI-generated values from human-authored ones.

      See Also: