OpenServ Client：TypeScript API 客户端，快速将AI代理接入OpenServ平台

openserv-client by openserv-labs/skills

94 周安装量

23 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/openserv-labs/skills --skill openserv-client

AI/机器学习自动化区块链

🇨🇳中文介绍

OpenServ Client

@openserv-labs/client 包是 OpenServ Platform API 的 TypeScript 客户端。当你的代码需要与平台通信时——无论是注册代理、创建工作流、设置触发器还是运行任务——都会用到它。

为什么需要这个包

你的代理（使用 @openserv-labs/sdk 构建）在你的机器或服务器上运行。在你告知平台之前，平台并不知道它的存在：代理是什么、如何访问它以及如何触发它。客户端就是你用来完成这些操作的工具。它允许你创建一个平台账户（或复用现有账户）、注册你的代理、定义工作流和触发器（webhook、cron、手动或 x402 付费），并绑定凭证，以便你的代理可以接收任务。没有它，你的代理将无法接入平台或接收工作。

你可以用它做什么

配置 — 一次性设置：创建或复用账户（通过钱包）、注册代理、创建包含触发器和任务的工作流，并获取 API 密钥和认证令牌。通常你会在每次应用启动时调用一次 provision()；它是幂等的。
平台 API — 通过 PlatformClient 进行完全控制：创建和列出代理、工作流、触发器和任务；触发触发器；运行工作流；管理凭证。当你需要超出默认配置流程的功能时使用它。
模型参数 — 配置平台为你的代理任务使用哪个 LLM 模型及其参数。在创建/更新代理时或通过 provision() 设置 model_parameters。
— 通过发现可用的 LLM 模型及其参数模式。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

快速开始：仅需 `provision()` + `run()`

最简单的部署只需要两次调用：provision() 和 run()。 仅此而已。

你需要在平台上拥有一个账户来注册代理和工作流。最简单的方法是让 provision() 为你创建一个：它会创建一个钱包并用它为你注册（无需电子邮件）。该账户在每次运行时都会被复用。

查看 examples/agent.ts 获取完整的可运行示例。

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

`provision()` 的作用

创建或复用以太坊钱包（如果是新账户，则同时创建平台账户）
使用 OpenServ 平台进行身份验证
创建或更新代理（幂等）
生成 API 密钥和认证令牌
将凭证绑定到代理实例（如果提供了 agent.instance）
创建或更新包含触发器和任务的工作流
创建工作流图（连接触发器到任务的边）
激活触发器并将工作流设置为运行状态
将状态持久化到 .openserv.json

工作流名称与目标

workflow 配置需要两个重要属性：

name（字符串） - 这将成为 ERC-8004 中的代理名称。使其精炼、有力且令人难忘——这是用户看到的公开品牌名称。请考虑产品发布，而不是变量名。例如：'Viral Content Engine'、'Crypto Alpha Scanner'、'Life Catalyst Pro'。
goal（字符串，必需） - 对工作流实现目标的详细描述。必须具有描述性且详尽——简短或模糊的目标将导致 API 调用失败。至少写一个完整的句子来解释工作流的目的。

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

代理实例绑定（v1.1+）

将你的代理实例传递给 provision() 以实现自动凭证绑定：

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

await provision({
  agent: {
    instance: agent, // 自动调用 agent.setCredentials()
    name: 'my-agent',
    description: '...',
    model_parameters: { model: 'gpt-5', verbosity: 'medium', reasoning_effort: 'high' } // 可选
  },
  workflow: { ... }
})

// agent 现在已设置好 apiKey 和 authToken - 准备运行 run()
await run(agent)

这消除了手动设置 OPENSERV_API_KEY 环境变量的需要。

可选的 model_parameters 字段控制平台在为你的代理执行任务时（包括无运行能力和 generate() 调用）使用哪个 LLM 模型及其参数。如果未提供，则使用平台默认值。

await provision({
  agent: {
    instance: agent,
    name: 'my-agent',
    description: '...',
    model_parameters: {
      model: 'gpt-4o',
      temperature: 0.5,
      parallel_tool_calls: false
    }
  },
  workflow: { ... }
})

发现可用模型及其参数：

