@vmosedge/workflow-agent-sdk

@vmosedge/workflow-agent-sdk

VMOS Edge 自动化 SDK，用于把“目标描述 -> 设备执行 -> 工作流脚本”串成一条完整链路。

SDK 内置任务规划、运行时可靠性策略、MCP 工具接入和脚本生成能力，适合 Android/云手机自动化、录制回放和 Agent 执行场景。

能力概览

• 目标规划：先拆解任务，再进入执行阶段
• 设备执行：内置本地设备工具，并支持挂接 MCP server 扩展能力
• 可靠性控制：内置重试、超时、收敛限制和动作后验证 gate
• 脚本生成：基于 execution log 生成结构化 workflow script

安装

pnpm add @vmosedge/workflow-agent-sdk

要求：

• Node.js >= 20
• 需要可访问的模型接口，支持 OpenAI-compatible、Anthropic Claude、Google Gemini
• 需要设备连接信息：hostIp + deviceId

导出说明

• @vmosedge/workflow-agent-sdk
  • 轻量导出，包含 generateScript 和基础类型
• @vmosedge/workflow-agent-sdk/runtime
  • 完整 runtime 能力，包含 createAutomationAgentRuntime、AutomationAgentRuntime、默认可靠性配置和错误类型
• @vmosedge/workflow-agent-sdk/types
  • 全量类型定义，适合深度集成

快速开始：直接生成脚本

适用于你已经有 execution log，只需要生成 workflow script 的场景。

import {
  generateScript,
  type AIProviderConfig,
  type ExecutionLogEntry
} from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'openai',
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini'
}

const executionLog: ExecutionLogEntry[] = [
  {
    index: 1,
    toolName: 'start_app',
    arguments: {
      package_name: 'com.example.app'
    },
    result: {
      toolCallId: 'call_1',
      name: 'start_app',
      success: true
    },
    category: 'action',
    timestamp: Date.now()
  }
]

const workflow = await generateScript(
  '打开目标应用并进入首页',
  executionLog,
  provider
)

console.log(JSON.stringify(workflow, null, 2))

快速开始：使用 runtime 跑完整流程

适用于你希望从自然语言目标出发，先规划、再执行、最后生成脚本的场景。

import { createAutomationAgentRuntime } from '@vmosedge/workflow-agent-sdk/runtime'
import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'openai',
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini'
}

const runtime = createAutomationAgentRuntime({
  mcpServers: {
    knowledge: {
      transport: 'streamable_http',
      url: 'https://mcp.example.com'
    }
  }
})

runtime.on('planning', (data) => {
  console.log('[planning]', data.status, data.plan)
})

runtime.on('thinking', (data) => {
  console.log('[thinking]', data.text)
})

runtime.on('toolcall', (data) => {
  console.log('[toolcall]', data.toolCall.name, data.toolCall.arguments)
})

runtime.on('toolresult', (data) => {
  console.log('[toolresult]', data.result.name, data.result.success)
})

runtime.on('paused', async (data) => {
  console.log('[paused]', data.text)

  // 需要人工补充信息时，可恢复继续执行
  // await runtime.resume({
  //   sessionId: data.sessionId,
  //   message: '继续执行，目标是进入搜索页'
  // })
})

runtime.on('error', (data) => {
  console.error('[error]', data.code, data.error, data.details)
})

const { sessionId } = await runtime.start({
  goal: '打开目标应用并进入搜索页',
  provider,
  device: {
    hostIp: '192.168.50.10',
    deviceId: 'emulator-5554'
  }
})

// 当 session 已暂停，且已经产生可用 execution log 后：
const result = await runtime.generateScript(sessionId)

console.log(JSON.stringify(result.workflow, null, 2))
console.log(result.diagnostics)

await runtime.destroy()

典型调用顺序：

• start() 启动一次执行
• 如果 Agent 主动暂停并要求补充信息，调用 resume()
• 当 session 已暂停且执行日志可用时，调用 generateScript()
• 结束时调用 destroy()

Runtime 事件

事件名	说明
planning	任务规划开始或完成
thinking	模型当前可见思考文本
toolcall	发起工具调用
toolresult	收到工具执行结果
diagnostic	可靠性策略、重试、收敛等诊断信息
paused	当前轮次暂停，等待人工补充或外部决策
scriptgenerating	开始生成 workflow script
complete	generateScript() 成功完成后触发
error	运行时错误

MCP Server 配置

支持 stdio、http、streamable_http 和 sse 四类传输方式。

stdio 示例

const runtime = createAutomationAgentRuntime({
  mcpServers: {
    filesystem: {
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', './workspace']
    }
  }
})

HTTP 示例

const runtime = createAutomationAgentRuntime({
  mcpServers: {
    remoteKnowledge: {
      transport: 'streamable_http',
      url: 'https://mcp.example.com',
      headers: {
        Authorization: `Bearer ${process.env.MCP_TOKEN}`
      }
    }
  }
})

常用接口

• createAutomationAgentRuntime(options)：创建 runtime 实例
• runtime.start(params)：启动一次完整任务执行，返回 sessionId
• runtime.resume(params)：在任务暂停后继续执行
• runtime.generateScript(sessionId)：基于当前 session 的 execution log 生成 workflow script
• runtime.stop(sessionId)：停止当前 session
• runtime.destroy()：释放 runtime 占用资源
• runtime.on(event, handler) / runtime.off(event, handler)：订阅或取消订阅事件

Provider 配置

SDK 现在支持两类模型接入方式：

• OpenAI-compatible：vendor 使用 openai / deepseek / azure / custom，需要提供 baseUrl
• Native provider：vendor 使用 anthropic / claude 或 google / gemini，分别走 Claude / Gemini 官方接口，baseUrl 可选

如果你拿到的是 OpenAI-compatible 聚合网关，即使底层模型实际是 Claude 或 Gemini，也应该继续使用 openai 或 custom 并填写 baseUrl。

OpenAI-compatible 示例

import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'openai',
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini'
}

Claude 示例

import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'claude',
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-model-id'
}

Gemini 示例

import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'gemini',
  apiKey: process.env.GOOGLE_API_KEY!,
  model: 'gemini-model-id'
}

可靠性策略

内置默认策略包括：

• observation 工具最多重试 3 次
• action 工具最多重试 2 次
• 默认工具超时 12 秒
• 最大迭代次数 120
• 连续失败和重复工具调用达到阈值时自动暂停

如需调优，可在 start() 时传入 reliability 覆盖默认值。

使用说明

• generateScript(sessionId) 只有在 session 不再运行、execution log 非空且不存在待验证动作时才能成功
• vendor 会直接决定底层 provider：
• openai / deepseek / azure / custom：按 OpenAI-compatible 方式接入
• anthropic / claude：按 Claude 官方接口接入
• google / gemini：按 Gemini 官方接口接入