Version: 2.5

Contextual AI Assistant Architecture

Version scope

tSM 2.4 provides the top-bar AI chat and SpEL editor integration. This page describes the unreleased tSM 2.5 extension for Form, TQL, and BPMN authoring and for business screens configured through Assistant Profiles.

Decision Summary

tSM uses one universal AI shell across configuration and business screens. For each turn, the backend resolves a versioned Assistant Profile from the active screen, tenant, user, and business object. The profile defines the scenario presentation, context sources, available actions, and the reusable Agent Profile that performs the governed runtime work.

The browser sends a small context envelope with stable identifiers. Server-side context providers load authorized business facts under the current identity and return evidence. The assistant emits answers, artifacts, or typed action proposals. Deterministic APIs, certified Scripts, and durable processes apply approved actions through their normal authorization and audit boundaries.

The deployable backend, Agent Runtime, state ownership, and process communication are described in tSM AI and Agent Runtime.

Design Principles

A consistent AI entry point adapts to the active business or configuration context.
Customer scenarios are assembled from published profiles, certified providers, tools, and actions, which keeps most extensions configuration-driven.
The browser supplies identifiers and UI intent; authoritative business facts are loaded server-side.
Prompts guide model behavior, while privileges, data access, write authorization, and action schemas remain deterministic platform controls.
Read results carry evidence, and proposed changes remain typed and reviewable.
Long-running work becomes a durable process or A2A Task with a visible lifecycle.
Profiles and contracts are versioned, evaluated, gradually released, and auditable.

Existing Foundation

tSM 2.4 introduced the top-bar AI chat, streamed responses, conversation threads, attachments, feedback, and contextual SpEL assistance. tSM 2.5 reuses the common shell and server-side conversation contract for Form, TQL, and BPMN authoring and for business scenarios, while each surface retains its domain-specific validation and review behavior.

The UI already exposes route-level aiContext metadata for many entity and configuration screens. That metadata supplies profile-selection hints and stable identifiers; the server resolves tenant, identity, privileges, and business facts independently.

Profile Model

Assistant Profile

An Assistant Profile is the customer-configurable unit for one user-facing scenario.

Field	Purpose
Identity and version	Stable code, lifecycle state, immutable published version
Matchers	Surfaces, entity types, modules, routes, roles, and feature flags
Presentation	Name, description, icon, empty state, and starter questions
Agent Profile reference	Published reusable runtime policy and maximum capability
Scenario goal	UI-specific objective appended below the published Agent Profile instructions
Contract refinements	Optional input/result JSON Schema constraints combined with profile contracts using `allOf`
Context providers	Ordered allowed selection and input mapping within the Agent Profile provider policy
Actions	Local action code plus exact published Tool Definition `toolRef`; selected subset of the Agent Profile allow-list
Action policy	Risk class, preview schema, confirmation, approval, and executor
Limits	Optional tighter duration, turn, tool, token, cost, context, and artifact ceilings
Outcome presentation	Rendering/handover for every Agent Outcome code and `FULL`/`PARTIAL` result completeness
Governance	Required privileges, data classification, retention, and rollout
Evaluation	Versioned scenario tests and release thresholds

An Agent Profile defines the reusable behavioral identity and runtime ceiling: instructions, input and result contracts, model policy, provider/tool allow-lists, budgets, privilege requirements, and evaluation gates. It grants no privilege. Multiple Assistant Profiles can reference the same Agent Profile while selecting narrower screens, goals, context providers, tools, limits, or action policies. A BPMN Agent Task can reference that same Agent Profile independently of UI presentation. See the complete Agent Profile configuration.

Business configurators compose profiles from technically certified providers, tools, and actions. Registration of server code, credentials, and permission rules remains part of platform administration.

An action's local code controls presentation and starter behavior. Runtime eligibility uses exact canonical Tool Definition code@version equality with the Agent Profile allow-list. A matching name or schema is insufficient.

Effective Profile Bundle

At the start of a conversation or Agent Run, tsm-ai resolves the published Assistant Profile, Agent Profile, tenant/platform ceiling, delegated security identity, and all referenced contract versions into an immutable effective bundle. Provider and tool sets are intersections, limits and data rules use the most restrictive value, and scenario contracts refine the base contracts. The bundle is pinned to the conversation or run, so instructions, tools, schemas, and model policy remain stable. Platform kill switches and revoked authorization take effect immediately.

Context Envelope

The browser creates a small, versioned envelope with identifiers and relevant UI state:

{
  "version": "1",
  "surface": "customer-detail",
  "route": "/customers/:id",
  "microservice": "customer",
  "entity": {
    "type": "Customer",
    "id": "018f...",
    "code": "C-100045"
  },
  "selection": [],
  "locale": "en"
}

The server validates the envelope against the active route and authenticated identity. Tenant host, privileges, tool access, credentials, and data classification come from server-owned configuration.

Context Providers

A context provider accepts validated identifiers and returns typed facts with evidence metadata.

Provider type	Typical use	Contract
Public API provider	Stable entity and relationship reads	Product-owned typed API and evidence references
SpEL provider	Environment-specific synchronous composition	Certified read Script with typed output
MCP tool	On-demand narrow read capability	Profile allow-list and delegated identity
Knowledge provider	tSM documentation or project knowledge	Source links, version, and retrieval time
Process snapshot provider	Current process/task state and history	Read-only process facts and stable IDs

