Agentic Subprocess

An Agentic Subprocess is a bounded ad-hoc BPMN scope in which an agent chooses from explicitly exposed child activities. The surrounding process defines the goal, permitted data, available activities, active-work limits, approvals, owner deadlines, and completion behavior.

The agent interacts through typed Agent Tools. It proposes a Tool Call, and the Process Engine validates and starts the corresponding BPMN activity using its normal transaction, retry, authorization, and audit behavior.

When to Use It

Use an Agentic Subprocess when:

• several diagnostic paths are possible and the useful next check depends on previous results;
• the order of permitted activities cannot be completely fixed at design time;
• the process must preserve every activity, approval, retry, and observation;
• the problem has a clear goal, bounded toolbox, measurable completion criteria, and escalation.

Use an Agent Task for one model operation and standard BPMN for a known sequence. Agentic Subprocesses are designed for bounded goals with a safe stop condition and an explicitly exposed Tool set.

Designing the Scope

Create an ad-hoc subprocess and mark it as Agentic. Add only the activities the agent may select. Each child activity is configured as an Agent Tool.

Suitable tools include:

• read-only Service Tasks that load a typed fact or relationship;
• External or Kafka Tasks for diagnostics and integrations;
• an Agent Task for one specialized inference;
• a Call Activity that represents an approved reusable business capability;
• a User Task that collects missing information or approval;
• an A2A Agent Task for a bounded delegation to another registered agent.

Gateways, boundary events, validation tasks, and compensation handlers remain process controls. An activity enters the agent Tool catalog only when the model author marks it Available to agent.

Subprocess Configuration

Property	Required	Description
Agent Profile	Yes	UUID of a currently valid profile that supports AGENTIC_SUBPROCESS; admission resolves and pins the latest valid JaVers commit in the Agent Run
Goal	Yes	Concrete outcome for this subprocess instance
Context Mapping	Yes	Explicit process variables available to the agent
Result Form	No	Optional subprocess-specific refinement combined with the profile result contract using JSON Schema allOf
Completion Rule	Yes	Valid final response, deterministic condition, or both
Maximum Model Calls	Yes	Hard upper bound on model turns
Maximum Tool Calls	Yes	Hard upper bound across the complete run
Tool Calls per Turn	Yes	Maximum proposals accepted from one model response
Parallel Tool Calls	Yes	Maximum activities that may run concurrently
Repetition Policy	Yes	Whether and how an activity may run again with the same input
Active Work Limit	Yes	Maximum cumulative Agent Runtime execution time; QUEUED, durable backoff, and WAITING do not consume it
Subprocess Deadline	Yes	Absolute wall-clock deadline or explicit governed UNBOUNDED; unbounded waiting requires monitoring, cancellation, and escalation
Token and Cost Budgets	Yes	Aggregate limits for the complete Agent Run
Approval Policy	Yes	Risk classes that require confirmation or User Task approval
Admission Failure Mapping	Yes	Maps typed pre-Run contract, profile, deadline, tenant, or authorization rejection to a configuration incident or allow-listed BPMN error
Outcome Mapping	Yes	Explicit BPMN action for RESULT, REQUIRE_REVIEW, REJECTED, LIMIT_EXCEEDED, AUTHORIZATION_REVOKED, FAILED, and CANCELED

Tenant, platform, and Agent Profile policies may reduce configured limits. The subprocess values are tighter ceilings and cannot add a provider/tool, relax a policy, or raise a profile maximum.

Agent Tool Configuration

Only child activities explicitly marked Available to agent enter the tool catalog.

Property	Description
Tool ID	Stable unique ID inside the subprocess scope
Tool Definition	Exact certified canonical toolRef (code@version) that must also occur in the Agent Profile allow-list
Name and Description	Purpose, expected effect, and when the tool should be used
Input Form	JSON Schema for model-supplied parameters
Input Mapping	Model parameters and server-controlled values mapped to activity inputs
Result Form	JSON Schema for the Tool Outcome payload
Result Mapping	Activity result mapped back to the Agent Run and selected process variables
Risk Class	Read-only, draft, reversible write, high-impact, or privileged
Required Privilege	Authorization checked for the initiating identity and, when applicable, approver
Repeatable	Whether the same canonical call may execute more than once
Invocation Limit	Maximum calls to this tool during one Agent Run
Concurrency Group	Activities that must not run in parallel because they share a resource
Deadline and Retry	Activity-owner execution, timeout/unbounded-wait, reconciliation, and retry policy
Idempotency Mapping	Stable key used to deduplicate a side effect
Compensation	Optional activity that mitigates a completed side effect

