openserv-client

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenServ Client

OpenServ客户端

The

@openserv-labs/client

package provides a TypeScript client for the OpenServ Platform API.

Reference files:

```
reference.md
```
- Full API reference for all PlatformClient methods
```
troubleshooting.md
```
- Common issues and solutions
```
examples/
```
- Complete code examples

@openserv-labs/client

包为OpenServ平台API提供了一个TypeScript客户端。

参考文件：

```
reference.md
```
- 所有PlatformClient方法的完整API参考
```
troubleshooting.md
```
- 常见问题及解决方案
```
examples/
```
- 完整代码示例

Installation

安装

bash

npm install @openserv-labs/client

bash

npm install @openserv-labs/client

Quick Start: Just

provision()

run()

快速入门：只需

provision()

run()

The simplest deployment is just two calls:
provision()
and
run()
. That's it.

See

examples/agent.ts

for a complete runnable example.

Key Point:
provision()
is idempotent. Call it every time your app starts - no need to check
isProvisioned()
first.

最简单的部署只需两次调用：
provision()
和
run()
。就是这么简单。

完整可运行示例请查看

examples/agent.ts

。

关键点：
provision()
是幂等的。每次应用启动时都可以调用它——无需先检查
isProvisioned()
。

What

provision()

Does

provision()

的作用

Creates/retrieves an Ethereum wallet for authentication
Authenticates with the OpenServ platform
Creates or updates the agent (idempotent)
Generates API key and auth token
Binds credentials to agent instance (if
```
agent.instance
```
is provided)
Creates or updates the workflow with trigger and task
Creates workflow graph (edges linking trigger to task)
Activates trigger and sets workflow to running
Persists state to
```
.openserv.json
```

创建/检索用于身份验证的以太坊钱包
与OpenServ平台进行身份验证
创建或更新Agent（幂等操作）
生成API密钥和身份验证令牌
将凭证绑定到Agent实例（如果提供了
```
agent.instance
```
）
创建或更新带有触发器和任务的工作流
创建工作流图（连接触发器与任务的边）
激活触发器并将工作流设置为运行状态
将状态持久化到
```
.openserv.json
```

Workflow Name & Goal

工作流名称与目标

The

workflow

config requires two important properties:

name
(string) - This becomes the agent name in ERC-8004. Make it polished, punchy, and memorable — this is the public-facing brand name users see. Think product launch, not variable name. Examples:
```
'Viral Content Engine'
```
,
```
'Crypto Alpha Scanner'
```
,
```
'Life Catalyst Pro'
```
.
goal
(string, required) - A detailed description of what the workflow accomplishes. Must be descriptive and thorough — short or vague goals will cause API calls to fail. Write at least a full sentence explaining the workflow's purpose.

typescript

workflow: {
  name: 'Deep Research Pro',
  goal: 'Research any topic in depth, synthesize findings from multiple sources, and produce a comprehensive report with citations',
  trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),
  task: { description: 'Research the given topic' }
}

workflow

配置需要两个重要属性：

name
（字符串）- 这将成为ERC-8004中的Agent名称。请起一个简洁、醒目且易记的名称——这是用户看到的公开品牌名称。要像产品发布名称一样，而不是变量名。例如：
```
'Viral Content Engine'
```
、
```
'Crypto Alpha Scanner'
```
、
```
'Life Catalyst Pro'
```
。
goal
（字符串，必填）- 对工作流实现目标的详细描述。必须详尽具体——简短或模糊的目标会导致API调用失败。请至少用一整句话解释工作流的用途。

typescript

workflow: {
  name: 'Deep Research Pro',
  goal: '深入研究任何主题，综合多来源研究结果，并生成带引用的全面报告',
  trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),
  task: { description: '研究指定主题' }
}

Agent Instance Binding (v1.1+)

Agent实例绑定（v1.1+）

Pass your agent instance to

provision()

for automatic credential binding:

typescript

const agent = new Agent({ systemPrompt: '...' })

await provision({
  agent: {
    instance: agent, // Calls agent.setCredentials() automatically
    name: 'my-agent',
    description: '...'
  },
  workflow: { ... }
})

// agent now has apiKey and authToken set - ready for run()
await run(agent)

This eliminates the need to manually set

OPENSERV_API_KEY

environment variables.

将你的Agent实例传递给

provision()

以自动绑定凭证：

typescript

const agent = new Agent({ systemPrompt: '...' })

await provision({
  agent: {
    instance: agent, // 自动调用agent.setCredentials()
    name: 'my-agent',
    description: '...'
  },
  workflow: { ... }
})

