Skip to main content

Tasks

Tasks are user-owned work items, optionally recurring and scoped to an agent/app/workflow. Use this resource for CRUD plus lifecycle (complete, cancel, skip, end recurrence).

Access it as client.tasks on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate)  # filters: kind, status, include_completed, search_text, tags, trigger_type, due_only, linked_ids
for task in client.tasks.list():
    print(task.id)

Methods​

Core​

list​

list(*, kind: str | None = None, status: str | None = None, include_completed: bool | None = None, search_text: str | None = None, tags: Sequence[str] | None = None, trigger_type: str | None = None, due_only: bool | None = None, linked_ids: Sequence[str] | None = None, limit: int | None = None) -> SyncPaginator[Task]

List tasks with pagination and filters.

Parameters

  • kind (str | None, optional): recurring or oneoff.
  • status (str | None, optional): open | fired | done | failed | cancelled.
  • include_completed (bool | None, optional): Include done/failed/cancelled rows (default off).
  • search_text (str | None, optional): Substring match on description and notes.
  • tags (Sequence[str] | None, optional): Only tasks carrying all of these tags.
  • trigger_type (str | None, optional): heartbeat or scheduled.
  • due_only (bool | None, optional): Only tasks whose due time has arrived.
  • linked_ids (Sequence[str] | None, optional): Only tasks that belong to all of these agents and pools.
  • limit (int | None, optional): Maximum number of items to return (default: all matching items).

Returns

  • SyncPaginator[Task]: A paginator yielding Task objects.

create​

create(*, description: str, subject_ref: Mapping[str, Any] | None = None, due_at: str | None = None, notes: str | None = None, recurrence: Mapping[str, Any] | None = None, tags: Sequence[str] | None = None, trigger_type: str | None = None, linked_ids: Sequence[str] | None = None, created_by_agent: str | None = None, assigned_to_agent: str | None = None, shared_with: Sequence[str] | None = None, is_public: bool | None = None) -> Task

Create a task.

Recurring tasks (recurrence.kind != "none") get a computed next_due_at; one-off tasks use the provided due_at.

Parameters

  • description (str): What needs to be done (required).
  • subject_ref (Mapping[str, Any] | None, optional): Optional {kind, id, app?} pointer to the subject.
  • due_at (str | None, optional): ISO timestamp for one-off tasks.
  • notes (str | None, optional): Free-form notes.
  • recurrence (Mapping[str, Any] | None, optional): A recurrence dict, e.g. {kind, interval, time_of_day, ...}.
  • tags (Sequence[str] | None, optional): Tag labels.
  • trigger_type (str | None, optional): heartbeat (the agent completes it when it next wakes) or scheduled (the platform fires it at an exact time). Defaults: a cron recurrence is scheduled, anything else heartbeat.
  • linked_ids (Sequence[str] | None, optional): Agents and pools (ids) the task belongs to.
  • created_by_agent (str | None, optional): Id of the agent that created the task.
  • assigned_to_agent (str | None, optional): A label a Task Due workflow trigger can filter on (exact match). Agents work the tasks linked to them (linked_ids).
  • shared_with (Sequence[str] | None, optional): User ids to share the task with on creation.
  • is_public (bool | None, optional): Whether the task is publicly visible.

Returns

  • Task: The created Task.

retrieve​

retrieve(task_id: str) -> Task

Retrieve a single task by id.

update​

update(task_id: str, *, description: str | None = None, subject_ref: Mapping[str, Any] | None = None, due_at: str | None = None, notes: str | None = None, recurrence: Mapping[str, Any] | None = None, tags: Sequence[str] | None = None, trigger_type: str | None = None, assigned_to_agent: str | None = None, linked_ids: Sequence[str] | None = None, clear_due_at: bool | None = None, clear_assigned_to_agent: bool | None = None, clear_subject_ref: bool | None = None) -> Task

Update a task: only the arguments given change.

Changing recurrence recomputes next_due_at; {"kind": "none"} stops it repeating. linked_ids replaces the agents and pools the task belongs to. clear_due_at, clear_assigned_to_agent and clear_subject_ref remove those fields. To finish or cancel a task use complete or cancel.

delete​

delete(task_id: str) -> None

Delete a task (hard delete). Raises on failure; returns nothing.

Lifecycle & actions​

cancel​

cancel(task_id: str, *, reason: str | None = None) -> Task

Cancel a task (sets status cancelled). Optional reason.

complete​

complete(task_id: str, *, notes: str | None = None, execution_id: str | None = None) -> Task

Mark a task complete and return the updated task.

Recurring tasks advance to the next due instant; one-off tasks transition to done.

Parameters

  • task_id (str): Target task id.
  • notes (str | None, optional): Optional completion notes.
  • execution_id (str | None, optional): Workflow execution that completed the task.

skip_next​

skip_next(task_id: str) -> Task

Skip the next scheduled fire on a recurring task.

end_recurrence​

end_recurrence(task_id: str) -> Task

Stop recurrence on a recurring task (history is preserved).

Other​

add_member​

add_member(resource_id: str, *, user_id: str, role: str) -> Permissions

Share the resource with a user.

Parameters

  • resource_id (str): The resource's id.
  • user_id (str): The user to share it with.
  • role (str): "editor" (use and change it) or "user" (use it only; types without a use-only tier, such as knowledge bases, take "editor" only).

claim​

claim(task_id: str, *, claimant_id: str) -> Task

Claim a task's current occurrence before working it, so two agents never both do.

Returns the task, its claimed_by you, when you won it (claiming again as the winner returns it again).

Parameters

  • claimant_id (str): Your agent's id.

Raises

  • ConflictError: Another agent holds this occurrence (skip it); the message names it.

permissions​

permissions(resource_id: str) -> Permissions

Return who can reach the resource: its owner, members and their roles, and visibility.

Parameters

  • resource_id (str): The resource's id.

remove_member​

remove_member(resource_id: str, user_id: str) -> None

Stop sharing the resource with a user.

Parameters

  • resource_id (str): The resource's id.
  • user_id (str): The user to stop sharing it with.

set_visibility​

set_visibility(resource_id: str, visibility: str) -> Permissions

Make the resource public (every user can find and use it) or private.

Parameters

  • resource_id (str): The resource's id.
  • visibility (str): "public" or "private".