Audit Trail & AI Transparency

Every AI Agent invocation is recorded automatically. This chapter describes the technical transparency features the connector ships — what is recorded, where, and how to tune or redact it.

The per-activity chat-log variable

For each AI Agent service task the connector writes a process-scoped variable named:

cibseven-connect-ai-agent_<activityId>

It holds a JSON array of audit events for that activity. Key behaviors:

• Written on every LLM request / response / error event as the agent loop runs.
• Accumulates: if the variable already exists when the task runs again within the same process instance, prior content is decoded and new events are appended to one timeline.
• It is not an output parameter — its serialized form regularly exceeds the VARCHAR(4000) limit of the engine’s TEXT_ column, so it’s managed as its own variable rather than mapped output.
• A companion flag variable cibseven-connect-ai-agent marks that the agent connector ran.

What’s recorded

Each event is a structured record (schema version 1). Fields seen on events include:

• Identity / sequence: schemaVersion, type (request/response/error), runId, eventSeq, timestamp.
• Model: provider, model, endpoint.
• Process correlation: processInstanceId, processDefinitionId, processDefinitionKey, executionId, activityId (and businessKey / tenantId when present).
• Caller identity: userId, userIdSource, groupIds.
• Content: messages[] (role + content) on requests.
• Tools: tools[] (available tool names), toolProvenance{} (per tool: kind local/mcp, and for MCP the server, url, originalToolName), and toolCalls[] (the calls the model made, with id, name, arguments) on responses.
• Outcome: durationMs; on errors, the error class and a short stack (up to 5 frames).
• Tool side-effects: when ProcessStarterTool starts a process, a record with the resulting processInstanceId, state, and the principal it executedAs is stitched onto the timeline.

A real request event (from the tool-usage demo):

{
  "schemaVersion": 1,
  "type": "request",
  "runId": "7643fc4c-9dfe-4ecd-99f1-2e25fcb3cc6d",
  "eventSeq": 0,
  "timestamp": "2026-05-24T13:19:26.110397928Z",
  "provider": "OPEN_AI",
  "model": "gpt-5.4-nano",
  "endpoint": "https://api.openai.com/v1",
  "processDefinitionKey": "agent-with-tool-usage",
  "activityId": "Activity_agentic_process_management",
  "userId": "demo",
  "groupIds": ["camunda-admin"],
  "messages": [
    { "role": "SYSTEM", "content": "You have access to ... ProcessStarterTool ..." },
    { "role": "USER",   "content": "Start the process \"process-as-a-tool\" ..." }
  ],
  "tools": ["runProcessByKey"],
  "toolProvenance": { "runProcessByKey": { "kind": "local" } }
}

The matching response event adds durationMs and the toolCalls[] the model issued. These logs are what the EE AI Agent Audit view renders.

Marking AI-generated output (aiMeta)

Mapping the AI-output marker output (${outputAiMeta} → e.g. agentOutput_aiMeta) attaches a machine-readable map to the result:

{ "aiGenerated": true, "runId": "...", "provider": "OPEN_AI", "model": "...", "responseId": "...", "generatedAt": "2026-..." }

Downstream user tasks, gateways, and history consumers can use it to distinguish AI-generated values from human-authored ones. Leave the output field unset to skip it. See Configuring the Agent.

Content redaction

For GDPR-conservative deployments, message/response content can be replaced with a SHA-256 hash plus the original character length (the rest of the event — identity, model, tools, timings — is preserved):

When enabled, each messages[].content becomes a {hash, length, redacted} marker. This trades webclient readability for confidentiality. Resolution is property → env → default false.

Turning the chat-log variable off

The DB write can be suppressed at two scopes (the in-memory timeline is still built and still emitted to SLF4J / the HistoryEventHandler chain, so external audit sinks keep working — only the engine DB write is skipped):

• Per activity — the Persist chat-log audit variable field (persistChatLog), tri-state: empty = use global default, ${true} = force on, ${false} = force off (overrides the global).
• Deployment-wide — cibseven.connect.ai-agent.chatLogVariable.enabled (system property) or CIBSEVEN_CONNECT_AI_AGENT_CHAT_LOG_VARIABLE_ENABLED (env), default true. The connector logs the resolved value once at startup (WARN when disabled, since it’s a compliance-relevant deviation).

Transparency to the end user

aiMeta is consumed by downstream logic. The person who reads or acts on the agent’s output in a Tasklist form is a distinct audience, and AI transparency obligations (e.g. EU AI Act Art. 50 user-facing disclosure) are about them. The connector gives you the signal; surfacing it is a modeling choice:

• Label AI-generated values in forms. When a user task shows agentOutput, make it clear the value was produced by AI and should be reviewed — e.g. a read-only “AI-generated — please verify” field, or a form hint driven by agentOutput_aiMeta.aiGenerated.
• Prefer review steps for consequential output. Put a human approval between the agent and any irreversible action (the human-in-the-loop pattern).
• Give reviewers the trail. In CIB seven Enterprise, the AI Agent Audit view renders the chat-log timeline so a reviewer can see the prompt, tools, and reasoning behind an answer.

The EU AI Act compliance guide

Deployer obligations, risk-tier guidance, retention, and the Article-by-Article mapping are maintained in a separate compliance guide (COMPLIANCE.md), so the legal content can be reviewed and versioned independently of this technical manual. Refer to that guide for compliance decisions; use this chapter for the knobs that implement them.