The tool schema contains only parameters the model is allowed to choose. Credentials, tenant, target host, service routing, business ownership, and protected defaults are injected by the server after authorization.

Tool ID is only the local BPMN alias. Eligibility is established by exact Tool Definition toolRef equality, not by the local ID or schema similarity. The activity may tighten the certified definition's schema, risk, approval, limits, timeout, or retry policy but cannot relax it.

An Agent Tool that may take an unknown or very long time must be an asynchronous process activity: it returns a durable operation correlation, releases its worker, exposes status/cancellation, and eventually produces one typed Tool Outcome. It must not hide an unbounded microservice call inside a synchronous INLINE handler. Inline reads and deterministic validations always have finite technical timeouts, best-effort cancellation, and a late-result commit fence.

Runtime Loop

1. Enter and commit. The Process Engine enters the subprocess, persists its wait state and stable agentRunId, and publishes an idempotent request after commit.
2. Admit and resolve the run. Agent Runtime in tsm-ai deterministically validates admission, pins the Agent Profile, model policy, context providers, tool contracts, completion contract, and budgets, and returns AgentRunAdmissionResult. Rejection creates no Run; acceptance persists the pinned QUEUED Run before execution.
3. Build context and catalog. Runtime loads mapped process values, authorized provider results, previous Tool Outcomes, remaining limits, and currently enabled Agent Tools.
4. Request and persist a turn. Runtime sends the bounded request to the approved model and records the response reference, usage, model request ID, and turn number.
5. Validate and propose a batch. Runtime validates the complete response, independent Tool Calls, catalog and argument hashes, and limits, persists the proposal, changes the Run to WAITING, releases its worker, and publishes AgentToolCallsProposed.
6. Admit the batch. The Process Engine validates and persists the complete batch atomically, assigns an initial disposition to every call, and returns AgentToolBatchAdmissionResult before any external effect starts.
7. Approve when required. A protected proposal waits in a User Task containing its evidence, exact parameters, expected effect, expiry, and compensation information.
8. Execute activities. The Process Engine runs valid BPMN activities. Independent reads may run in parallel; conflicting or side-effecting operations are serialized.
9. Return a complete observation vector. Every original call reaches a terminal Tool Outcome. The Process Engine returns them together, and Agent Runtime atomically persists the complete vector before changing the active Run from WAITING to QUEUED.
10. Continue or finish. Runtime either requests another turn or publishes a schema-valid Final Outcome. The Process Engine maps the result and continues the parent process.

When the model returns neither a tool call nor a valid Final Outcome, the configured repair or escalation path is used. Silence is not treated as successful completion.

Tool Batch, Tool Call, and Tool Outcome

A proposal has a stable identity, catalog digest, and ordered independent calls:

{
  "proposalId": "episode-3-proposal-1",
  "toolCatalogDigest": "sha256:catalog-17",
  "calls": [
    {
      "toolCallId": "turn-3-call-1",
      "toolRef": "tool/inspect-recent-alarms@2",
      "arguments": {
        "serviceId": "SVC-100045",
        "periodMinutes": 30
      },
      "argumentsHash": "sha256:arguments-41"
    }
  ]
}

The Process Engine accepts the complete batch before dispatch and returns an initial disposition for each call:

{
  "proposalId": "episode-3-proposal-1",
  "admission": "ACCEPTED",
  "callDispositions": [
    {
      "toolCallId": "turn-3-call-1",
      "status": "SCHEDULED"
    }
  ]
}

After every call is terminal, it returns one complete observation vector:

