feat(action-center): extend taskSourceMetadata on CreateTask/CreateEscalation

[dushyant-uipath]

Summary

• Changes: CreateTask/CreateEscalation get one new optional field, task_source_metadata: dict[str, Any] | None. Its keys merge into taskSource.taskSourceMetadata on the created task, alongside the SDK's own InstanceId/FolderKey/JobKey/ProcessKey. Caller keys win on collision.
• Does not change: every existing call to CreateTask, CreateEscalation, TasksService.create, and TasksService.create_async behaves exactly as before. The field defaults to None and is keyword-only.
• What it's for: a coded agent that creates its own Action Center escalation (Verticals' decision-router, ACTN-123, see vertical-solution-purchase-order-intake#402) has no field on CreateTask to attach custom context, e.g. a conversational-agent id, to the task it creates. taskSourceMetadata already carries correlation ids (InstanceId, FolderKey, JobKey, ProcessKey); this makes it extensible.

Problem

taskSource.taskSourceMetadata is assembled inside _apply_task_source (action_center/_tasks_service.py) from UiPathConfig state. CreateTask's other fields (data, actionable_message_metadata, labels, etc.) each map onto a parameter of _create_spec; taskSourceMetadata does not, since it is built entirely from UiPathConfig rather than from a CreateTask field.

How it's used

sequenceDiagram
    participant Agent as decision-router (coded agent)
    participant Trig as UiPathResumeTriggerCreator
    participant Tasks as TasksService.create_async
    participant Orch as Orchestrator (CreateAppTask)
    participant Plugins as Plugins service

    Agent->>Agent: interrupt(CreateEscalation(task_source_metadata={"ConversationalAgentId": id}))
    Agent->>Trig: job suspends on the CreateEscalation value
    Trig->>Tasks: create_async(..., task_source_metadata=value.task_source_metadata)
    Tasks->>Orch: POST taskSource.taskSourceMetadata = {InstanceId, FolderKey, JobKey, ProcessKey, ConversationalAgentId}
    Orch-->>Plugins: task record carries taskSource.taskSourceMetadata
    Plugins->>Plugins: reads ConversationalAgentId, attaches the conversational agent to the actionable card

Loading

Changes

• common/interrupt_models.py: new task_source_metadata field on CreateTask.
• resume_triggers/_protocol.py: _handle_task_trigger passes value.task_source_metadata into the tasks.create_async(...) call it makes when a job suspends on CreateTask/CreateEscalation. Without this, a value set on the interrupt object would never reach the API call.
• action_center/_tasks_service.py: TasksService.create/create_async accept task_source_metadata, pass it to _create_spec, which passes it to _apply_task_source, where it merges into taskSourceMetadata. Takes effect only when taskSource itself is populated (UiPathConfig.project_id and trace_id both set), documented on both methods.
• sonar-project.properties: scoped a python:S107 (too-many-parameters) exclusion to _tasks_service.py. _create_spec/create/create_async were already at Sonar's 13-parameter limit before this field; collapsing them into an options object is a separate, larger refactor across this file's whole public API.

Test plan

• test_create_merges_task_source_metadata, test_create_async_merges_task_source_metadata, test_create_omits_extra_task_source_metadata_when_unset, test_create_task_source_metadata_overrides_a_built_in_key_on_collision in packages/uipath-platform/tests/services/test_actions_service.py.
• Not run locally. CI runs pytest across packages/uipath-platform, including the tests above.

[Copilot]

🟡 Changes recommended

A few small but user-facing issues remain (metadata merge can raise an opaque TypeError on invalid keys, collision behavior isn’t asserted, and docs should clarify when taskSource is populated).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Extends the Action Center task creation surface so callers of CreateTask / CreateEscalation (including resume-trigger flows) can attach arbitrary additional key/value context into taskSource.taskSourceMetadata, merged on top of the SDK’s built-in correlation keys.

Changes:

• Added task_source_metadata to the CreateTask interrupt model and threaded it through resume triggers into TasksService.create/create_async.
• Extended task request spec building to merge caller-provided metadata into taskSource.taskSourceMetadata (caller wins on collision).
• Added tests to validate metadata merging behavior and bumped uipath-platform version.

File summaries

File	Description
packages/uipath-platform/src/uipath/platform/common/interrupt_models.py	Adds task_source_metadata to CreateTask (inherited by CreateEscalation).
packages/uipath-platform/src/uipath/platform/resume_triggers/_protocol.py	Passes interrupt-provided task_source_metadata into tasks.create_async(...).
packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py	Plumbs task_source_metadata through create/create_async into request payload taskSourceMetadata.
packages/uipath-platform/tests/services/test_actions_service.py	Adds tests covering merge/omit behavior for extra task-source metadata.
packages/uipath-platform/tests/services/test_hitl.py	Updates interrupt construction to include the new field in the test setup.
packages/uipath-platform/pyproject.toml	Bumps package version to 0.2.24.
packages/uipath-platform/uv.lock	Updates lockfile version entry for uipath-platform.

Review details

Suppressed comments (1)

packages/uipath-platform/src/uipath/platform/action_center/_tasks_service.py:627

• Same as create_async: task_source_metadata is ignored unless _apply_task_source populates the taskSource block (requires UiPathConfig.project_id and UiPathConfig.trace_id). Adding that note here would prevent confusion for callers.

            task_source_metadata: Optional extra keys merged into taskSource.taskSourceMetadata,
                on top of the built-in InstanceId/FolderKey/JobKey/ProcessKey (e.g. a
                conversational-agent id a HITL task should carry downstream)

• Files reviewed: 6/8 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
1.7% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🚨 Heads up: uipath-langchain cross-tests are FAILING 🚨

Your changes may break the uipath-langchain-python integration.

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →