> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Create, update, and deploy workflows (mgmt.workflows).

### WorkflowsResource

```python
class WorkflowsResource(http: HttpClient, config: ModusConfig, ops: ManagementWorkflowsOperations = ManagementWorkflowsOperations(list='WorkflowsController_list', get='WorkflowsController_get', create='WorkflowsController_create', update='WorkflowsController_update', deploy='WorkflowsController_deploy', delete='WorkflowsController_delete', restore='WorkflowsController_restore', request_ownership_transfer='WorkflowsController_requestOwnershipTransfer', cancel_ownership_transfer='WorkflowsController_cancelOwnershipTransfer', accept_ownership_transfer='WorkflowsController_acceptOwnershipTransfer', toggle='WorkflowsController_toggle'))
```

Bases: `object`

Full CRUD access to Modus workflows.

mgmt.workflows.list() → Page\[Agent] mgmt.workflows.get(workflow\_id) → Agent (with variation fields) mgmt.workflows.create(name, type) → Agent mgmt.workflows.update(workflow\_id, ..) → Agent mgmt.workflows.deploy(workflow\_id) → Agent mgmt.workflows.delete(workflow\_id) → None

#### list()

```python
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 all Modus workflows in the organisation.

* Parameters:

  * **page\_size** – Maximum number of items to return (default 25).

  * **page\_token** – Token from a previous page’s `next_page_token`; omit for the first page.

  * **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()

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

Retrieve a Modus workflow with full configuration.

#### interfaces()

```python
interfaces(workflow_id: int | str) → WorkflowInterfacesResource
```

Return the interfaces sub-resource scoped to `workflow_id`.

#### create()

```python
create(name: str, type: AgentType, *, description: str | None = None, trigger: TriggerInput | None = None, agent_selection: AgentSelectionInput | None = None, workflow_structure: WorkflowGraphInput | None = None, guardrails: List[str] | None = None) → Agent
```

Create a new Modus workflow.

* Parameters:

  * **name** – Display name for the workflow.

  * **type** – `"task"` for single-step skill orchestration, or `"workflow"` for a multi-step graph.

  * **guardrails** – Runtime guardrail labels (for example `"no-pii"`). When set, the workflow is created with these labels under the organisation default sharing rules. Omit (`None`) to create with no guardrails. ACL fields cannot be set from the SDK.

#### update()

```python
update(workflow_id: int | str, *, name: str | None = None, type: AgentType | None = None, description: str | None = None, trigger: TriggerInput | None = None, agent_selection: AgentSelectionInput | None = None, workflow_structure: WorkflowGraphInput | None = None, guardrails: List[str] | None = None, update_mask: str | None = None) → Agent
```

Update a Modus workflow’s configuration.

Only the fields you pass are changed. To clear a field, name it in `update_mask` (a comma-separated list of field names) and leave its argument unset — the server sets each masked field to null and leaves fields not named in the mask untouched.

* Parameters:

  **guardrails** – Runtime guardrail labels to set on the workflow. Fetches the current workflow first and merges these labels into its access configuration (an extra `get` request). Omit (`None`) to leave guardrails unchanged. Pass `[]` to clear all guardrails.

#### deploy()

```python
deploy(workflow_id: int | str) → WorkflowDto
```

Publish the current draft of a Modus workflow.

* Parameters:

  **workflow\_id** – Workflow to publish.

* Returns:

  The workflow with its newly published configuration.

#### toggle()

```python
toggle(workflow_id: int | str, *, active: bool) → WorkflowDto
```

Enable or disable a workflow.

#### delete()

```python
delete(workflow_id: int | str) → None
```

Delete a Modus workflow.

* Parameters:

  **workflow\_id** – Workflow to remove.

#### request\_ownership\_transfer()

```python
request_ownership_transfer(workflow_id: int | str, *, new_owner_user_id: str) → WorkflowDto
```

Start transferring ownership of a workflow to another organisation member.

#### cancel\_ownership\_transfer()

```python
cancel_ownership_transfer(workflow_id: int | str) → WorkflowDto
```

Cancel a pending workflow ownership transfer.

#### accept\_ownership\_transfer()

```python
accept_ownership_transfer(workflow_id: int | str) → WorkflowDto
```

Accept a pending workflow ownership transfer.

#### restore()

```python
restore(workflow_id: int | str) → WorkflowDto
```

Restore a deleted workflow.

### AsyncWorkflowsResource

```python
class AsyncWorkflowsResource(http: AsyncHttpClient, config: ModusConfig, ops: ManagementWorkflowsOperations = ManagementWorkflowsOperations(list='WorkflowsController_list', get='WorkflowsController_get', create='WorkflowsController_create', update='WorkflowsController_update', deploy='WorkflowsController_deploy', delete='WorkflowsController_delete', restore='WorkflowsController_restore', request_ownership_transfer='WorkflowsController_requestOwnershipTransfer', cancel_ownership_transfer='WorkflowsController_cancelOwnershipTransfer', accept_ownership_transfer='WorkflowsController_acceptOwnershipTransfer', toggle='WorkflowsController_toggle'))
```

Bases: `object`

#### list()

```python
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 all Modus workflows in the organisation.