{
  "proposalId": "episode-3-proposal-1",
  "complete": true,
  "outcomes": [
    {
      "toolCallId": "turn-3-call-1",
      "status": "COMPLETED",
      "reasonCode": "OK",
      "output": {
        "criticalAlarmCount": 2,
        "alarmIds": ["A-18", "A-21"]
      },
      "evidence": ["alarm:A-18", "alarm:A-21"],
      "changedResources": [],
      "attempts": 1
    }
  ]
}

Allowed terminal statuses are COMPLETED, REJECTED, FAILED, TIMED_OUT, CANCELED, and INDETERMINATE. The model observes the complete outcome vector, not unrestricted process state. Failed tools return a sanitized typed reason; stack traces and secrets stay in operational logs.

Unknown Tools, malformed arguments/hashes, duplicate IDs, a non-current proposal version, an exceeded batch limit, or a catalog mismatch reject the whole batch before execution. Once that structural boundary passes, live authorization, activity enablement, repetition, risk, and business policy can reject one call without discarding independent calls. Batch admission is atomic; the resulting activities and side effects are not one distributed transaction.

Parallel Calls and Resource Conflicts

All calls proposed in one v1 batch must be semantically independent; dependsOn is not supported. If one operation needs another call's result, it is proposed in a later model episode. The engine, not the prompt, enforces parallelism. Calls run in parallel only when all of the following are true:

• the subprocess and current budget allow another parallel activity;
• the tools are read-only or declare non-conflicting resource/concurrency groups;
• neither call depends on the other call's result;
• each activity has an independent idempotency and timeout policy.

Write operations over the same business object are serialized. The engine waits for all calls from the current proposal to reach a terminal state and publishes one complete ordered outcome vector. Partial completion and approval progress are visible operationally but cannot start another model episode.

Repetition and Loop Protection

tSM creates a canonical signature from the tool ID, validated arguments, and target business resource. The repetition policy can:

• reject an identical call within the same turn;
• reuse the previous read-only result while it remains fresh;
• allow a configured number of calls across different turns;
• require a changed input or explicit reason before repeating;
• block a repeated side effect regardless of the model request.

The run stops before exceeding any model-call, tool-call, per-tool, repetition, parallelism, active-work, token, or cost limit. The Process Engine separately enforces every configured owner deadline. Limit enforcement happens before a model call, before activity dispatch, and after usage is recorded.

Human Approval

For a protected call, tSM creates an approval User Task before starting the activity. The approver sees:

• requested tool and business target;
• validated arguments and server-controlled values after redaction;
• evidence and agent explanation;
• expected effect, risk class, expiry, and compensation path;
• remaining Agent Run limits and previous related actions.

Approval is bound to the exact call ID, Tool version, canonical arguments hash, target, pinned profile bundle, approval-policy version, and expiry. Changing any bound value invalidates the decision and requires a new proposal and approval. Privileges are checked again immediately before execution.

Granting approval permits the original call to execute; it is not yet a Tool Outcome. Denial becomes REJECTED / APPROVAL_REJECTED, expiry becomes TIMED_OUT / APPROVAL_EXPIRED, and process or Run cancellation becomes CANCELED. A bounded approver comment is untrusted observation data and cannot modify the call or grant broader authority.

Persistent State and Recovery

The process stores a small agentRunId, correlations for currently executing BPMN activities, and the final-result reference. The Agent Run store owned by tsm-ai keeps the turns, Tool Calls, and larger execution record:

• immutable configuration and policy snapshot;
• context and tool-catalog hashes;
• model turns and usage;
• Tool Batch identity/hash/admission, per-call dispositions, approvals, attempts, and outcomes;
• final outcome, incident, cancellation, and compensation references.

Model responses and external calls use stable idempotency keys. After a restart, each owner resumes from its last persisted transition: the Process Engine restores the BPMN wait state and Agent Runtime restores the Agent Run. Duplicate or late completion events are recorded without starting a second turn or repeating a completed side effect.

If a batch times out or is canceled, completed activities keep their real outcomes and activities that never started become TIMED_OUT or CANCELED. In-flight writes are reconciled before their effect is classified. An INDETERMINATE mutating effect never starts another autonomous episode and normally routes the Run to REQUIRE_REVIEW / TOOL_EFFECT_INDETERMINATE. Outcomes arriving after a terminal Run remain audit history and cannot reopen it.

