Agentic Subprocess

An Agentic Subprocess is a bounded ad-hoc BPMN scope in which an agent chooses from explicitly published child activities. The surrounding process defines the goal, permitted data, available activities, limits, approvals, timeout, 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 published 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 publishes it explicitly.

Subprocess Configuration

Property	Required	Description
Agent Profile	Yes	Exact published profile version containing instructions, model policy, base contracts, provider/tool policy, limits, data policy, and evaluation gates
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
Wall-clock Timeout	Yes	Maximum duration including waits and retries
Token and Cost Budgets	Yes	Aggregate limits for the complete Agent Run
Approval Policy	Yes	Risk classes that require confirmation or User Task approval
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 published 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
Timeout and Retry	Activity-specific execution 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 published definition's schema, risk, approval, limits, timeout, or retry policy but cannot relax it.

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. Resolve the run. Agent Runtime in tsm-ai pins the Agent Profile, model policy, context providers, tool contracts, completion contract, and budgets in the Agent Run.
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 proposals. Runtime validates the response schema and Tool arguments. The Process Engine enforces activity authorization, risk, repetition, concurrency, approval, and remaining process budgets before dispatch.
6. Approve when required. A protected proposal waits in a User Task containing its evidence, exact parameters, expected effect, expiry, and compensation information.
7. Execute activities. The Process Engine runs valid BPMN activities. Independent reads may run in parallel; conflicting or side-effecting operations are serialized.
8. Return observations. Every activity produces a structured Tool Outcome. The Process Engine correlates it to the run, and Agent Runtime persists it before scheduling the next turn.
9. 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 Call and Tool Outcome

A tool proposal has a stable call ID and typed parameters:

{
  "callId": "turn-3-call-1",
  "toolId": "inspectRecentAlarms",
  "arguments": {
    "serviceId": "SVC-100045",
    "periodMinutes": 30
  }
}

The activity returns a structured Tool Outcome:

{
  "callId": "turn-3-call-1",
  "status": "COMPLETED",
  "output": {
    "criticalAlarmCount": 2,
    "alarmIds": ["A-18", "A-21"]
  },
  "evidence": ["alarm:A-18", "alarm:A-21"],
  "changedResources": [],
  "retryable": false
}

The model observes the outcome, not unrestricted process state. Failed tools return a sanitized typed error; stack traces and secrets stay in operational logs.

Parallel Calls and Resource Conflicts

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 turn to reach a terminal state before building the next observation snapshot.

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, wall-clock, token, or cost limit. 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 hash. Changing parameters, target, tool version, or process authorization invalidates the decision and requires a new approval. Privileges are checked again immediately before execution.

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 proposals, 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.

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_REJECTED	Proposed tool or parameters violate policy
AGENT_TOOL_FAILED	Activity exhausted its own retry policy
AGENT_APPROVAL_EXPIRED	Required approval was not completed before expiry
AGENT_LIMIT_EXCEEDED	A turn, tool, 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;
• referenced profiles, forms, policies, privileges, and called process definitions have compatible published versions;
• write tools define idempotency and the required approval policy;
• parallel tools do not declare incompatible resource access;
• every loop and budget has a hard upper bound;
• 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