A2A Agent Task

An A2A Agent Task delegates one process activity to a registered remote agent through A2A Protocol 1.0. The embedded Process Engine owns the BPMN wait state, state/result mapping, and response listener. The outbound A2A client in tsm-ai owns transport and the durable local invocation view. The remote agent owns the authoritative A2A Task. tSM Gateway is not part of this outbound path; it is used for inbound Script MCP and A2A bindings.

Use it when the collaborating agent is independently operated, advertises an approved Agent Skill, and may require progress updates, additional input, authentication, Artifacts, or cancellation. Use an Agent Task when tsm-ai should perform one local model operation, or an Agentic Subprocess when tSM should coordinate a bounded local model-and-tool loop.

Core A2A Concepts

Concept	Use in an outbound process task
Agent Card	Discoverable identity, interfaces, Skills, capabilities, protocol versions, and security requirements
Agent Skill	Approved remote capability selected by stable Skill ID
Message	User/agent interaction composed of typed Parts
Part	Text, structured data, or file/reference carried by a Message or Artifact
Task	Stateful unit of work created and owned by the remote A2A server
taskId	Server-created opaque identifier for one remote Task
contextId	Server-created opaque grouping for related Tasks and Messages
Artifact	Validated Task output composed of Parts

tsm-ai stores remote identifiers in the Outbound A2A Invocation; the Process Engine references that record by a2aInvocationId. Any projected identifier is only a correlation value and never establishes tenant, user, authorization, business key, or process identity.

Agent Registry and Discovery

Every remote agent is onboarded through the tSM Agent Registry. The registry retrieves and pins the standard Agent Card, then applies enterprise trust and data-governance policy.

Registry property	Purpose
Code	Stable identifier used by process configuration
Discovery	Approved well-known Agent Card URL, curated card, or private registry source
Pinned Agent Card	Versioned card, selected interface, protocol version, and capability snapshot
Trust Policy	Allowed provider, domain, certificate/signature, and security scheme
Skills	Explicit allow-list of remote Agent Skill IDs
Invocation Mapping	Deterministic mapping from the selected Skill to a single-skill agent contract or a required remote routing extension
Authentication	Reference to OIDC, OAuth 2.0, mTLS, API-key, or HTTP-auth configuration
Tenant Mapping	Server-controlled local-to-remote tenant mapping
Data Policy	Allowed classifications, media types, sizes, regions, and retention
Runtime Limits	Deadline, retry, rate, concurrency, Message, and Artifact limits
Availability	Health policy, circuit breaker, rollout, and kill switch

A2A discovery normally starts with:

https://agent.example.com/.well-known/agent-card.json

The standard Agent Card declares supportedInterfaces, protocol versions, capabilities, security, input/output modes, and Skills. The tSM registry adds curated approval, version pinning, tenant mapping, and change control. A refreshed card can improve descriptive information; newly introduced endpoints, Skills, security schemes, or required extensions pass registry approval before use.

Skill Invocation Mapping

An Agent Skill ID is part of Agent Card discovery; the core A2A SendMessage request has no standard skillId field. The tSM Agent Registry therefore publishes an explicit Invocation Mapping for every approved Skill:

Mapping	Use
Single-skill agent contract	The pinned agent/interface exposes one unambiguous approved Skill; the configured Message and result contracts are checked against its advertised input/output modes.
Required routing extension	A multi-skill agent declares a required AgentExtension with a URI and metadata schema. The tsm-ai outbound client activates it and writes the selected Skill ID into its namespaced metadata.

For example, a remote agent can declare https://agent.example.com/extensions/skill-routing/v1 as required. The registry pins that declaration and its schema, and the tsm-ai outbound client builds:

{
  "extensions": [
    "https://agent.example.com/extensions/skill-routing/v1"
  ],
  "metadata": {
    "https://agent.example.com/extensions/skill-routing/v1": {
      "skillId": "resolve-service-incident"
    }
  }
}

Registration accepts a multi-skill remote agent only when the selected Skill has an unambiguous Invocation Mapping. This keeps Skill selection deterministic while allowing each remote agent to define its own extension URI and schema.

Configuration

