Configuring the Agent

This chapter is the Modeler-facing reference for the AI Agent service task (connectorId = cibseven-ai-agent). For an exhaustive parameter table including the Knowledge Ingestor, see the Configuration Reference.

The element template and its field groups

Apply the CIB seven - AI Agent template (id org.cibseven.connect.ai.agent) to a bpmn:ServiceTask. The fields are organized into five groups:

Group	What it configures
Input	agentName, message, instruction, instructionMode
Agent	baseUrl, model, apiKey, customHeaders, reasoningEffort, reasoningSummary, agentDescription, persistChatLog
Tools	mcpServers, toolClasses → see Tools
Memory	useChatMemory, memoryId, chatMemoryMaxMessages → see Chat Memory
RAG	pgHost…pgTable, maxRagResults, minRagScore, embeddingDimension, embeddingModelName → see RAG

Only Agent name and Message are required; everything else is optional.

Core inputs

Field	Parameter	Notes
Agent name	agentName	Required. Logical name of the agent. Default value in the template: CIB seven AI Agent.
Message	message	Required. The user message. Typically references a process variable, e.g. Summarize: ${feedbackText}.
Agent description	agentDescription	Optional, human-readable description.

LLM provider (endpoint, model, authentication)

The connector speaks to any OpenAI-compatible API. Four fields control the endpoint and model:

Field	Parameter	Default / resolution
Base URL	baseUrl	baseUrl → env OPENAI_BASE_URL → https://api.openai.com/v1
Model	model	model → system property cibseven.connect.ai-agent.defaultModel → env CIBSEVEN_CONNECT_AI_AGENT_DEFAULT_MODEL → built-in gpt-5.4-nano
API key	apiKey	apiKey → env OPENAI_API_KEY
HTTP headers	customHeaders	JSON object of header → value, e.g. {"Authorization": "Bearer sk-..."}

Provider recipes

The same task works against any OpenAI-compatible endpoint — only baseUrl, model, and the authentication differ. Use a current model ID from your provider’s catalogue in place of the placeholders below.

OpenAI (default) — omit baseUrl; set apiKey (or the OPENAI_API_KEY env var).

model:   <an OpenAI chat model>
apiKey:  ${apiKey}

Azure OpenAI — point baseUrl at your Azure deployment endpoint and pass the Azure key. Many Azure setups expect the key in a header; use customHeaders if your gateway requires it.

baseUrl: https://<resource>.openai.azure.com/openai/v1
model:   <your Azure deployment name>
apiKey:  ${azureKey}

OpenRouter — prefix the model with its provider; OpenRouter aggregates many vendors.

baseUrl: https://openrouter.ai/api/v1
model:   <vendor>/<model>     # e.g. openai/<model>, anthropic/<model>
apiKey:  ${openrouterKey}

Ollama (local / self-hosted) — no API key needed for a local server.

baseUrl: http://localhost:11434/v1
model:   <a model you've pulled into Ollama>

System prompt and instruction modes

The connector ships a default system prompt that frames the agent as a CIB seven workflow agent and tells it how to use whatever tools/RAG/memory are wired in, and how to format its reply for the next BPMN step. You influence the prompt with two fields:

• Instruction (instruction) — your system prompt text. Leave empty to use only the bundled default.
• Instruction mode (instructionMode) — how your instruction combines with the bundled default. Ignored when instruction is empty.

Mode	Value	Effect
Replace default	replace (default)	Only your instruction is sent; the bundled default is discarded.
Append to default	append	Bundled default first, then your instruction (blank-line separated).
Prepend to default	prepend	Your instruction first, then the bundled default.

An unknown instructionMode value makes the connector reject the request with an AgentConnectorException. Use append when you want to keep the CIB seven framing and just add task-specific guidance.

Reasoning models

For reasoning-capable models, two optional hints are forwarded to the provider:

Field	Parameter	Example	Effect
Reasoning effort	reasoningEffort	low / medium / high	Thinking-budget hint, forwarded as-is.
Reasoning summary	reasoningSummary	auto / concise / detailed	Enables reasoning-summary text. Switches the connector to the OpenAI Responses API (required for summaries).

Allowed values are model-dependent and passed through unchanged. Setting reasoningSummary changes the underlying client, so only set it for models that support the Responses API.

Output variables

Output field (template default)	Source	Description
agentOutput	${output}	The agent’s final text answer. Required output mapping.
agentOutput_aiMeta	${outputAiMeta}	Map marking the value AI-generated (aiGenerated, runId, provider, model, responseId, generatedAt). Leave unset to skip. See Audit Trail.
memoryId	${memoryId}	The chat-memory id; only meaningful with chat memory. Leave unset to skip. See Chat Memory.