Agent Task

An Agent Task performs one bounded AI operation and returns a typed result to the process. It is designed for steps where BPMN already defines what happens before and after the AI operation.

Typical uses include:

• classifying a ticket or request;
• extracting structured data from text or a document;
• summarizing a customer, incident, or process state;
• drafting a response or work instruction;
• evaluating risk against supplied evidence;
• recommending one of a fixed set of process branches.

Use an Agentic Subprocess when the agent must choose and repeat several activities. Use an A2A Agent Task when the work is delegated to an independently operated remote agent.

Execution Semantics

An Agent Task is an asynchronous wait state:

1. The Process Engine commits the transaction before the task.
2. Its outbox dispatches an idempotent request with a stable agentRunId.
3. Agent Runtime validates deterministic admission, resolves and pins the effective bundle, and atomically persists either a typed rejection or the accepted QUEUED Run.
4. AgentRunAdmissionResult returns that decision. A rejection follows its configuration, authorization, deadline, or contract incident path without awaiting an Agent Run.
5. Authorized context providers load the configured input snapshot for an accepted Run. A failed REQUIRED provider returns BLOCKED context without calling the model; failed selected DEFAULT/AVAILABLE providers produce visible PARTIAL context.
6. The tSM Agent Runtime performs the configured model operation only with FULL or permitted PARTIAL context.
7. The response is validated against the effective profile plus activity contract and policy.
8. A RESULT outcome is mapped to process variables; other Agent Outcomes carry their typed review, rejection, limit, authorization, failure, or cancellation payload.
9. The configured Outcome Mapping continues, creates a User Task, raises a BPMN error, retries, creates an incident, or follows the cancellation path.

The task commits a durable wait state before dispatch. Agent Runtime resumes the same Agent Run after worker restarts, and the Process Engine applies a correlated result in a new transaction.

Runtime Boundary

Agent Runtime is the process-triggered execution capability of the tsm-ai microservice. It resolves the pinned Agent Profile, loads authorized context, calls the approved model, validates the typed result, and owns the durable Agent Run. The embedded Process Engine owns BPMN state, transactions, input/output mapping, retry decisions, incidents, and continuation.

The two components exchange an idempotent durable run request, explicit admission result, and a correlated terminal outcome. This keeps the model call outside the domain-service transaction while preserving a restart-safe process wait state. Agent Runtime owns bounded provider-attempt retries inside the same Agent Run and model episode. The Process Engine owns BPMN activity retry, modeled error, and incident handling after a terminal runtime outcome. Such an activity retry creates a new agentRunId, carries a higher activity-attempt number and previous/root Run links, and retains the activity-level retry budget. Deployment, transport, storage, scaling, and readiness are defined centrally in tSM AI and Agent Runtime architecture.

An A2A Agent Task follows a different boundary: the outbound A2A client in tsm-ai communicates with an independently operated remote agent through that installation's remote tSM Gateway, and the remote A2A Task owns that execution state. The local Gateway is not an outbound proxy.

Configuration

Select an Agent Task in Process Designer and configure the following properties.