Property	Required	Description
Remote Agent	Yes	Stable Agent Registry code
Agent Skill	Yes	Allowed Skill ID from the pinned Agent Card
Invocation Mapping	Inherited	Pinned single-skill contract or required routing extension from the Agent Registry
Goal / Message	Yes	Message template and mapped Parts
Input Mapping	Yes	Explicit process values mapped to text, data, file, or governed URL/reference Parts
Accepted Output Modes	Yes	Media types accepted from the remote agent
Initial Request	Yes	SendMessage or SendStreamingMessage
Update Delivery	Yes	Preferred stream, authenticated push, or bounded polling/reconciliation policy
Context Mapping	No	Existing contextId for a documented related interaction
State Mapping	Yes	Remote Task states mapped to a local status, variable mapping, lifecycle action, and permitted listener actions
State Response Listener	No	One expression or certified Script/delegate implementation; State Mapping is the sole source of trigger states and permitted actions
Listener Failure Policy	Conditional	Retry/incident behavior and maximum attempts when a State Response Listener is configured
Result Mapping	Yes	Artifact or direct-Message values mapped to typed process variables
Input-required Path	Yes	User Task, local Agent Task, or modeled Message path
Auth-required Path	Yes	Approval or credential-broker path
Deadline and Retry	Yes	Overall deadline, transport retries, polling, and circuit-breaker policy
Cancellation Policy	Yes	Remote cancel attempt, local timeout, and compensation behavior
Error Mapping	Yes	Protocol, contract, and transport outcomes mapped to BPMN errors or incidents

The process selects a registry entry rather than accepting a runtime URL expression. Authentication references remain server-side and are never stored in BPMN, Message Parts, or process variables.

Runtime Lifecycle

1. The Process Engine loads the deployed Agent Registry code, Skill, Invocation Mapping, state mapping, listener, and policy references.
2. Input Parts are authorized, schema-validated, scanned, and size-limited.
3. The engine persists a stable a2aInvocationId, messageId, BPMN wait state, and durable request before dispatch.
4. The tsm-ai outbound client creates or resumes the Outbound A2A Invocation; resolves and pins the Agent Card, interface, extension, tenant mapping, trust, authentication, and data policy; materializes the Invocation Mapping; and sends SendMessage with A2A-Version: 1.0. Durable poll/push execution uses returnImmediately: true. Streaming starts with SendStreamingMessage.
5. A direct Message is validated and may complete short work. A returned Task persists its remote taskId, contextId, state, interface, and agent identity in the local invocation projection; its initial snapshot is normalized and sequenced as the first state response.
6. The Process Engine consumes that initial response through the same mapping/listener pipeline as any later response. If it is non-terminal, the BPMN activity waits while tsm-ai accepts, validates, deduplicates, persists, and sequences updates from the configured delivery modes.
7. The Process Engine consumes every later update idempotently, computes the provisional State Mapping, invokes the optional listener, validates its result, and atomically commits the accepted update, variables, commands, and process action.
8. INPUT_REQUIRED and AUTH_REQUIRED activate their explicit process paths and continue with the same remote Task and context.
9. A terminal response is reconciled with the authoritative remote Task. Its Artifacts are validated and mapped before the process continues.

A stream accelerates delivery but is not the durable wait state. Local correlation and GetTask reconcile execution after a disconnect, duplicate callback, or restart.

Task State Mapping and Response Listener

tsm-ai normalizes every accepted remote update into a durable state response. The Process Engine maps that response to a local status and process action. These defaults are safe starting points:

A2A 1.0 state	Default local lifecycle action
TASK_STATE_UNSPECIFIED	Reconcile with GetTask; remain waiting and create A2A_UNMAPPED_STATE incident if the state cannot be resolved
TASK_STATE_SUBMITTED	Persist remote Task identity and WAIT
TASK_STATE_WORKING	Persist status/progress and WAIT
TASK_STATE_INPUT_REQUIRED	WAIT and start the configured information-collection path or listener reply flow
TASK_STATE_AUTH_REQUIRED	WAIT and start the configured approval or delegated-authentication path
TASK_STATE_COMPLETED	Validate Artifacts and result mapping, then COMPLETE
TASK_STATE_REJECTED	Throw the configured business error, default A2A_REJECTED
TASK_STATE_FAILED	Apply an explicit business mapping or create an incident
TASK_STATE_CANCELED	Follow the modeled cancellation, error, or compensation path

A direct Message is an immediate result path and is not converted to a synthetic Task state. INPUT_REQUIRED and AUTH_REQUIRED are interrupted states. Terminal Tasks are immutable and cannot accept another continuation.

State Mapping Configuration

Each configured state entry contains:

Field	Meaning
localStatus	Operator-facing status code stored for the activity
variableMapping	Schema-checked fields copied from status, Message, or Artifact references
action	Built-in WAIT, COMPLETE, BPMN_ERROR, or INCIDENT behavior
errorCode	Required for a BPMN_ERROR mapping
invokeListener	Whether the task's one configured State Response Listener runs for this state
allowedListenerActions	Subset of listener actions permitted for this state