// agent现在已设置apiKey和authToken - 可随时调用run()
await run(agent)

这消除了手动设置

OPENSERV_API_KEY

环境变量的需求。

Provision Result

资源配置结果

typescript

interface ProvisionResult {
  agentId: number
  apiKey: string
  authToken?: string
  workflowId: number
  triggerId: string
  triggerToken: string
  paywallUrl?: string // For x402 triggers
  apiEndpoint?: string // For webhook triggers
}

typescript

interface ProvisionResult {
  agentId: number
  apiKey: string
  authToken?: string
  workflowId: number
  triggerId: string
  triggerToken: string
  paywallUrl?: string // 用于x402触发器
  apiEndpoint?: string // 用于webhook触发器
}

PlatformClient: Full API Access

PlatformClient：完整API访问

For advanced use cases, use

PlatformClient

directly:

typescript

import { PlatformClient } from '@openserv-labs/client'

// Using API key
const client = new PlatformClient({
  apiKey: process.env.OPENSERV_USER_API_KEY
})

// Or using wallet authentication
const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

See

reference.md

for full API documentation on:

```
client.agents.*
```
- Agent management
```
client.workflows.*
```
- Workflow management
```
client.triggers.*
```
- Trigger management
```
client.tasks.*
```
- Task management
```
client.integrations.*
```
- Integration connections
```
client.payments.*
```
- x402 payments
```
client.web3.*
```
- Credits top-up

对于高级用例，请直接使用

PlatformClient

：

typescript

import { PlatformClient } from '@openserv-labs/client'

// 使用API密钥
const client = new PlatformClient({
  apiKey: process.env.OPENSERV_USER_API_KEY
})

// 或使用钱包身份验证
const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

完整API文档请查阅

reference.md

，包括：

```
client.agents.*
```
- Agent管理
```
client.workflows.*
```
- 工作流管理
```
client.triggers.*
```
- 触发器管理
```
client.tasks.*
```
- 任务管理
```
client.integrations.*
```
- 集成连接
```
client.payments.*
```
- x402支付
```
client.web3.*
```
- 余额充值

Triggers Factory

触发器工厂

Use the

triggers

factory for type-safe trigger configuration:

typescript

import { triggers } from '@openserv-labs/client'

// Webhook (free, public endpoint)
triggers.webhook({
  input: { query: { type: 'string', description: 'Search query' } },
  waitForCompletion: true,
  timeout: 600
})

// x402 (paid API with paywall)
triggers.x402({
  name: 'AI Research Assistant',
  description: 'Get comprehensive research reports on any topic',
  price: '0.01',
  timeout: 600,
  input: {
    prompt: {
      type: 'string',
      title: 'Your Request',
      description: 'Describe what you would like the agent to do'
    }
  }
})

// Cron (scheduled)
triggers.cron({
  schedule: '0 9 * * *', // Daily at 9 AM
  timezone: 'America/New_York'
})

// Manual (platform UI only)
triggers.manual()

使用

triggers

工厂进行类型安全的触发器配置：

typescript

import { triggers } from '@openserv-labs/client'

// Webhook（免费，公开端点）
triggers.webhook({
  input: { query: { type: 'string', description: '搜索查询' } },
  waitForCompletion: true,
  timeout: 600
})

// x402（带付费墙的付费API）
triggers.x402({
  name: 'AI Research Assistant',
  description: '获取任意主题的全面研究报告',
  price: '0.01',
  timeout: 600,
  input: {
    prompt: {
      type: 'string',
      title: '你的请求',
      description: '描述你希望Agent执行的操作'
    }
  }
})

// Cron（定时触发）
triggers.cron({
  schedule: '0 9 * * *', // 每天上午9点
  timezone: 'America/New_York'
})

// Manual（仅平台UI触发）
triggers.manual()

Timeout

超时设置

Important: Always set
timeout
to at least 600 seconds (10 minutes) for webhook and x402 triggers. Agents often take significant time to process requests — especially in multi-agent workflows or when performing research, content generation, or other complex tasks. A low timeout (e.g., 180s) will cause premature failures. When in doubt, err on the side of a longer timeout. For multi-agent pipelines with many sequential steps, consider 900 seconds or more.

重要提示： 对于webhook和x402触发器，请始终将
timeout
设置为至少600秒（10分钟）。Agent处理请求通常需要大量时间——尤其是在多Agent工作流或执行研究、内容生成等复杂任务时。较低的超时时间（如180秒）会导致提前失败。如有疑问，请设置更长的超时时间。对于包含多个连续步骤的多Agent管道，可考虑设置900秒或更长时间。

