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
CODEBLOCK0
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
- 1. 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 INLINECODE20
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.
CODEBLOCK1
Agent Instance Binding (v1.1+)
Pass your agent instance to provision() for automatic credential binding:
CODEBLOCK2
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.
CODEBLOCK3
Discover available models and their parameters:
CODEBLOCK4
Provision Result
CODEBLOCK5
API Keys: Agent vs User
INLINECODE31 creates two types of credentials. They are not interchangeable:
| Credential | Env Variable | Used By | Purpose |
|---|
| Agent API key | INLINECODE32 | 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 |
PlatformClient | Alternative to wallet auth. Get from the platform dashboard. |
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:
CODEBLOCK6
See reference.md for full API documentation on:
- -
client.agents.* - Agent management - INLINECODE43 - Workflow management
- INLINECODE44 - Trigger management
- INLINECODE45 - Task management
- INLINECODE46 - Available LLM models and parameters
- INLINECODE47 - Integration connections
- INLINECODE48 - x402 payments
- INLINECODE49 - Credits top-up
Triggers Factory
Use the triggers factory for type-safe trigger configuration:
CODEBLOCK7
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:
CODEBLOCK8
Cron Expressions
CODEBLOCK9
Common: 0 9 * * * (daily 9 AM), */5 * * * * (every 5 min), 0 9 * * 1-5 (weekdays 9 AM)
State Management
CODEBLOCK10
Discovering & Firing x402 Services
Discover Available Services (No Auth Required)
INLINECODE55 lists all public x402-enabled workflows. No authentication is needed — you can call it on a bare PlatformClient:
CODEBLOCK11
Firing Triggers
CODEBLOCK12
x402 (Programmatic)
CODEBLOCK13
Environment Variables
| Variable | Description | Required |
|---|
| INLINECODE57 | User API key (from platform) | Yes\ |
| INLINECODE58 |
Wallet for SIWE auth | Yes\ |
|
OPENSERV_API_URL | Custom API URL | No |
\*Either API key or wallet key required
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.
CODEBLOCK14
- - 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
CODEBLOCK15
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.
CODEBLOCK16
Or reinstall the OpenServ skills directly:
CODEBLOCK17
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
OpenServ 客户端
@openserv-labs/client 包是 OpenServ 平台 API 的 TypeScript 客户端。当你的代码需要与平台通信时——注册代理、创建工作流、设置触发器或运行任务——你都会用到它。
为什么需要这个包
你的代理（使用 @openserv-labs/sdk 构建）在你的机器或服务器上运行。在你告知平台之前，平台并不知道它的存在：代理是什么、在哪里可以访问它、以及如何触发它。客户端就是用来实现这一点的。它允许你创建平台账户（或复用现有账户）、注册代理、定义工作流和触发器（webhook、cron、手动或 x402 付费），并绑定凭据，以便你的代理能够接受任务。没有它，你的代理将无法进入平台或接收工作。
你可以用它做什么
- - Provision（配置） — 一次性设置：创建或复用账户（通过钱包）、注册代理、创建包含触发器和任务的工作流，并获取 API 密钥和认证令牌。通常在每次应用启动时调用一次 provision()；它是幂等的。
- Platform API（平台 API） — 通过 PlatformClient 实现完全控制：创建和列出代理、工作流、触发器和任务；触发触发器；运行工作流；管理凭据。当你需要比默认配置流程更多功能时使用。
- Model Parameters（模型参数） — 配置平台为代理任务使用的 LLM 模型和参数。在创建/更新代理时或通过 provision() 设置 model_parameters。
- Models API（模型 API） — 通过 client.models.list() 发现可用的 LLM 模型及其参数模式。
- x402 支付 — 将代理置于付费墙后；调用者在任务运行前按请求付费（例如 USDC）。Provision 可以设置 x402 触发器并返回付费墙 URL。
- ERC-8004 链上身份 — 在链上（Base）注册代理，铸造身份 NFT，并将服务元数据发布到 IPFS，以便其他人可以以标准方式发现和支付你的代理。
参考： reference.md（完整 API）· troubleshooting.md（常见问题）· examples/（可运行代码）
安装
bash
npm install @openserv-labs/client
快速开始：只需 provision() + run()
最简单的部署只需两个调用：provision() 和 run()。 仅此而已。
你需要在平台上有一个账户来注册代理和工作流。最简单的方法是让 provision() 为你创建一个：它会创建一个钱包并用它注册（无需邮箱）。该账户在每次运行时都会被复用。
参见 examples/agent.ts 获取完整的可运行示例。
关键点： provision() 是幂等的。每次应用启动时都调用它——无需先检查 isProvisioned()。
provision() 的作用
- 1. 创建或复用以太坊钱包（如果是新钱包则创建平台账户）
- 向 OpenServ 平台进行身份认证
- 创建或更新代理（幂等）
- 生成 API 密钥和认证令牌
- 将凭据绑定到代理实例（如果提供了 agent.instance）
- 创建或更新包含触发器和任务的工作流
- 创建工作流图（连接触发器到任务的边）
- 激活触发器并将工作流设置为运行状态
- 将状态持久化到 .openserv.json
工作流名称与目标
workflow 配置需要两个重要属性：
- - name（字符串）—— 这将成为 ERC-8004 中的代理名称。让它精炼、有力且令人难忘——这是用户看到的面向公众的品牌名称。像产品发布一样思考，而不是变量名。示例：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: 研究给定的主题 }
}
代理实例绑定（v1.1+）
将代理实例传递给 provision() 以实现自动凭据绑定：
typescript
const agent = new Agent({ systemPrompt: ... })
await provision({
agent: {
instance: agent, // 自动调用 agent.setCredentials()
name: my-agent,
description: ...,
modelparameters: { model: gpt-5, verbosity: medium, reasoningeffort: high } // 可选
},
workflow: { ... }
})
// agent 现在已设置 apiKey 和 authToken - 准备好运行 run()
await run(agent)
这消除了手动设置 OPENSERVAPIKEY 环境变量的需要。
模型参数
可选的 model_parameters 字段控制平台在执行代理任务时使用的 LLM 模型和参数（包括无运行能力和 generate() 调用）。如果未提供，则使用平台默认值。
typescript
await provision({
agent: {
instance: agent,
name: my-agent,
description: ...,
model_parameters: {
model: gpt-4o,
temperature: 0.5,
paralleltoolcalls: false
}
},
workflow: { ... }
})
发现可用模型及其参数：
typescript
const { models, default: defaultModel } = await client.models.list()
// models: [{ model: gpt-5, provider: openai, parameters: { ... } }, ...]
// default: gpt-5-mini
Provision 结果
typescript
interface ProvisionResult {
agentId: number
apiKey: string
authToken?: string
workflowId: number
triggerId: string
triggerToken: string
paywallUrl?: string // 用于 x402 触发器
apiEndpoint?: string // 用于 webhook 触发器
}
API 密钥：代理 vs 用户
provision() 创建两种类型的凭据。它们不可互换：
| 凭据 | 环境变量 | 使用者 | 用途 |
|---|
| 代理 API 密钥 | OPENSERVAPIKEY | SDK 内部 | 在从平台接收任务时对代理进行身份认证。通过 agent.instance 自动设置。不要与 PlatformClient 一起使用。 |
| 钱包密钥 |
WALLET
PRIVATEKEY | PlatformClient | 对管理调用（列出任务、调试工作流、管理代理）的账户进行身份认证。 |
| 用户 API 密钥 | OPENSERV
USERAPI_KEY | PlatformClient | 钱包认证的替代方案。从平台仪表板获取。 |
如果在使用 PlatformClient 时收到 401 未授权 错误，你可能错误地使用了代理 API 密钥。请改用钱包认证或用户 API 密钥。
PlatformClient：完整 API 访问
对于高级用例，直接使用 PlatformClient：
typescript
import { PlatformClient } from @openserv-labs/client
// 使用钱包认证（推荐——使用 provision 中的钱包）
const client = new PlatformClient()
await client.authenticate(process.env.WALLETPRIVATEKEY)
// 或使用用户 API 密钥（不是代理 API 密钥）
const client = new PlatformClient({
apiKey: process.env.OPENSERVUSERAPIKEY // 不是 OPENSERVAPI_KEY
})
参见 reference.md 获取以下完整 API 文档：
- - client.agents. - 代理管理
- client.workflows. - 工作流管理
- client.triggers. - 触发器管理
- client.tasks. - 任务管理
- client.models. - 可用 LLM 模型和参数
- client.integrations. - 集成连接
- client.payments. - x402 支付
- client.web3. - 积分充值
触发器工厂
使用 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 研究助手,
description: 获取任何主题