const { models, default: defaultModel } = await client.models.list()
// models: [{ model: 'gpt-5', provider: 'openai', parameters: { ... } }, ...]
// default: 'gpt-5-mini'

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

API 密钥：代理 vs 用户

provision() 创建两种类型的凭证。它们不可互换：

凭证	环境变量	使用者	用途
代理 API 密钥	`OPENSERV_API_KEY`	SDK 内部	当代理从平台接收任务时进行身份验证。通过 `agent.instance` 自动设置。请勿与 `PlatformClient` 一起使用。
钱包密钥	`WALLET_PRIVATE_KEY`	`PlatformClient`	为管理调用（列出任务、调试工作流、管理代理）对你的账户进行身份验证。
用户 API 密钥	`OPENSERV_USER_API_KEY`	`PlatformClient`	钱包身份验证的替代方案。从平台仪表板获取。

如果你在使用 PlatformClient 时遇到 401 Unauthorized，很可能错误地使用了代理 API 密钥。请改用钱包身份验证或用户 API 密钥。

PlatformClient：完整的 API 访问

对于高级用例，直接使用 PlatformClient：

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

// 使用钱包身份验证（推荐——使用配置中的钱包）
const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

// 或使用用户 API 密钥（不是代理 API 密钥）
const client = new PlatformClient({
  apiKey: process.env.OPENSERV_USER_API_KEY // 不是 OPENSERV_API_KEY
})

有关以下内容的完整 API 文档，请参阅 reference.md：

client.agents.* - 代理管理
client.workflows.* - 工作流管理
client.triggers.* - 触发器管理
client.tasks.* - 任务管理
client.models.* - 可用的 LLM 模型和参数
client.integrations.* - 集成连接
client.payments.* - x402 支付
client.web3.* - 积分充值

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

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: '描述你希望代理做什么'
    }
  }
})

// Cron（计划任务）
triggers.cron({
  schedule: '0 9 * * *', // 每天上午 9 点
  timezone: 'America/New_York'
})

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

重要： 对于 webhook 和 x402 触发器，始终将 timeout 设置为至少 600 秒（10 分钟）。代理处理请求通常需要大量时间——尤其是在多代理工作流中，或执行研究、内容生成或其他复杂任务时。较短的超时（例如 180 秒）将导致过早失败。如有疑问，请倾向于设置更长的超时。对于具有许多连续步骤的多代理管道，请考虑 900 秒或更长。

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

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'
    }
  }
})

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

常见示例：0 9 * * *（每天上午 9 点）、*/5 * * * *（每 5 分钟）、0 9 * * 1-5（工作日每天上午 9 点）

部署到 OpenServ Cloud

使用以下命令将你的代理部署到 OpenServ 托管云：

npx @openserv-labs/client deploy [path]

其中 [path] 是包含你代理代码的目录（默认为当前目录）。

.env 中的 OPENSERV_USER_API_KEY — 代理目录中的 .env 文件必须包含 OPENSERV_USER_API_KEY。从 OpenServ 平台仪表板获取此密钥。此密钥是部署命令（以及 PlatformClient 用于管理操作）所必需的。请注意，provision() 本身不需要此密钥——它会创建自己的钱包、进行身份验证，并将凭证独立持久化到 .openserv.json。如果存在，用户 API 密钥也会在配置后保存到 .openserv.json。
首先调用 provision() — 在部署之前，必须至少运行一次 provision()。它会在平台上注册代理并将凭证持久化到 .openserv.json。推荐的代理模板已经在 main() 中的 run(agent) 之前调用了 provision()，因此在本地启动代理（npm run dev 或 npx tsx src/agent.ts）就足够了。如果你的代码没有调用 provision()（例如，你只在自定义脚本中调用 run(agent)），则必须添加显式的 provision() 调用，并在部署前至少运行一次。

1. 在 .env 中设置 OPENSERV_USER_API_KEY
2. 在本地启动期间调用 provision() (npm run dev) — 注册代理并写入 .openserv.json
3. npx @openserv-labs/client deploy .

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

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

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

发现并触发 x402 服务

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