The Run's maxActiveDuration is cumulative across model episodes, provider attempts, and inline Tools. Admission may shorten it to a stricter profile, subprocess, tenant, or platform limit. QUEUED, durable retry backoff, approvals, external activity execution, and other WAITING time do not consume active duration, model turns, tokens, or provider cost.

The Process Engine separately owns the subprocess wall-clock deadline. A designer may explicitly choose UNBOUNDED for genuinely open-ended external or human work only with a visible status, privileged cancellation, and escalation/incident path. Every model, context-provider, and inline- Tool call remains finite even when the subprocess wait is unbounded.

The Process Engine owns the subprocess attempt, child-activity timers, and approval expiry; tsm-ai owns the Agent Run and provider timers. Each keeps its first committed terminal transition. If the Process Engine has already timed out or canceled the subprocess, a later Run result or Tool Outcome is audit-only and cannot advance the token. A provider completion after a terminal Run is also audit-only and cannot start another model episode.

A retry of one failed Agent Tool is a Process Engine activity retry: the same Agent Run and Tool Call remain WAITING until their final typed Tool Outcome is returned. A safe provider retry stays inside the same Run and model episode but records another Provider Attempt. If the whole Agentic Subprocess reaches a terminal failure and its parent Outcome Mapping selects RETRY, the Process Engine starts a new linked Agent Run with a higher activity-attempt number. A terminal Run itself is never reopened, and all linked Runs consume the subprocess's aggregate retry, active-duration, and cost ceilings.

Completion

The normal AgentOutcome.RESULT path completes only when:

• the model returns a Final Outcome valid against the effective profile plus subprocess result contract;
• all dispatched activities have finished;
• no approval or external result is still pending;
• the deterministic completion rule is true;
• required evidence and verification are present.

The Final Outcome is mapped to selected parent-process variables. Conversation history and internal tool state are not copied to the parent. Every non-result Agent Outcome exits through its explicit Outcome Mapping instead of being treated as successful completion.

Errors and Incidents

Incident	Meaning
AGENT_CONFIGURATION_INVALID	Missing profile, schema, model policy, or invalid tool metadata
AGENT_CONTEXT_FAILED	Required context could not be loaded or authorized
AGENT_MODEL_FAILED	Model call exhausted its retry policy
AGENT_RESPONSE_INVALID	Response could not be repaired or validated
AGENT_TOOL_BATCH_REJECTED	The complete proposal violated a structural, identity, catalog, hash, or protocol invariant; no Tool Call executed
AGENT_TOOL_REJECTED	A structurally valid individual call was rejected by live enablement, authorization, repetition, risk, or business policy and returns a Tool Outcome
AGENT_TOOL_FAILED	Activity exhausted its own retry policy
AGENT_TOOL_EFFECT_INDETERMINATE	A mutating activity could not be reconciled to a known effect and requires review/incident handling
AGENT_APPROVAL_EXPIRED	Required approval was not completed before expiry
AGENT_LIMIT_EXCEEDED	A turn, tool, active-duration, token, cost, or repetition limit was reached
AGENT_RESULT_INVALID	Final Outcome does not satisfy the completion contract

The process may catch modeled business conditions and route to a User Task. Technical failures that cannot be handled in BPMN create an operator-visible incident.

Deployment Checks

Deployment validates that:

• the subprocess is ad-hoc and has a completion contract;
• every exposed activity has a unique Tool ID and typed input/output forms;
• the referenced Agent Profile exists, is currently valid, supports AGENTIC_SUBPROCESS, and is compatible with the certified Form, policy, Tool, privilege, and called-process references;
• write tools define idempotency and the required approval policy;
• every model-proposed batch contains independent calls only and has a complete-outcome barrier;
• parallel tools do not declare incompatible resource access;
• every model/tool loop and active-work/usage budget has a hard upper bound; an explicitly unbounded external wait has monitoring, cancellation, and escalation instead;
• an escalation or incident path exists;
• final outputs map to variables available outside the subprocess.

Related Documentation

• Agentic Process Automation
• Subprocesses
• Agent Task
• A2A Agent Task
• A2A Script Bindings
• tSM AI and Agent Runtime architecture