# Run and Track Workflows

Use the AI Studio SDK to execute deployed workflows and inspect results or control execution based on current run status. Save the run ID upon launch; subsequent operations identify the same execution using this ID.

(sdk-ai-studio-workflow-run-flow)=
## Task workflow

An execution sequentially passes through input preparation, launch submission, obtaining the run ID, querying current status, and reading results. The run ID serves as the correlation token between launching, querying, controlling, and retrieving outputs.

```text
Workspace + Deployed workflow + Run inputs
              │
              ▼
          Start run
              │
              ▼
       Run ID + Current status
         ├── Inspect run status and available actions
         ├── Read run results
         └── Suspend, resume, retry, or cancel
```

(sdk-ai-studio-workflow-run-prepare)=
## Prerequisites

| Required item | How to obtain | Role on this page |
| --- | --- | --- |
| Authenticated client | Created during initial setup. | Access AI Studio resources. |
| Workspace ID | Obtained from workspace creation, listing, or operator selection. | Define the resource scope of the workflow. |
| Deployed workflow ID | Obtained from workflow deployment results or operator selection. | Identify the workflow to launch. |
| Workflow inputs | Derived from the workflow's input definitions and runtime data. | Provide parameter values for this execution. |

This page does not deploy workflows or validate input schemas. If these are missing, obtain them via corresponding workflow management workflows first.

(sdk-ai-studio-workflow-run-start)=
## Start an execution

Upon submitting a run, the SDK returns the execution ID and current status. Preserve the run ID; request success does not imply that the workflow has reached a terminal state.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace("<workspace-id>")
workflow = workspace.workflow("<workflow-id>")
started = workflow.run(
    sdk.with_workflow_run_input(
        {"<input-field-id>": "<input-value>"}
    )
)

execution_id = started.workflow_run.execution_id
print(execution_id)
print(started.workflow_run.status)
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	workspace, err := client.Workspace("<workspace-id>")
	if err != nil {
		panic(err)
	}
	workflow, err := workspace.Workflow("<workflow-id>")
	if err != nil {
		panic(err)
	}
	started, err := workflow.Run(
		ctx,
		sdk.WithWorkflowRunInput(map[string]any{
			"<input-field-id>": "<input-value>",
		}),
	)
	if err != nil {
		panic(err)
	}

	executionID := started.GetWorkflowRun().GetExecutionId()
	fmt.Println(executionID)
	fmt.Println(started.GetWorkflowRun().GetStatus())
}
```

::::

:::::

(sdk-ai-studio-workflow-run-inspect)=
## Inspect the execution

Use the execution ID to query the current status, available actions, and error messages. The SDK does not provide generic polling or retry loops; application logic should determine polling intervals and branching based on returned states.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
run = workflow.run_handle(execution_id)
current = run.refresh()

print(current.execution.status)
print(current.execution.available_actions)
print(current.execution.error)
```

::::

::::{tab-item} Go
:sync: go

```go
run, err := workflow.RunHandle(executionID)
if err != nil {
	panic(err)
}
current, err := run.Refresh(ctx)
if err != nil {
	panic(err)
}

fmt.Println(current.GetExecution().GetStatus())
fmt.Println(current.GetExecution().GetAvailableActions())
fmt.Println(current.GetExecution().GetError())
```

::::

:::::

(sdk-ai-studio-workflow-run-result)=
## Read execution results

When output records are needed, use the same run handle to read results. The payload contains overall run status, case results, case errors, node statuses, and available actions. The overall workflow status cannot replace individual node statuses.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
result = run.result()

print(result.result.status)
print(result.result.case_result)
print(result.result.case_error)
```

::::

::::{tab-item} Go
:sync: go

```go
result, err := run.Result(ctx)
if err != nil {
	panic(err)
}

fmt.Println(result.GetResult().GetStatus())
fmt.Println(result.GetResult().GetCaseResult())
fmt.Println(result.GetResult().GetCaseError())
```

::::

:::::

(sdk-ai-studio-workflow-run-control)=
## Control execution

When status and available actions permit, you can suspend, resume, retry, or cancel the run. Retrying returns new run details; retain the new execution ID. Other control actions return updated state for the current run, which still requires verification.

| Goal | Operation result |
| --- | --- |
| Suspend or resume | Returns current run metadata. |
| Retry | Returns new execution metadata. |
| Cancel | Returns current run metadata. |

(sdk-ai-studio-workflow-run-next)=
## Next steps

- [View workflow artifacts and data lineage](查看工作流产物和数据血缘.md)
- [Create custom operators and workflow templates](自定义算子和工作流模板.md)
- [Publish and invoke WorkItem API services](WorkItem API 服务.md)