* Parameters:

  * **page\_size** – Maximum number of items to return (default 25).

  * **page\_token** – Token from a previous page’s `next_page_token`; omit for the first page.

  * **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()

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

Retrieve a Modus workflow with full configuration.

#### interfaces()

```python
interfaces(workflow_id: int | str) → AsyncWorkflowInterfacesResource
```

Return the interfaces sub-resource scoped to `workflow_id`.

#### create()

```python
async create(name: str, type: AgentType, *, description: str | None = None, trigger: TriggerInput | None = None, agent_selection: AgentSelectionInput | None = None, workflow_structure: WorkflowGraphInput | None = None, guardrails: List[str] | None = None) → Agent
```

Create a new Modus workflow.

* Parameters:

  * **name** – Display name for the workflow.

  * **type** – `"task"` for single-step skill orchestration, or `"workflow"` for a multi-step graph.

  * **guardrails** – Runtime guardrail labels (for example `"no-pii"`). When set, the workflow is created with these labels under the organisation default sharing rules. Omit (`None`) to create with no guardrails. ACL fields cannot be set from the SDK.

#### update()

```python
async update(workflow_id: int | str, *, name: str | None = None, type: AgentType | None = None, description: str | None = None, trigger: TriggerInput | None = None, agent_selection: AgentSelectionInput | None = None, workflow_structure: WorkflowGraphInput | None = None, guardrails: List[str] | None = None, update_mask: str | None = None) → Agent
```

Update a Modus workflow’s configuration.

Only the fields you pass are changed. To clear a field, name it in `update_mask` (a comma-separated list of field names) and leave its argument unset — the server sets each masked field to null and leaves fields not named in the mask untouched.

* Parameters:

  **guardrails** – Runtime guardrail labels to set on the workflow. Fetches the current workflow first and merges these labels into its access configuration (an extra `get` request). Omit (`None`) to leave guardrails unchanged. Pass `[]` to clear all guardrails.

#### deploy()

```python
async deploy(workflow_id: int | str) → WorkflowDto
```

Publish the current draft of a Modus workflow. See the sync `deploy` for argument details.

#### toggle()

```python
async toggle(workflow_id: int | str, *, active: bool) → WorkflowDto
```

Enable or disable a workflow. See the sync `toggle` for argument details.

#### delete()

```python
async delete(workflow_id: int | str) → None
```

Delete a Modus workflow. See the sync `delete` for argument details.

#### request\_ownership\_transfer()

```python
async request_ownership_transfer(workflow_id: int | str, *, new_owner_user_id: str) → WorkflowDto
```

Start transferring ownership of a workflow to another organisation member.

#### cancel\_ownership\_transfer()

```python
async cancel_ownership_transfer(workflow_id: int | str) → WorkflowDto
```

Cancel a pending workflow ownership transfer.

#### accept\_ownership\_transfer()

```python
async accept_ownership_transfer(workflow_id: int | str) → WorkflowDto
```

Accept a pending workflow ownership transfer.

#### restore()

```python
async restore(workflow_id: int | str) → WorkflowDto
```

Restore a deleted workflow.

### WorkflowInterfacesResource

```python
class WorkflowInterfacesResource(http: HttpClient, config: ModusConfig, workflow_id: int | str)
```

Bases: `object`

#### list()

```python
list() → list[AgentInterfaceDto]
```

List interfaces attached to this workflow.

#### create()

```python
create(interface: AddAgentInterfaceDto | Mapping[str, Any]) → AgentInterfaceDto
```

Add an interface to this workflow.

* Parameters:

  **interface** – Interface configuration to attach, as a DTO or plain mapping.

#### update()

```python
update(interface_id: str, interface: UpdateAgentInterfaceDto, *, update_mask: str | None = None) → AgentInterfaceDto
```

Update an interface attached to this workflow.

#### delete()

```python
delete(interface_id: str) → None
```

Delete an interface from this workflow.

#### delete\_all()

```python
delete_all() → None
```

Delete every interface from this workflow.

### AsyncWorkflowInterfacesResource

```python
class AsyncWorkflowInterfacesResource(http: AsyncHttpClient, config: ModusConfig, workflow_id: int | str)
```

Bases: `object`

#### list()

```python
async list() → list[AgentInterfaceDto]
```

List interfaces attached to this workflow.

#### create()

```python
async create(interface: AddAgentInterfaceDto | Mapping[str, Any]) → AgentInterfaceDto
```

Add an interface to this workflow.

* Parameters:

  **interface** – Interface configuration to attach, as a DTO or plain mapping.

#### update()

```python
async update(interface_id: str, interface: UpdateAgentInterfaceDto, *, update_mask: str | None = None) → AgentInterfaceDto
```

Update an interface attached to this workflow.

* Parameters:

  * **interface\_id** – Identifier of the interface to update.

  * **interface** – Updated interface values.

  * **update\_mask** – Optional comma-separated list of fields to update.

#### delete()

```python
async delete(interface_id: str) → None
```

Delete an interface from this workflow.

* Parameters:

  **interface\_id** – Identifier of the interface to delete.

#### delete\_all()

```python
async delete_all() → None
```

Delete every interface from this workflow.