discoverServices() 列出所有公开的启用了 x402 的工作流。无需身份验证——你可以在一个裸的 PlatformClient 上调用它：

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}`)
}

// 通过工作流 ID（推荐——自动解析 URL）
const result = await client.triggers.fireWebhook({
  workflowId: 123,
  input: { query: 'hello world' }
})

// 或通过直接 URL
const result = await client.triggers.fireWebhook({
  triggerUrl: 'https://api.openserv.ai/webhooks/trigger/TOKEN',
  input: { query: 'hello world' }
})

x402（编程方式）

// 通过工作流 ID（推荐）
const result = await client.payments.payWorkflow({
  workflowId: 123,
  input: { prompt: 'Hello world' }
})

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

变量	描述	必需
`OPENSERV_USER_API_KEY`	用户 API 密钥（来自平台）。部署和 `PlatformClient` 所需	是*
`WALLET_PRIVATE_KEY`	用于 SIWE 身份验证的钱包	是*
`OPENSERV_API_URL`	自定义 API URL	否

*PlatformClient 需要 API 密钥或钱包密钥中的一种。npx @openserv-labs/client deploy 需要 OPENSERV_USER_API_KEY。

ERC-8004：链上代理身份

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

需要在 Base 上有 ETH。 provision() 创建的钱包初始余额为零。在注册之前，请使用少量 Base 主网 ETH 为其充值。始终使用 try/catch 包装，以免失败阻止 run(agent) 启动。

在 provision() 后重新加载 .env。 provision() 在运行时将 WALLET_PRIVATE_KEY 写入 .env，但 process.env 在启动时已经加载了空值。在 provision() 之后使用 dotenv.config({ override: true }) 来获取刚写入的密钥。有关完整的 dotenv 模式，请参阅 openserv-agent-sdk 技能。

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

// 重新加载 .env 以获取 provision() 写入的 WALLET_PRIVATE_KEY
dotenv.config({ override: true })

try {
  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: '此代理的功能'
  })

  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"
} catch (error) {
  console.warn('ERC-8004 注册已跳过：', error instanceof Error ? error.message : error)
}

首次运行 铸造一个新的 NFT。重新运行会更新 URI——代理 ID 保持不变。
默认链是 Base 主网 (8453)。对于其他链，请传递 chainId 和 rpcUrl。
切勿清除钱包状态，除非你确实想要一个新的代理 ID。

有关完整的 ERC-8004 API（钱包管理、链辅助工具、故障排除），请参阅 reference.md。

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

此技能可能已过时。OpenServ 团队会定期发布更新——新功能、API 更改和错误修复在你更新之前不会反映在此处。如果某些功能未按预期工作，或者你想确保拥有最新信息，请在继续之前更新技能。

# 检查是否有可用更新
npx skills check

# 将所有已安装技能更新到最新版本
npx skills update

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

npx skills add openserv-labs/skills

openserv-agent-sdk - 使用能力构建代理
openserv-multi-agent-workflows - 多代理协作模式
openserv-launch - 在 Base 区块链上发行代币
openserv-ideaboard-api - 在 Ideaboard 上寻找创意并发布代理服务

🇺🇸English

OpenServ Client

The @openserv-labs/client package is the TypeScript client for the OpenServ Platform API. You use it whenever your code needs to talk to the platform—to register an agent, create workflows, set up triggers, or run tasks.

Why you need this package

Your agent (built with @openserv-labs/sdk) runs on your machine or server. The platform doesn’t know about it until you tell it: what the agent is, where it’s reachable, and how it can be triggered. The client is how you do that. It lets you create a platform account (or reuse one), register your agent, define workflows and triggers (webhook, cron, manual, or x402 paid), and bind credentials so your agent can accept tasks. Without it, your agent would have no way to get onto the platform or receive work.

What you can do with it

Provision — One-shot setup: create or reuse an account (via wallet), register the agent, create a workflow with trigger and task, and get API key and auth token. Typically you call provision() once per app startup; it’s idempotent.
Platform API — Full control via PlatformClient: create and list agents, workflows, triggers, and tasks; fire triggers; run workflows; manage credentials. Use this when you need more than the default provision flow.
Model Parameters — Configure which LLM model and parameters the platform uses for your agent's tasks. Set model_parameters on agent creation/update or via provision().
Models API — Discover available LLM models and their parameter schemas via client.models.list().
x402 payments — Expose your agent behind a paywall; callers pay per request (e.g. USDC) before the task runs. Provision can set up an x402 trigger and return a paywall URL.
ERC-8004 on-chain identity — Register your agent on-chain (Base), mint an identity NFT, and publish service metadata to IPFS so others can discover and pay your agent in a standard way.

Reference: reference.md (full API) · troubleshooting.md (common issues) · examples/ (runnable code)

Installation

npm install @openserv-labs/client

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

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

You need an account on the platform to register agents and workflows. The easiest way is to let provision() create one for you: it creates a wallet and signs you up with it (no email required). That account is reused on every run.

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.

What `provision()` Does

Creates or reuses an Ethereum wallet (and platform account if new)
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

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.

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' } }

Agent Instance Binding (v1.1+)

Pass your agent instance to provision() for automatic credential binding:

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

await provision({
  agent: {
    instance: agent, // Calls agent.setCredentials() automatically
    name: 'my-agent',
    description: '...',
    model_parameters: { model: 'gpt-5', verbosity: 'medium', reasoning_effort: 'high' } // Optional
  },
  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.

Model Parameters

The optional model_parameters field controls which LLM model and parameters the platform uses when executing tasks for your agent (including runless capabilities and generate() calls). If not provided, the platform default is used.

await provision({
  agent: {
    instance: agent,
    name: 'my-agent',
    description: '...',
    model_parameters: {
      model: 'gpt-4o',
      temperature: 0.5,
      parallel_tool_calls: false
    }
  },
  workflow: { ... }
})

Discover available models and their parameters:

const { models, default: defaultModel } = await client.models.list()
// models: [{ model: 'gpt-5', provider: 'openai', parameters: { ... } }, ...]
// default: 'gpt-5-mini'

Provision Result

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

API Keys: Agent vs User

provision() creates two types of credentials. They are not interchangeable :

Credential	Env Variable	Used By	Purpose
Agent API key	`OPENSERV_API_KEY`	SDK internals	Authenticates the agent when receiving tasks from the platform. Set automatically via `agent.instance`. Do not use with `PlatformClient`.
Wallet key	`WALLET_PRIVATE_KEY`	`PlatformClient`	Authenticates your account for management calls (list tasks, debug workflows, manage agents).
User API key	`OPENSERV_USER_API_KEY`

If you get a 401 Unauthorized when using PlatformClient, you are likely using the agent API key by mistake. Use wallet authentication or the user API key instead.

PlatformClient: Full API Access

For advanced use cases, use PlatformClient directly:

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

// Using wallet authentication (recommended — uses wallet from provision)
const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)

// Or using User API key (NOT the agent API key)
const client = new PlatformClient({
  apiKey: process.env.OPENSERV_USER_API_KEY // NOT OPENSERV_API_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.models.* - Available LLM models and parameters
client.integrations.* - Integration connections
client.payments.* - x402 payments
client.web3.* - Credits top-up

Triggers Factory

Use the triggers factory for type-safe trigger configuration:

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

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.

Input Schema

Define fields for webhook/x402 paywall UI:

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'
    }
  }
})

Cron Expressions

┌───────────── 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)

Deploy to OpenServ Cloud

Deploy your agent to the OpenServ managed cloud with:

npx @openserv-labs/client deploy [path]

Where [path] is the directory containing your agent code (defaults to current directory).

Prerequisites

OPENSERV_USER_API_KEY in .env — Your .env file in the agent directory must contain OPENSERV_USER_API_KEY. Get this from the OpenServ platform dashboard. This key is required by the deploy command (and by PlatformClient for management operations). Note that provision() itself does not need this key — it creates its own wallet, authenticates, and persists credentials to .openserv.json independently. The user API key is also saved to .openserv.json after provision if present.
Callprovision() first — must run at least once before deploying. It registers the agent on the platform and persists credentials to . The recommended agent template already calls before in , so starting the agent locally ( or ) is enough. If your code does not call (e.g., you only call in a custom script), you must add an explicit call and run it once before deploying.

Deploy Workflow

1. Set OPENSERV_USER_API_KEY in .env
2. Call provision() during local startup (npm run dev) — registers the agent and writes .openserv.json
3. npx @openserv-labs/client deploy .

State Management

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

Discovering & Firing x402 Services

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:

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}`)
}