Unknown future states never advance the process automatically. State enum order and remote timestamps are not used as an ordering mechanism: an interrupted Task can legitimately return to WORKING after a continuation. Conflicting or uncertain delivery is reconciled with GetTask.

A2A State Response Listener

An optional A2A State Response Listener runs after a normalized update has been persisted by tsm-ai and accepted by the Process Engine. It executes in the process-owning microservice because it needs process variables, certified Scripts, and the local transaction. It never runs inside a remote stream or callback transaction.

The listener uses the same expression/delegate configuration shape as other tSM listeners and is identified as a2aStateListener. One implementation and retry policy are configured on the task. For each state, State Mapping alone controls invokeListener and allowedListenerActions; there is no second listener-level state filter or action override. A certified Script receives the immutable update as #a2aUpdate:

Field	Meaning
schemaVersion	Version of the internal response contract
a2aInvocationId	Stable local outbound invocation identity
processDefinitionId, processInstanceId, activityInstanceId	Owning BPMN correlation
remoteAgentCode, agentCardVersion, skillId	Pinned target configuration
messageId, taskId, contextId	Local Message and opaque remote identifiers
previousState, state	Previously accepted and current A2A Task states
statusTimestamp, statusMessage	Validated remote status data
artifactRefs	Governed references to accepted Artifacts; never unrestricted payloads
deliveryMode	INITIAL, STREAM, PUSH, POLL, or RECONCILIATION
updateId, updateSequence	Locally assigned deduplication identity and order
receivedAt, deadline, listenerAttempt	Local timing and retry context

updateId and updateSequence are generated by tsm-ai; A2A status events do not provide a portable event identity or cross-delivery sequence.

Update Identity and Cross-delivery Deduplication

The same remote state can arrive through a stream, push callback, and later GetTask. tsm-ai keeps every raw delivery under a unique deliveryId for audit, but publishes a process update only when the canonical local Task projection changes:

1. Validate the delivery and apply its status, Message, and Artifact changes to the previous canonical projection. A reconciliation response replaces that projection with the verified GetTask snapshot.
2. Canonically serialize the observable projection: remote Task ID, state, status timestamp and Message/Part hashes, Artifact IDs/descriptors/checksums, and approved protocol metadata.
3. Compute snapshotFingerprint from that serialization. When a server supplies an approved stable event/revision extension, its value is included but never trusted as authorization.
4. Reuse the existing updateId when the fingerprint was already accepted. For a new fingerprint, assign the next updateSequence and derive a stable updateId from (a2aInvocationId, snapshotFingerprint).

Consequently, a repeated snapshot from another delivery mode cannot run the listener twice, while a new status message, timestamp, Artifact, or state creates a new update even when the state enum is unchanged. Two deliveries with no observable difference are intentionally one semantic update. Raw delivery attempts remain available for transport diagnostics.

An expression listener may return no value and only use outbox-safe local services. A Script or delegate can return this typed result:

{
  "action": "USE_MAPPING",
  "variables": {
    "remoteProgressText": "Validation completed"
  },
  "reply": null,
  "errorCode": null,
  "reason": "Progress recorded"
}

Listener action	Effect
USE_MAPPING	Keep the built-in state mapping action
WAIT	Remain at the activity after applying allowed variable mappings
REPLY	Write a durable continuation command with typed Parts for the same taskId/contextId
BPMN_ERROR	Throw an allow-listed business error code
INCIDENT	Keep the activity waiting and create an operator-visible incident
CANCEL	Write a durable CancelTask command and follow the configured cancellation mapping

REPLY is allowed only for configured interrupted states. The Process Engine commits it to its outbox; tsm-ai sends the continuation with a stable new messageId. Authentication challenges use a server-side credential broker/reference, never credentials in Message Parts.

The mapping restricts which listener actions are legal for each state. A listener cannot complete a non-terminal remote Task, fabricate a terminal state, skip Artifact/result validation, or bypass an approval. Processing order is fixed:

1. Deduplicate the response and lock the active BPMN activity.
2. Validate the state and referenced content, then compute the provisional mapping and variables; no process transition has happened yet.
3. Invoke the listener when invokeListener is enabled for that state.
4. Validate the listener action, variables, terminal-state rules, result contract, and approval.
5. Commit the update receipt, listener outcome, variable changes, outbox commands, and final process action in one transaction.

Listener retries reuse the same updateId; exhausted attempts create an incident while the BPMN activity remains waiting.

Messages, Parts, and Artifacts

An outbound Message contains a unique messageId, role, one or more Parts, and optional taskId/contextId for a continuation.

Part	tSM handling
Text	UTF-8 content with length, classification, and prompt-injection controls
Data	Structured value validated against the configured Form/JSON Schema
File	Size-limited content or an authorized governed-document reference

