Tools

Tools let the agent do things, not just answer. When tools are wired into an AI Agent service task, the model can decide to call them, the connector executes the call, feeds the result back to the model, and the loop continues until the model produces a final answer. Every tool call is captured in the audit trail.

There are two ways to give the agent tools, and they combine freely on one task:

• Java @Tool classes — the toolClasses parameter (Tools group).
• MCP servers — the mcpServers parameter (Tools group).

How the agent loop uses tools

The connector builds a LangChain4j agent and registers every tool from toolClasses and every tool discovered on the configured mcpServers. The model receives each tool’s name, description, and argument schema, and chooses when to call. The bundled default system prompt instructs the agent to prefer calling a tool over guessing, to never fabricate tool output, and to report tool errors faithfully rather than retrying on its own.

Built-in tool: ProcessStarterTool

The connector ships one ready-to-use tool that lets the agent start a CIB seven process and react to its result — the “process-as-a-tool” pattern.

Enable it by adding its fully-qualified class name to Tool classes:

org.cibseven.connect.ai.agent.impl.ProcessStarterTool

It exposes a single method, runProcessByKey, which starts a process by definition key, polls until it ends (or the retry budget is exhausted), and returns its output variables — so the model never has to orchestrate its own polling loop.

Arguments the model supplies

Result map returned to the model: processInstanceId, processDefinitionId, state (one of ACTIVE, SUSPENDED, COMPLETED, EXTERNALLY_TERMINATED, INTERNALLY_TERMINATED), ended, attempts, and outputs (the filtered process variables).

Authorization

The started process runs under the authentication of the user who triggered the agent service task — captured at the start of the connector invocation and re-applied on the engine thread. The tool does not elevate privileges; an engine authorization error is reported as-is.

Threading

Engine calls run on a dedicated daemon thread pool (not the JVM common pool) so each call gets its own command context and transaction.

Audit

Each successful start publishes a side-effect record onto the chat log: the tool name, the resulting processInstanceId, the state, and the principal it executedAs. See Audit Trail.

Custom Java @Tool classes

Register your own tools by listing their fully-qualified class names (comma-separated) in Tool classes:

org.cibseven.connect.ai.agent.impl.ProcessStarterTool,com.example.WeatherTools,com.example.CalendarTools

Requirements for each class:

• Annotate methods with LangChain4j’s @Tool (a description) and parameters with @P (per-argument descriptions). These descriptions are what the model sees — write them for the model.
• The class must have a public no-arg constructor. A fresh instance is created on every connector invocation.
• The class (and its dependencies) must be on the engine classpath — packaged into the agent overlay or otherwise visible to the connector’s classloader.

If a listed class cannot be loaded or instantiated, the connector fails fast with an AgentConnectorException rather than silently dropping the tool.

public class WeatherTools {
  @Tool("Returns the current weather for a city.")
  public String currentWeather(@P("City name, e.g. 'Munich'") String city) {
    // ... call your weather service ...
    return "Munich: 18°C, cloudy";
  }
}

MCP servers

Model Context Protocol servers expose tools over HTTP. Configure them as a JSON array in MCP servers; their tools are registered alongside any toolClasses.

[
  {"name": "engine", "url": "http://localhost:8081/mcp"},
  {"name": "krank",  "url": "http://localhost:8082/mcp", "headers": {"Authorization": "Bearer token"}}
]

• url (required) — the MCP endpoint. The connector uses the HTTP-streaming transport.
• headers (optional) — a JSON object of header → value, e.g. for bearer-token auth.
• name (optional, 1–32 chars of [a-zA-Z0-9_-]) — a prefix that disambiguates tools across servers. The model sees <name>__<toolName> instead of just <toolName>. When omitted, the connector derives a slug from the URL host/port (e.g. localhost:8081 → localhost-8081).

Why the prefix matters

Two MCP servers exposing a tool of the same name would otherwise collide and abort the agent invocation. Prefixing makes every tool name unique and gives the model a stable mental model when servers are added or removed. Tool execution still routes to the right server using the original tool name; only the LLM-facing name is prefixed.

Audit

For each MCP tool the chat log records its provenance — kind: "mcp", the server prefix, the url, and the originalToolName — so auditors can see exactly which external endpoint served which tool. Local Java tools are recorded as kind: "local". See Audit Trail.

See Examples for runnable tool and MCP models.