Firing Triggers

// By workflow ID (recommended — resolves the URL automatically)
const result = await client.triggers.fireWebhook({
  workflowId: 123,
  input: { query: 'hello world' }
})

// Or by direct URL
const result = await client.triggers.fireWebhook({
  triggerUrl: 'https://api.openserv.ai/webhooks/trigger/TOKEN',
  input: { query: 'hello world' }
})

x402 (Programmatic)

// By workflow ID (recommended)
const result = await client.payments.payWorkflow({
  workflowId: 123,
  input: { prompt: 'Hello world' }
})

// Or by direct URL
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). Required for deploy and `PlatformClient`	Yes*
`WALLET_PRIVATE_KEY`	Wallet for SIWE auth	Yes*
`OPENSERV_API_URL`	Custom API URL	No

*Either API key or wallet key required for PlatformClient. OPENSERV_USER_API_KEY is required for npx @openserv-labs/client deploy.

ERC-8004: On-Chain Agent Identity

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

Requires ETH on Base. The wallet created by provision() starts with zero balance. Fund it with a small amount of ETH on Base mainnet before registration. Always wrap in try/catch so failures don't prevent run(agent) from starting.

Reload.env after provision(). provision() writes WALLET_PRIVATE_KEY to .env at runtime, but process.env already loaded the empty value at startup. Use dotenv.config({ override: true }) after provision() to pick up the freshly written key. See openserv-agent-sdk skill for the full dotenv pattern.

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

