Workflows - Modus Docs

WorkflowsResource

class WorkflowsResource(http: ~modus._http.HttpClient, agent_http: ~modus._http.HttpClient, config: ~modus._config.ModusConfig, ops: ~modus.resources.workflows.workflows.WorkflowsOperations = WorkflowsOperations(list='WorkflowsController_list', get='WorkflowsController_get', runs=RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'), stream_session=<function workflow_stream_session>, stream_session_async=<function workflow_stream_session_async>))

Bases: object Read access to Modus workflows. client.workflows.list() → Page[Agent] client.workflows.get(workflow_id) → Agent To create, update, or deploy workflows use modus.management.ModusManagement.

list()

list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, type: AgentType | None = None, view: Literal['active', 'draft'] | None = None, include_variation: bool | None = None) → Page[WorkflowDto]

List workflows in the organisation.

Parameters:
- page_size – Items per page (default 25).
- page_token – Opaque token from a previous page’s next_page_token.
- search – Case-insensitive substring filter on the workflow name.
- type – Filter by workflow type: "task" or "workflow".
- view – Variation view — "active" (deployed) or "draft".
- include_variation – Include variation payload on each list row.

get()

get(workflow_id: int | str, *, view: Literal['active', 'draft'] | None = None) → WorkflowDto

Retrieve a workflow by ID or slug.

Parameters: view – Variation view — "active" (deployed) or "draft".
Raises: NotFoundError – if no workflow with this ID/slug exists.

chat_stream()

chat_stream(workflow_id: int | str, message: str, *, model: str, thread_id: str | None = None, version: Literal['published', 'draft'] | str | None = None) → ChatStream

Send a message to a workflow and stream the reply token by token.

Parameters:
- workflow_id – Workflow ID or slug.
- message – The message to send.
- model – Model to run this message with (required). One of the supported model IDs, e.g. "claude-sonnet-5" or "gpt-5.5".
- thread_id – Continue an existing conversation; omit to start a new one.
- version – Run a specific variation — "published" or "draft".
Returns: ChatStream you can iterate for text chunks; the final result carries the thread_id.

AsyncWorkflowsResource

class AsyncWorkflowsResource(http: ~modus._http.AsyncHttpClient, agent_http: ~modus._http.AsyncHttpClient, config: ~modus._config.ModusConfig, ops: ~modus.resources.workflows.workflows.WorkflowsOperations = WorkflowsOperations(list='WorkflowsController_list', get='WorkflowsController_get', runs=RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'), stream_session=<function workflow_stream_session>, stream_session_async=<function workflow_stream_session_async>))

Bases: object Async read access to Modus workflows. await client.workflows.list() → AsyncPage[Agent] await client.workflows.get(workflow_id) → Agent To create, update, or deploy workflows use modus.management.ModusManagement.

list()

async list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, type: AgentType | None = None, view: Literal['active', 'draft'] | None = None, include_variation: bool | None = None) → AsyncPage[WorkflowDto]

List workflows in the organisation.

Parameters:
- page_size – Items per page (default 25).
- page_token – Opaque token from a previous page’s next_page_token.
- search – Case-insensitive substring filter on the workflow name.
- type – Filter by workflow type: "task" or "workflow".
- view – Variation view — "active" (deployed) or "draft".
- include_variation – Include variation payload on each list row.

get()

async get(workflow_id: int | str, *, view: Literal['active', 'draft'] | None = None) → WorkflowDto

Retrieve a workflow by ID or slug.

Parameters: view – Variation view — "active" (deployed) or "draft".
Raises: NotFoundError – if no workflow with this ID/slug exists.

chat_stream()

chat_stream(workflow_id: int | str, message: str, *, model: str, thread_id: str | None = None, version: Literal['published', 'draft'] | str | None = None) → AsyncChatStream

Send a message to a workflow and stream the reply token by token.

Parameters:
- workflow_id – Workflow ID or slug.
- message – The message to send.
- model – Model to run this message with (required). One of the supported model IDs, e.g. "claude-sonnet-5" or "gpt-5.5".
- thread_id – Continue an existing conversation; omit to start a new one.
- version – Run a specific variation — "published" or "draft".
Returns: AsyncChatStream you can iterate for text chunks; the final result carries the thread_id.

WorkflowRunsResource

class WorkflowRunsResource(http: HttpClient, config: ModusConfig, ops: RunOperations = RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'))

Bases: object

list()

list(workflow_id: int | str, *, page_size: int = 25, page_token: str | None = None, status: Literal['running', 'awaiting_human', 'completed', 'error', 'cancelled', 'all_executions'] | str | None = None, timeframe: Literal['last_hour', 'last_day', 'last_week'] | str | None = None, approval_scope: Literal['mine', 'all'] | str | None = None, search: str | None = None) → Page[AutomationRunListItemDto]

List runs for a workflow.

Parameters:
- workflow_id – Workflow ID or slug.
- page_size – Maximum number of items to return (default 25, max 100).
- page_token – Token from a previous page’s next_page_token; omit for the first page.
- status – Filter by run status (e.g. "running", "awaiting_human", "completed", "error", "cancelled", "all_executions").
- timeframe – Filter by time window (e.g. "last_hour", "last_day", "last_week").
- approval_scope – When status="awaiting_human", scope to "mine" or "all".
- search – Free-text search filter.

active()

active(*, page_size: int = 50, page_token: str | None = None) → Page[ActiveConversationRunDto]

List active conversation runs for the current user.

Parameters:
- page_size – Maximum number of active runs to return (default 50, max 100).
- page_token – Token from a previous page’s next_page_token; omit for the first page.

active_by_session()

active_by_session(session_ids: Sequence[str]) → List[ActiveConversationRunDto]

Return active runs for the supplied conversation thread ids.

Parameters: session_ids – Conversation thread ids to check; blanks and duplicates are ignored.

get()

get(workflow_id: int | str, run_id: str, *, temporal_run_id: str | None = None) → GetAutomationRunResponseDto

Retrieve a Modus workflow run by ID.

Parameters:
- workflow_id – Modus workflow ID or slug.
- run_id – Run ID.
- temporal_run_id – Optional Temporal run ID when disambiguating.

create()

create(workflow_id: int | str, body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Start a workflow run and stream its events.

Parameters:
- workflow_id – Workflow ID or slug.
- body – Run request fields such as message, sessionId, config, and runId.

create_scope()

create_scope(scope_id: int | str, body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Start a scope run and stream its events.

Parameters:
- scope_id – Scope ID or slug.
- body – Run request fields such as message, sessionId, config, and runId.

create_modus()

create_modus(body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Start a Modus run and stream its events.

Parameters: body – Run request fields such as message, sessionId, config, and runId.

resume()

resume(run_id: str, body: Mapping[str, Any]) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Resume a paused run and stream its events.

Parameters:
- run_id – Run ID to resume.
- body – Resume request fields including the decision and message.

cancel()

cancel(run_id: str, body: Mapping[str, Any] | None = None) → None

Cancel a run.

Parameters:
- run_id – Run ID to cancel.
- body – Optional cancellation details.

interrupt()

interrupt(run_id: str, body: Mapping[str, Any] | None = None) → None

Interrupt a run.

Parameters:
- run_id – Run ID to interrupt.
- body – Optional interruption details.

edit_queued()

edit_queued(run_id: str, body: Mapping[str, Any] | None = None) → None

Edit a queued run.

Parameters:
- run_id – Run ID to edit.
- body – Optional queued-run edit details.

events()

events(run_id: str) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Stream run lifecycle events.

Parameters: run_id – Run ID to follow.

stream()

stream(run_id: str) → Iterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Stream run output events.

Parameters: run_id – Run ID to follow.

AsyncWorkflowRunsResource

class AsyncWorkflowRunsResource(http: AsyncHttpClient, config: ModusConfig, ops: RunOperations = RunOperations(list='WorkflowRunsController_list', get='WorkflowRunsController_get', active='RunLifecycleController_active', active_by_session='RunLifecycleController_activeBySession', create='WorkflowRunsController_create', create_scope='ScopeRunsController_create'))

Bases: object

list()

async list(workflow_id: int | str, *, page_size: int = 25, page_token: str | None = None, status: Literal['running', 'awaiting_human', 'completed', 'error', 'cancelled', 'all_executions'] | str | None = None, timeframe: Literal['last_hour', 'last_day', 'last_week'] | str | None = None, approval_scope: Literal['mine', 'all'] | str | None = None, search: str | None = None) → AsyncPage[AutomationRunListItemDto]

List runs for a workflow.

Parameters:
- workflow_id – Workflow ID or slug.
- page_size – Maximum number of items to return (default 25, max 100).
- page_token – Token from a previous page’s next_page_token; omit for the first page.
- status – Filter by run status (e.g. "running", "awaiting_human", "completed", "error", "cancelled", "all_executions").
- timeframe – Filter by time window (e.g. "last_hour", "last_day", "last_week").
- approval_scope – When status="awaiting_human", scope to "mine" or "all".
- search – Free-text search filter.

active()

async active(*, page_size: int = 50, page_token: str | None = None) → AsyncPage[ActiveConversationRunDto]

List active conversation runs for the current user.

Parameters:
- page_size – Maximum number of active runs to return (default 50, max 100).
- page_token – Token from a previous page’s next_page_token; omit for the first page.

active_by_session()

async active_by_session(session_ids: Sequence[str]) → List[ActiveConversationRunDto]

Return active runs for the supplied conversation thread ids.

Parameters: session_ids – Conversation thread ids to check; blanks and duplicates are ignored.

get()

async get(workflow_id: int | str, run_id: str, *, temporal_run_id: str | None = None) → GetAutomationRunResponseDto

Retrieve a Modus workflow run by ID.

Parameters:
- workflow_id – Modus workflow ID or slug.
- run_id – Run ID.
- temporal_run_id – Optional Temporal run ID when disambiguating.

create()

async create(workflow_id: int | str, body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Start a workflow run and stream its events.

Parameters:
- workflow_id – Workflow ID or slug.
- body – Run request fields such as message, sessionId, config, and runId.

create_scope()

async create_scope(scope_id: int | str, body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Start a scope run and stream its events.

Parameters:
- scope_id – Scope ID or slug.
- body – Run request fields such as message, sessionId, config, and runId.

create_modus()

async create_modus(body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Start a Modus run and stream its events.

Parameters: body – Run request fields such as message, sessionId, config, and runId.

resume()

async resume(run_id: str, body: Mapping[str, Any]) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Resume a paused run and stream its events.

Parameters:
- run_id – Run ID to resume.
- body – Resume request fields including the decision and message.

cancel()

async cancel(run_id: str, body: Mapping[str, Any] | None = None) → None

Cancel a run.

Parameters:
- run_id – Run ID to cancel.
- body – Optional cancellation details.

interrupt()

async interrupt(run_id: str, body: Mapping[str, Any] | None = None) → None

Interrupt a run.

Parameters:
- run_id – Run ID to interrupt.
- body – Optional interruption details.

edit_queued()

async edit_queued(run_id: str, body: Mapping[str, Any] | None = None) → None

Edit a queued run.

Parameters:
- run_id – Run ID to edit.
- body – Optional queued-run edit details.

events()

async events(run_id: str) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Stream run lifecycle events.

Parameters: run_id – Run ID to follow.

stream()

async stream(run_id: str) → AsyncIterator[TokenEvent | DoneEvent | ErrorEvent | CancelledEvent | StreamTimeoutEvent | AssistantContentResetEvent]

Stream run output events.

Parameters: run_id – Run ID to follow.

​WorkflowsResource

​list()

​get()

​chat_stream()

​AsyncWorkflowsResource

​list()

​get()

​chat_stream()

​WorkflowRunsResource

​list()

​active()

​active_by_session()

​get()

​create()

​create_scope()

​create_modus()

​resume()

​cancel()

​interrupt()

​edit_queued()

​events()

​stream()

​AsyncWorkflowRunsResource

​list()

​active()

​active_by_session()

​get()

​create()

​create_scope()

​create_modus()

​resume()

​cancel()

​interrupt()

​edit_queued()

​events()

​stream()

WorkflowsResource

list()

get()

chat_stream()

AsyncWorkflowsResource

list()

get()

chat_stream()

WorkflowRunsResource

list()

active()

active_by_session()

get()

create()

create_scope()

create_modus()

resume()

cancel()

interrupt()

edit_queued()

events()

stream()

AsyncWorkflowRunsResource

list()

active()

active_by_session()

get()

create()

create_scope()

create_modus()

resume()

cancel()

interrupt()

edit_queued()

events()

stream()