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 intake creates or resumes the Agent Run in QUEUED before a worker claims it.
4. Authorized context providers load the configured input snapshot.
5. The tSM Agent Runtime performs the configured model operation.
6. The response is validated against the effective profile plus activity contract and policy.
7. A RESULT outcome is mapped to process variables; other Agent Outcomes carry their typed review, rejection, limit, authorization, failure, or cancellation payload.
8. 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 and a correlated 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; the Process Engine owns BPMN activity retry, modeled error, and incident handling after a terminal runtime outcome. 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, and the remote A2A Task owns that execution state. tSM Gateway is used only for inbound Script MCP and A2A publication.

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	Exact published profile version containing instructions, model policy, base contracts, provider/tool policy, limits, data policy, and evaluation gates
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
Timeout	Yes	Maximum wall-clock duration of one attempt
Retry Policy	Yes	Maximum attempts, backoff, and retryable error classes
Token and Cost Limits	No	Optional tighter ceilings; the effective run uses the most restrictive profile, tenant, and activity values
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.

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.

Errors and Incidents

Condition	Default handling
Invalid mapped input	Configuration incident; do not call the model
Context provider unavailable	Retry only when provider policy marks the error transient
Model timeout or temporary service failure	Retry with configured backoff and stable Agent Run ID
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

Retries never increase the configured overall deadline or cost budget. A retry reuses the same logical Agent Run and idempotency key while recording a separate attempt.

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. 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.
• Pin the published Agent Profile and result schema to the process version.
• Test the task against a versioned evaluation set before deployment.
• Use SpEL, DMN, or a Service Task for deterministic calculations and rules.