Input Schema

输入 Schema

Define fields for webhook/x402 paywall UI:

typescript

triggers.x402({
  name: 'Content Writer',
  description: 'Generate polished content on any topic',
  price: '0.01',
  input: {
    topic: {
      type: 'string',
      title: 'Content Topic',
      description: 'Enter the subject you want covered'
    },
    style: {
      type: 'string',
      title: 'Writing Style',
      enum: ['formal', 'casual', 'humorous'],
      default: 'casual'
    }
  }
})

为webhook/x402付费墙UI定义字段：

typescript

triggers.x402({
  name: 'Content Writer',
  description: '生成任意主题的优质内容',
  price: '0.01',
  input: {
    topic: {
      type: 'string',
      title: '内容主题',
      description: '输入你希望覆盖的主题'
    },
    style: {
      type: 'string',
      title: '写作风格',
      enum: ['formal', 'casual', 'humorous'],
      default: 'casual'
    }
  }
})

Cron Expressions

Cron表达式

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
* * * * *

Common:

0 9 * * *

(daily 9 AM),

*/5 * * * *

(every 5 min),

0 9 * * 1-5

(weekdays 9 AM)

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6，周日=0)
* * * * *

常用示例：

0 9 * * *

（每天上午9点）、

*/5 * * * *

（每5分钟）、

0 9 * * 1-5

（工作日上午9点）

State Management

状态管理

typescript

import { getProvisionedInfo, clearProvisionedState } from '@openserv-labs/client'

// Get stored IDs and tokens
const info = getProvisionedInfo('my-agent', 'My Awesome Workflow')

// Clear state (forces fresh creation)
clearProvisionedState()

typescript

import { getProvisionedInfo, clearProvisionedState } from '@openserv-labs/client'

// 获取存储的ID和令牌
const info = getProvisionedInfo('my-agent', 'My Awesome Workflow')

// 清除状态（强制重新创建）
clearProvisionedState()

Discovering & Firing x402 Services

发现与触发x402服务

Discover Available Services (No Auth Required)

发现可用服务（无需身份验证）

discoverServices()

lists all public x402-enabled workflows. No authentication is needed — you can call it on a bare

PlatformClient

typescript

import { PlatformClient } from '@openserv-labs/client'

const client = new PlatformClient() // no API key or wallet needed
const services = await client.payments.discoverServices()

for (const service of services) {
  console.log(`${service.name}: $${service.x402Pricing}`)
  console.log(`URL: ${service.webhookUrl}`)
}

discoverServices()

列出所有公开的支持x402的工作流。无需身份验证——你可以在裸

PlatformClient

上调用它：

typescript

import { PlatformClient } from '@openserv-labs/client'

const client = new PlatformClient() // 无需API密钥或钱包
const services = await client.payments.discoverServices()

for (const service of services) {
  console.log(`${service.name}: $${service.x402Pricing}`)
  console.log(`URL: ${service.webhookUrl}`)
}

Firing Triggers

触发触发器

Webhook

bash

curl -X POST https://api.openserv.ai/webhooks/trigger/TOKEN \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'

bash

curl -X POST https://api.openserv.ai/webhooks/trigger/TOKEN \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'

x402 (Programmatic)

x402（程序化调用）

typescript

const result = await client.payments.payWorkflow({
  triggerUrl: 'https://api.openserv.ai/webhooks/x402/trigger/TOKEN',
  input: { prompt: 'Hello world' }
})

typescript

const result = await client.payments.payWorkflow({
  triggerUrl: 'https://api.openserv.ai/webhooks/x402/trigger/TOKEN',
  input: { prompt: 'Hello world' }
})

Environment Variables

环境变量

Variable	Description	Required
`OPENSERV_USER_API_KEY`	User API key (from platform)	Yes*
`WALLET_PRIVATE_KEY`	Wallet for SIWE auth	Yes*
`OPENSERV_API_URL`	Custom API URL	No

*Either API key or wallet key required

环境变量	描述	是否必填
`OPENSERV_USER_API_KEY`	用户API密钥（来自平台）	是*
`WALLET_PRIVATE_KEY`	用于SIWE身份验证的钱包	是*
`OPENSERV_API_URL`	自定义API地址	否

*需提供API密钥或钱包密钥其中之一

ERC-8004: On-Chain Agent Identity

ERC-8004：链上Agent身份

Register your agent on-chain after provisioning. This mints an NFT on the Identity Registry and publishes your agent's service endpoints to IPFS.

typescript

import { PlatformClient } from '@openserv-labs/client'

const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

const erc8004 = await client.erc8004.registerOnChain({
  workflowId: result.workflowId,
  privateKey: process.env.WALLET_PRIVATE_KEY!,
  name: 'My Agent',
  description: 'What this agent does'
})

console.log(`Agent ID: ${erc8004.agentId}`) // "8453:42"
console.log(`Explorer: ${erc8004.blockExplorerUrl}`)
console.log(`Scan: ${erc8004.scanUrl}`) // "https://www.8004scan.io/agents/base/42"

First run mints a new NFT. Re-runs update the URI — agent ID stays the same.
Default chain is Base mainnet (8453). Pass
```
chainId
```
and
```
rpcUrl
```
for other chains.
Never clear the wallet state unless you intentionally want a new agent ID.

See

reference.md

for the full ERC-8004 API (wallet management, chain helpers, troubleshooting).

在资源配置完成后，在链上注册你的Agent。这会在身份注册表上铸造一个NFT，并将你的Agent服务端点发布到IPFS。

typescript

import { PlatformClient } from '@openserv-labs/client'

const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

const erc8004 = await client.erc8004.registerOnChain({
  workflowId: result.workflowId,
  privateKey: process.env.WALLET_PRIVATE_KEY!,
  name: 'My Agent',
  description: '该Agent的功能'
})

console.log(`Agent ID: ${erc8004.agentId}`) // "8453:42"
console.log(`区块链浏览器: ${erc8004.blockExplorerUrl}`)
console.log(`扫描地址: ${erc8004.scanUrl}`) // "https://www.8004scan.io/agents/base/42"

首次运行会铸造新的NFT。再次运行会更新URI——Agent ID保持不变。
默认链为Base主网（8453）。如需使用其他链，请传入
```
chainId
```
和
```
rpcUrl
```
。
除非你有意获取新的Agent ID，否则请勿清除钱包状态。

完整ERC-8004 API（钱包管理、链助手、故障排除）请查阅

reference.md

。

Cleanup

清理

typescript

await client.workflows.delete({ id: workflowId })
await client.agents.delete({ id: agentId })
clearProvisionedState()

typescript

await client.workflows.delete({ id: workflowId })
await client.agents.delete({ id: agentId })
clearProvisionedState()

Updating This Skill

更新本技能

This skill may be outdated. The OpenServ team ships updates regularly—new features, API changes, and bug fixes won't be reflected here until you update. If something isn't working as expected, or you want to make sure you have the latest information, update the skill before proceeding.

bash

undefined

本技能可能已过时。OpenServ团队会定期发布更新——新功能、API变更和错误修复不会立即反映在此处，直到你更新技能。如果遇到功能异常，或想确保使用最新信息，请先更新技能再继续操作。

bash

undefined

Check if updates are available

检查是否有可用更新

npx skills check

Update all installed skills to latest versions

将所有已安装技能更新到最新版本

npx skills update


Or reinstall the OpenServ skills directly:

```bash
npx skills add openserv-labs/skills

npx skills update


或者直接重新安装OpenServ技能：

```bash
npx skills add openserv-labs/skills

openserv-client

Original

Translation

OpenServ Client

OpenServ客户端

Installation

安装

Quick Start: Just provision() + run()

快速入门：只需provision() + run()

What provision() Does

provision()的作用

Workflow Name & Goal

工作流名称与目标

Agent Instance Binding (v1.1+)

Agent实例绑定（v1.1+）

Provision Result

资源配置结果

PlatformClient: Full API Access

PlatformClient：完整API访问

Triggers Factory

触发器工厂

Timeout

超时设置

Input Schema

输入 Schema

Cron Expressions

Cron表达式

State Management

状态管理

Discovering & Firing x402 Services

发现与触发x402服务

Discover Available Services (No Auth Required)

发现可用服务（无需身份验证）

Firing Triggers

触发触发器

Webhook

Webhook

x402 (Programmatic)

x402（程序化调用）

Environment Variables

环境变量

ERC-8004: On-Chain Agent Identity

ERC-8004：链上Agent身份

Cleanup

清理

Updating This Skill

更新本技能

Check if updates are available

检查是否有可用更新

Update all installed skills to latest versions

将所有已安装技能更新到最新版本

Related Skills

相关技能

Quick Start: Just
`provision()`
+
`run()`

快速入门：只需
`provision()`
+
`run()`

What
`provision()`
Does

`provision()`
的作用