Task business outputs are read from Artifacts. Every Artifact is verified by media type, size, checksum, schema, caller access, malware policy, and retention policy before it becomes process data. Large inputs and outputs remain in governed document storage and are represented by stable references.

Multi-turn Interaction

• Continue an interrupted Task with its persisted taskId and contextId.
• Start permitted related work with an existing contextId and no taskId.
• Reject a continuation whose IDs do not match the local correlation.
• Apply context expiry and retention independently of process lifetime.
• Route caller input and delegated authentication through explicit modeled paths.

Credentials are exchanged through the configured credential broker or delegated-authentication flow, not through Message Parts.

Update Delivery and Recovery

Streaming

SendStreamingMessage and SubscribeToTask are available when the pinned Agent Card declares streaming. The stream carries state and Artifact updates. After reconnect, the tsm-ai client verifies the current state with GetTask.

Push notifications

Push is available when the Agent Card declares push notifications. The tsm-ai callback endpoint authenticates the sender, correlates tenant and Task, writes incoming updates to an idempotent inbox, and verifies the authoritative Task before publishing a state response. Callback endpoints are allow-listed and protected against SSRF, redirects, private-address access, and DNS rebinding.

Polling and reconciliation

Polling calls GetTask with bounded exponential backoff and jitter. It is the primary mode for agents without stream/push support and the recovery mode whenever delivery is uncertain. All modes update the same tsm-ai Outbound A2A Invocation; the remote server remains the Task authority.

Cancellation

An interrupting boundary event, process cancellation, or operator action writes a durable cancel command. The tsm-ai outbound client sends CancelTask for a non-terminal remote Task, reconciles the authoritative state, and returns the normalized outcome. The Process Engine follows the configured local cancellation, timeout, or compensation path. A cancellation request and a business rollback are separate modeled operations.

If the remote Task is already terminal or not cancelable, the process applies its configured race and compensation policy. Late updates remain in audit history and cannot reactivate a completed or canceled BPMN activity.

Errors, Retry, and Idempotency

Condition	Handling
Authentication challenge / AUTH_REQUIRED	Follow the approved delegated-authentication path
Forbidden or unsupported Skill, content, operation, extension, or version	Configuration or authorization incident
Task missing or inaccessible	Correlation/security incident
Invalid input, Message, reply, or Artifact	Contract incident unless an explicit repair path exists
Network timeout, rate limit, or temporary server failure	Bounded retry with backoff, circuit breaker, and stable messageId
Remote TASK_STATE_FAILED	Apply documented business mapping; otherwise create an incident
Delivery uncertainty	Reconcile with GetTask before retrying or continuing

A2A delivery is made safe with stable Message and command IDs, the Process Engine outbox/inbox, the tsm-ai invocation inbox/outbox and local update sequence, and authoritative Task lookup. Business side effects and listener integrations also use their own idempotency keys.

Security and Operations

• Use TLS and a security scheme declared by the pinned Agent Card.
• The tsm-ai client resolves targets through the tSM Agent Registry and sends A2A-Version: 1.0.
• Enforce tenant, Skill, Invocation Mapping, extension, media type, size, data-egress, rate, concurrency, and duration policy before dispatch and on every update.
• Treat remote Messages and Artifacts as untrusted content.
• Keep secrets in the credential service and sanitize internal errors before external delivery or model context.
• Audit registry/card versions, identity, interface, Skill, Message, remote state, Artifact, retry, approval, cancellation, and resulting business transition.

The process-instance Operations view correlates the BPMN activity with a2aInvocationId, local messageId, remote taskId/contextId, accepted update sequence, listener attempts, delivery attempts, current state, Artifacts, incidents, and result mapping. Local Agent Runs appear only when the process separately invokes tSM Agent Runtime; an Outbound A2A Invocation is a separate record.

Protocol Operations

Operation	Purpose
SendMessage	Start or continue an interaction
SendStreamingMessage	Start or continue while receiving real-time updates
GetTask	Read authoritative Task state, Artifacts, and permitted history
CancelTask	Request cancellation of a non-terminal Task
SubscribeToTask	Subscribe to an existing non-terminal Task stream
Push-notification configuration	Manage callback delivery for one Task
GetExtendedAgentCard	Retrieve identity-scoped additional capabilities

Standard References

• A2A Protocol 1.0 specification
• Agent discovery and Agent Cards
• Life of an A2A Task
• Streaming and asynchronous operations

Related Documentation

• Agentic Process Automation
• Agent Task
• Agentic Subprocess
• A2A Script Bindings
• tSM AI and Agent Runtime architecture
• Process Messaging
• Process Transactions