发布工作流 API 服务

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

任务流程

  1. 将交互页面 HTML 文件上传到工作区数据卷,取得文件 ID(HTML_FILE_ID)。

  2. 准备已验证的原生 MOWL 工作流定义文件,以及与工作流输入输出一致的 JSON Schema 文件。

  3. 以 dynamic_service 执行模式部署工作流,传入服务名称、输入输出 Schema、结果模式与 HTML 页面资源引用。

  4. 保存返回的工作流 ID 并核查发布警告;后续更新服务配置时一并携带页面资源文件信息以保留绑定。

准备

  1. 已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置。

  2. 工作流定义与输入输出 Schema(WORKFLOW_FILE、INPUT_SCHEMA_FILE、OUTPUT_SCHEMA_FILE):准备已通过测试的原生 MOWL JSON 文件,以及与工作流输入和输出结构一致的 JSON Schema 文件。

  3. HTML 页面文件 ID 与已有工作流 ID:按 管理卷和文件 将 HTML 文件上传至工作区卷并保存返回的文件 ID(HTML_FILE_ID);更新已有服务时,按 读取资源清单 取得目标工作流 ID(WORKFLOW_ID)。

发布动态服务

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

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)
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 交互页面。

更新页面绑定

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

下一步

最后更新于