Property	Required	Description
Name and ID	Yes	Stable BPMN activity identity and operator-facing name
Agent Profile	Yes	UUID of a currently valid profile that supports AGENT_TASK; each accepted activity attempt resolves and pins the latest valid id + JaVers commitId in its Agent Run
Goal	Yes	Task-specific objective; may contain mapped process expressions
Input Mapping	Yes	Explicit variables or object fields made available to the task
Context Providers	No	Selected subset of the profile's DEFAULT and AVAILABLE providers; REQUIRED providers cannot be removed
Result Form	No	Optional activity-specific refinement combined with the profile result contract using JSON Schema allOf
Output Mapping	Yes	Mapping from validated result fields to process variables
Evidence Policy	No	Requirements that may tighten, but never relax, the profile evidence policy
Active Work Limit	Yes	Maximum cumulative tsm-ai execution time across model/provider/inline work; queueing, durable backoff, and waits do not consume it
Activity Deadline	Yes	Absolute wall-clock deadline or explicit governed UNBOUNDED; an unbounded activity requires monitoring, cancellation, and escalation rather than being an implicit default
Retry Policy	Yes	Maximum activity attempts, backoff, retryable outcome/reason classes, and aggregate active-duration/cost ceilings across linked Runs
Token and Cost Limits	No	Optional tighter per-Run ceilings; the effective Run uses the most restrictive profile, tenant, activity, and remaining aggregate values
Admission Failure Mapping	Yes	Maps typed pre-Run contract, profile, deadline, tenant, or authorization rejection to a configuration incident or allow-listed BPMN error; an identical rejected request is not automatically retried
Outcome Mapping	Yes	Authoritative rule that selects the BPMN action for RESULT, REQUIRE_REVIEW, REJECTED, LIMIT_EXCEEDED, AUTHORIZATION_REVOKED, FAILED, and CANCELED
Business Error Mapping	No	Named condition, error code, and mapped details referenced by an Outcome Mapping rule whose selected action is BPMN_ERROR
Incident Policy	Yes	Retry limits and incident metadata used only when Outcome Mapping selects RETRY or INCIDENT

Model provider credentials and endpoints are selected by the referenced model policy. They are not stored in BPMN XML or supplied through the goal.

The first delivered Agent Task is the generic read-only form of this contract. Its activity deadline defaults to 30 minutes, while its built-in Agent Profile permits at most 10 minutes of cumulative active tsm-ai work. The designer may choose another deadline or explicit UNBOUNDED, but cannot widen the profile's active-work limit. This first slice uses only read-only context and inline Tools and writes the schema-validated JSON result to the mapped process variable.

Admission Failure Mapping applies only before a Run exists. For an accepted Run, Outcome Mapping is the sole action-selection layer. Business Error Mapping and Incident Policy parameterize the selected action; neither can independently override it. For example, the FAILED entry can select RETRY with the Incident Policy and then INCIDENT after exhaustion, while a domain condition on a valid RESULT can select a named BPMN_ERROR mapping.

Input Mapping

The task receives only mapped values. Map stable identifiers and small typed structures rather than complete entities or the unrestricted #variables object.

Example conceptual input:

{
  "ticketId": "018f...",
  "subject": "Customer cannot activate service",
  "description": "Activation fails after identity verification",
  "allowedCategories": ["ORDER", "IDENTITY", "NETWORK", "OTHER"]
}

For data that must be current at execution time, configure a server-side context provider instead of copying a stale value into the process at start.

Result Contract

The result is always validated before it becomes process data. A classification task can use a result schema corresponding to:

{
  "category": "IDENTITY",
  "confidence": 0.91,
  "summary": "Activation is blocked after the identity-verification step.",
  "evidence": [
    {"source": "ticket:018f...", "field": "description"}
  ],
  "needsHumanReview": false
}

Free-form explanation can be one field of the result, but it is not a substitute for fields used by gateways. A sequence-flow condition should read a validated enum, boolean, or number.

Validation and Repair

tSM validates:

• JSON syntax and the complete result schema;
• enum, range, length, and required-field constraints;
• evidence requirements and allowed source references;
• output size and data-classification policy;
• business rules configured for the task.

When enabled, bounded repair can ask the model to correct a schema-invalid response. The Agent Profile sets maxRepairAttempts; the activity may lower that value. Repair receives the validation errors and the previous response but cannot change the task goal, context, limits, policy, or schema. Exhausted repair attempts follow the configured error path.

Branch Recommendation

An Agent Task can recommend a branch by returning a value from a fixed enum. The following gateway uses that validated variable. The model does not activate the sequence flow directly.

Low confidence, missing evidence, or an unrecognized category should route to a User Task rather than silently selecting a default business action.