// Reload .env to pick up WALLET_PRIVATE_KEY written by provision()
dotenv.config({ override: true })

try {
  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"
} catch (error) {
  console.warn('ERC-8004 registration skipped:', error instanceof Error ? error.message : error)
}

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).

Cleanup

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.

# Check if updates are available
npx skills check

# Update all installed skills to latest versions
npx skills update

Or reinstall the OpenServ skills directly:

npx skills add openserv-labs/skills

Related Skills

openserv-agent-sdk - Building agents with capabilities
openserv-multi-agent-workflows - Multi-agent collaboration patterns
openserv-launch - Launch tokens on Base blockchain
openserv-ideaboard-api - Find ideas and ship agent services on the Ideaboard

Weekly Installs

Repository

openserv-labs/skills

GitHub Stars

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex72

opencode63

github-copilot54

amp54

kimi-cli54

gemini-cli54

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

69,600 周安装

npx tsx src/agent.ts

OpenServ Client：TypeScript API 客户端，快速将AI代理接入OpenServ平台

🇨🇳中文介绍

OpenServ Client

为什么需要这个包

你可以用它做什么

相关 Skills

安装

快速开始：仅需 provision() + run()

provision() 的作用

工作流名称与目标

代理实例绑定（v1.1+）

模型参数

配置结果

API 密钥：代理 vs 用户

PlatformClient：完整的 API 访问

触发器工厂

超时

输入模式

Cron 表达式

部署到 OpenServ Cloud

先决条件

部署工作流

状态管理

发现并触发 x402 服务

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

触发触发器

x402（编程方式）

环境变量

ERC-8004：链上代理身份

清理

更新此技能

相关技能

🇺🇸English

OpenServ Client

Why you need this package

What you can do with it

Installation

Quick Start: Just provision() + run()

What provision() Does

Workflow Name & Goal

Agent Instance Binding (v1.1+)

Model Parameters

Provision Result

API Keys: Agent vs User

PlatformClient: Full API Access

Triggers Factory

Timeout

Input Schema

Cron Expressions

Deploy to OpenServ Cloud

Prerequisites

Deploy Workflow

State Management

Discovering & Firing x402 Services

Discover Available Services (No Auth Required)

Firing Triggers

x402 (Programmatic)

Environment Variables

ERC-8004: On-Chain Agent Identity

Cleanup

Updating This Skill

Related Skills

最新 Skills

快速开始：仅需 `provision()` + `run()`

`provision()` 的作用

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

What `provision()` Does