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

典型调用顺序：

1. start() 启动一次执行
2. 如果 Agent 主动暂停并要求补充信息，调用 resume()
3. 当 session 已暂停且执行日志可用时，调用 generateScript()
4. 结束时调用 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 官方接口接入