# 发布工作流 API 服务

将工作流发布为动态 API 服务（`dynamic_service`），并绑定工作区卷中的 HTML 交互页面，供支持 MCP Apps 的客户端调用和渲染。

(sdk-ai-studio-workflow-service-flow)=
## 任务流程

1. 将交互页面 HTML 文件上传到工作区数据卷，取得文件 ID（`HTML_FILE_ID`）。
2. 准备已验证的原生 MOWL 工作流定义文件，以及与工作流输入输出一致的 JSON Schema 文件。
3. 以 `dynamic_service` 执行模式部署工作流，传入服务名称、输入输出 Schema、结果模式与 HTML 页面资源引用。
4. 保存返回的工作流 ID 并核查发布警告；后续更新服务配置时一并携带页面资源文件信息以保留绑定。

(sdk-ai-studio-workflow-service-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. **工作流定义与输入输出 Schema**（`WORKFLOW_FILE`、`INPUT_SCHEMA_FILE`、`OUTPUT_SCHEMA_FILE`）：准备已通过测试的原生 MOWL JSON 文件，以及与工作流输入和输出结构一致的 JSON Schema 文件。
3. **HTML 页面文件 ID 与已有工作流 ID**：按 [管理卷和文件](../资源中心/管理卷和文件.md#sdk-ai-studio-volume-file-upload) 将 HTML 文件上传至工作区卷并保存返回的文件 ID（`HTML_FILE_ID`）；更新已有服务时，按 [读取资源清单](../资源中心/读取资源清单.md) 取得目标工作流 ID（`WORKFLOW_ID`）。

(sdk-ai-studio-workflow-service-publish)=
## 发布动态服务

传入工作流定义、输入输出 JSON Schema 文件内容和 HTML 文件 ID 提交部署。新建动态服务时无需设置 `WORKFLOW_ID`。

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

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

```python
import json
import os
from pathlib import Path
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(os.environ["WORKSPACE_ID"])
definition = json.loads(Path(os.environ["WORKFLOW_FILE"]).read_text())
workflow, deployment = workspace.deploy_workflow(
    "Document service", "", os.environ.get("WORKFLOW_ID", ""),
    sdk.with_workflow_mowl(definition),
    sdk.with_workflow_execution_mode("dynamic_service"),
    sdk.with_workflow_dynamic_service(
        service_name="document_service",
        input_schema=Path(os.environ["INPUT_SCHEMA_FILE"]).read_text(),
        output_schema=Path(os.environ["OUTPUT_SCHEMA_FILE"]).read_text(),
        result_mode="oneshot",
        ui_resource={"file_id": os.environ["HTML_FILE_ID"], "mime_type": "text/html"},
    ),
)
print("Workflow:", workflow.id)
print("Warnings:", deployment.warnings)
```

::::

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

```go
package main

import (
	"context"
	"encoding/json"
	"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(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	definition, err := os.ReadFile(os.Getenv("WORKFLOW_FILE"))
	if err != nil {
		panic(err)
	}
	inputSchema, err := os.ReadFile(os.Getenv("INPUT_SCHEMA_FILE"))
	if err != nil {
		panic(err)
	}
	outputSchema, err := os.ReadFile(os.Getenv("OUTPUT_SCHEMA_FILE"))
	if err != nil {
		panic(err)
	}
	workflow, deployment, err := workspace.DeployWorkflow(
		ctx,
		"Document service",
		"",
		os.Getenv("WORKFLOW_ID"),
		sdk.WithWorkflowMOWL(json.RawMessage(definition)),
		sdk.WithWorkflowExecutionMode("dynamic_service"),
		sdk.WithWorkflowDynamicService(sdk.WorkflowDynamicServiceParam{
			ServiceName:  "document_service",
			InputSchema:  string(inputSchema),
			OutputSchema: string(outputSchema),
			ResultMode:   "oneshot",
			UIResource: &sdk.WorkflowUIResourceParam{
				FileID:   os.Getenv("HTML_FILE_ID"),
				MimeType: "text/html",
			},
		}),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("Workflow:", workflow.ID())
	fmt.Println("Warnings:", deployment.GetWarnings())
}
```

::::

:::::

保存返回的工作流 ID，读取工作流详情确认动态服务配置及调用入口，并在目标客户端验证一次服务调用与页面渲染。仅支持基础工具调用的普通 MCP 客户端不会渲染 MCP Apps 交互页面。

(sdk-ai-studio-workflow-service-update)=
## 更新页面绑定

后续显式更新工作流的动态服务配置时，若未传入页面资源字段，服务端会清空已有的 HTML 页面绑定；需要保留原交互页面时，在更新请求中一并传入原 `file_id` 与 `mime_type`。若仅需将单个算子节点发布为无页面的 API 服务，见 [管理 WorkItem 服务](管理WorkItem服务.md)。

(sdk-ai-studio-workflow-service-next)=
## 下一步

- [管理 WorkItem 服务](管理WorkItem服务.md)
- [运行并跟踪工作流](运行并跟踪工作流.md)