Drafts and Protected Actions

An Agent Task may create a draft such as a reply, remediation plan, or configuration proposal. The result remains data until a following User Task, Service Task, or approved subprocess applies it.

An Agent Task cannot directly execute an unrestricted write. Separate the flow into:

Agent Task → deterministic validation → User Task / policy approval → Service Task or process action

This makes the proposal, decision, actor, and final side effect independently auditable.

Deadline, Cancellation, and Late Results

The configured Active Work Limit is the Agent Run's cumulative execution budget. Admission narrows it to the strictest Agent Profile, activity, tenant, and platform value. It is consumed by model episodes, provider attempts, and inline Tools, not by queueing, durable backoff, or WAITING. Provider retries do not reset it.

Separately, the Process Engine owns the activity's wall-clock deadline. It may be explicitly UNBOUNDED for intentionally open-ended work only when the process provides visible monitoring, privileged cancellation, and escalation/incident handling. Model calls, context providers, and inline Tools always retain finite technical timeouts even under an unbounded activity.

The Process Engine owns the BPMN attempt and tsm-ai owns the Agent Run. Each keeps the first terminal transition committed in its own store. If the task times out or is canceled before the outcome is applied, a later Agent result is retained for audit but cannot continue the process. If the Run committed its result before a cancellation command reached tsm-ai, that Run remains RESULT; the Process Engine still ignores it when its activity attempt has already ended.

Active budget exhaustion is LIMIT_EXCEEDED / MAX_ACTIVE_DURATION. Exhausted provider timeouts are FAILED / MODEL_TIMEOUT. Activity deadline expiry is a Process Engine outcome. Outcome Mapping must provide the corresponding BPMN timeout, retry, review, or incident behavior.

Errors and Incidents

Condition	Default handling
Invalid mapped input	Configuration incident; do not call the model
Required context provider unavailable	Return blocked context without a model call, then follow the mapped review/failure path
Selected default/available provider unavailable	Continue with explicit partial context, a visible warning, and missing-source evidence
Model timeout or temporary service failure	Agent Runtime may create another Provider Attempt in the same Run and episode, using persisted backoff and the original budgets
Result violates schema	Bounded repair, then modeled error or incident
Safety or data-policy rejection	Non-retryable policy incident or configured human-review path
Token or cost limit reached	Stop the run and follow the limit-exceeded path
Process activity canceled	Cancel queued work where possible and mark late results as ignored

Provider attempts never increase the active-time or cost budget. They keep the same agentRunId and episode but receive distinct attempt identities. After a terminal outcome, an Outcome Mapping action of RETRY is different: the Process Engine persists the next BPMN activity attempt and starts a new linked Agent Run. Duplicate delivery of either start request is only an idempotent no-op, not another retry. The activity-level attempt, active-duration, deadline, and cost limits span all linked Runs.

Audit and Observability

The process-instance view links the task to its Agent Run and shows the configuration versions, mapped inputs, context-provider status, result, evidence, token and cost counters, attempts, timing, and terminal state. The Agent Runs detail adds the replayable event timeline and read-only execution diagram. Hidden model reasoning is neither required nor stored; the audit records observable requests, tool/provider events, structured decisions, and business outcomes.

Common Agent Run states, recovery, incident handling, and the unified Operations view are described in Agentic Process Automation.

Best Practices

• Keep one Agent Task focused on one explainable business decision.
• Prefer enums and typed fields over parsing generated prose in a gateway.
• Give the task only the context required for its goal.
• Provide a human-review branch for uncertainty and missing evidence.
• Reference the Agent Profile UUID and verify that every accepted Run records the resolved technical version and exact result schema; do not copy prompts or a profile version into BPMN.
• Test the task against a versioned scenario set before deployment and keep the result as delivery evidence rather than a separate profile publication state.
• Use SpEL, DMN, or a Service Task for deterministic calculations and rules.