Providers execute server-side under the delegated identity. Each published provider entry carries the failure mode allowed by the Agent Profile matrix: a required-provider failure fails the run or requires review; an optional-provider failure may additionally continue with an explicit partial-context result. The Assistant never silently treats missing context as complete. Provider results include source type, stable source reference, retrieval time, and provider version.

Customer Care Example

A customer-care Assistant Profile can combine:

customer and account data through Public API;
current balance and payment history through an environment-specific SpEL provider;
open tickets, recent worklogs, comments, and active orders through certified read providers;
applicable procedures through a project knowledge provider.

The browser supplies the customer identifier. The effective profile selects the required facts, data budget, freshness policy, and evidence presentation for that scenario.

Turn Lifecycle

The UI builds the Context Envelope from the active route, object, and selection.
tsm-ai authenticates the request and resolves a published Assistant Profile.
The Assistant Profile and referenced Agent Profile are authorized and pinned.
Required and optional context providers run with time and size limits.
Agent Runtime receives the profile bundle, typed context snapshot, bounded conversation, and scoped tools.
The response streams as structured status, content, evidence, artifact, or action-proposal events.
The UI renders evidence and action review separately from explanatory prose.
tsm-ai records feedback, provider status, usage, and the terminal outcome for operations and evaluation.

Authorization is checked on profile resolution, conversation access, provider execution, tool calls, and action execution.

Evidence and Partial Context

Answers based on business data expose the facts used through an evidence view with source labels, object references, timestamps, and provider status. Knowledge answers link to the relevant document. The response contract distinguishes:

verified facts returned by providers;
inferences derived from those facts;
missing or stale context;
recommendations requiring a business decision.

When data from a DEFAULT or AVAILABLE provider is unavailable, its configured policy can permit an explicit partial-context result. A failed REQUIRED provider never becomes partial context: it produces the profile's FAILED or REQUIRE_REVIEW outcome.

Actions: Propose, Review, Execute

An action is defined by a certified, versioned Action Definition. Every Action Definition pins one exact published Tool Definition toolRef (code@version) in addition to its local action code and version. The model returns that local identity in its typed ActionProposal:

{
  "action": "ticket.addComment",
  "version": "1",
  "target": {"type": "Ticket", "id": "018f..."},
  "input": {"text": "Proposed customer update"},
  "risk": "reversible-write",
  "evidence": ["provider:ticket-summary:..."],
  "idempotencyKey": "..."
}

Before authorization or execution, the server resolves action and version to the pinned Action Definition and then to its exact toolRef. That toolRef must occur in the effective Agent Profile allow-list; the proposal cannot supply or replace it.

The UI validates the schema and renders a preview or diff. The executor reauthorizes the identity and applies the configured policy:

Risk	Default handling
Read-only	Execute in the current turn and display evidence
Draft-only	Create a draft that the user explicitly applies
Reversible write	Preview and confirm, then call Public API or a certified SpEL action
High-impact or multi-step	Start a durable BPMN process with approval, retry, compensation, and audit

Financial, security, bulk, external, and irreversible operations use an explicit action policy and normally a durable User Task approval. The same typed contracts support execution from a screen, process, API, or another agent.

Inbound agent publication uses A2A Script Bindings; outbound process delegation uses an A2A Agent Task.

Conversation and Handover

tsm-ai stores conversations under tenant, owner, Assistant Profile, and access policy. The UI distinguishes a personal working conversation from a thread explicitly attached to a business object. Retention minimizes context snapshots and excludes credentials and hidden model reasoning.

A handover to another user, durable process, or integration contains a structured summary, evidence, open questions, approved proposals, and completed actions. The receiving component uses stable references rather than depending on an opaque chat transcript.

Governance and Evaluation

Each published profile has replayable tests covering:

profile selection and version pinning;
tenant, role, user, and entity data boundaries;
provider selection, evidence, freshness, and partial-context behavior;
allowed tools and action proposals;
preview, confirmation, and approval requirements;
timeout, provider failure, prompt injection, and sensitive-data handling;
schema validity, latency, token, and cost budgets.

Semantic quality can use reviewed or model-assisted scoring. Authorization, tool calls, schemas, approval, and side effects use deterministic assertions. Release gates and tenant-scoped rollout promote only profile versions that meet their required thresholds.

2.5 Delivery Sequence

Profile foundation: context envelope, Assistant/Agent Profile resolver, provider/action contracts, server conversations, and profile authorization.
Read-only pilot: customer-care summary and Q&A with evidence and partial-context handling.
Low-risk proposals: draft reply, add-note proposal, navigation, and structured filter preview.
Durable actions: approval-gated process execution and visible process status.
Scale-out: profile administration, evaluation and release workflow, telemetry, and more business modules.

Decision Summary​

Design Principles​

Existing Foundation​

Profile Model​

Assistant Profile​

Effective Profile Bundle​

Context Envelope​

Context Providers​

Customer Care Example​

Turn Lifecycle​

Evidence and Partial Context​

Actions: Propose, Review, Execute​

Conversation and Handover​

Governance and Evaluation​

2.5 Delivery Sequence​

Related Documentation​