openserv-client

OpenServ クライアント

@openserv-labs/client パッケージは、OpenServ Platform API 用の TypeScript クライアントです。コードからプラットフォームと通信する必要があるとき——エージェントの登録、ワークフローの作成、トリガーの設定、タスクの実行など——にこれを使用します。

このパッケージが必要な理由

あなたのエージェント（@openserv-labs/sdk で構築）は、あなたのマシンまたはサーバー上で動作します。プラットフォームは、あなたがそれを伝えるまでエージェントの存在を知りません。エージェントが何であるか、どこから到達できるか、どのようにトリガーできるかを伝える必要があります。クライアントはそのための手段です。プラットフォームアカウントの作成（または既存のものの再利用）、エージェントの登録、ワークフローとトリガー（webhook、cron、手動、または x402 有料）の定義、そしてエージェントがタスクを受け入れられるように認証情報をバインドできます。これがなければ、エージェントをプラットフォームに載せたり、仕事を受け取ったりする方法がありません。

これでできること

• プロビジョニング — ワンショットのセットアップ：アカウントの作成または再利用（ウォレット経由）、エージェントの登録、トリガーとタスクを伴うワークフローの作成、API キーと認証トークンの取得。通常、アプリ起動ごとに provision() を 1 回呼び出します。これは冪等です。
• プラットフォーム API — PlatformClient による完全な制御：エージェント、ワークフロー、トリガー、タスクの作成と一覧表示、トリガーの発火、ワークフローの実行、認証情報の管理。デフォルトのプロビジョンフロー以上のことが必要な場合に使用します。
• モデルパラメータ — プラットフォームがエージェントのタスクに使用する LLM モデルとパラメータを設定します。エージェントの作成/更新時、または provision() 経由で model_parameters を設定します。
• Models API — client.models.list() を介して、利用可能な LLM モデルとそのパラメータスキーマを検出します。
• x402 支払い — エージェントをペイウォールの背後に公開します。呼び出し元はタスクが実行される前にリクエストごとに支払います（例：USDC）。プロビジョニングで x402 トリガーをセットアップし、ペイウォール URL を返すことができます。
• ERC-8004 オンチェーンアイデンティティ — エージェントをオンチェーン（Base）に登録し、アイデンティティ NFT をミントし、サービスメタデータを IPFS に公開して、他のユーザーが標準的な方法でエージェントを発見して支払えるようにします。

リファレンス: reference.md（完全な API）· troubleshooting.md（よくある問題）· examples/（実行可能なコード）

インストール

npm install @openserv-labs/client

---

クイックスタート：provision() + run() だけ

最もシンプルなデプロイは 2 つの呼び出しだけです：provision() と run()。 それだけです。

エージェントとワークフローを登録するには、プラットフォーム上のアカウントが必要です。最も簡単な方法は、provision() にアカウントを作成させることです。ウォレットを作成し、それでサインアップします（メールは不要）。そのアカウントは毎回の実行で再利用されます。

完全な実行可能な例については examples/agent.ts を参照してください。

重要ポイント: provision() は冪等です。アプリの起動ごとに呼び出してください——最初に isProvisioned() を確認する必要はありません。

provision() が行うこと

1. Ethereum ウォレット（および新規の場合はプラットフォームアカウント）を作成または再利用します
2. OpenServ プラットフォームで認証します
3. エージェントを作成または更新します（冪等）
4. API キーと認証トークンを生成します
5. エージェントインスタンスに認証情報をバインドします（agent.instance が指定されている場合）
6. トリガーとタスクを伴うワークフローを作成または更新します
7. ワークフローグラフを作成します（トリガーをタスクにリンクするエッジ）
8. トリガーをアクティブ化し、ワークフローを実行中に設定します
9. 状態を .openserv.json に永続化します

ワークフロー名と目標

workflow 設定には 2 つの重要なプロパティが必要です：

• name（文字列） - これは ERC-8004 のエージェント名になります。洗練された、印象的で、記憶に残るものにしてください——これはユーザーが見る公開向けのブランド名です。変数名ではなく、製品の立ち上げをイメージしてください。例：'Viral Content Engine'、'Crypto Alpha Scanner'、'Life Catalyst Pro'。
• goal（文字列、必須） - ワークフローが何を達成するかの詳細な説明です。説明的で徹底したものでなければなりません——短すぎるまたは曖昧な目標は API 呼び出しの失敗を引き起こします。ワークフローの目的を説明する完全な文を少なくとも 1 つ書いてください。

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

エージェントインスタンスのバインド（v1.1+）

自動的な認証情報のバインドのために、エージェントインスタンスを provision() に渡します：

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)

これにより、OPENSERV_API_KEY 環境変数を手動で設定する必要がなくなります。

モデルパラメータ

オプションの model_parameters フィールドは、プラットフォームがエージェントのタスクを実行する際に使用する LLM モデルとパラメータを制御します（runless 機能や generate() 呼び出しを含む）。指定しない場合は、プラットフォームのデフォルトが使用されます。

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 // For x402 triggers
  apiEndpoint?: string // For webhook triggers
}

---

API キー: エージェント用とユーザー用

provision() は 2 種類の認証情報を作成します。これらは互換性がありません:

認証情報	環境変数	使用元	目的
エージェント 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'

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

以下に関する完全な API ドキュメントは reference.md を参照してください:

• client.agents.* - エージェント管理
• client.workflows.* - ワークフロー管理
• client.triggers.* - トリガー管理
• client.tasks.* - タスク管理
• client.models.* - 利用可能な LLM モデルとパラメータ
• client.integrations.* - 統合接続
• client.payments.* - x402 決済
• client.web3.* - クレジットのチャージ

---

Triggers ファクトリ

型安全なトリガー設定には triggers ファクトリを使用します:

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

タイムアウト

重要: webhook トリガーおよび x402 トリガーでは、timeout を常に最低 600 秒（10 分）に設定してください。エージェントはリクエストの処理にかなりの時間がかかることがよくあります。特にマルチエージェントワークフローや、リサーチ、コンテンツ生成、その他の複雑なタスクを実行する場合に顕著です。タイムアウトが短すぎる（例: 180 秒）と、途中で失敗する原因になります。判断に迷った場合は、より長いタイムアウトを選んでください。多数の逐次ステップを含むマルチエージェントパイプラインでは、900 秒以上を検討してください。

入力スキーマ

webhook/x402 ペイウォール 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 式

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

よく使われるもの: 0 9 * * *（毎日午前 9 時）、*/5 * * * *（5 分ごと）、0 9 * * 1-5（平日午前 9 時）

---

OpenServ Cloud へのデプロイ

以下のコマンドでエージェントを OpenServ のマネージドクラウドにデプロイします:

npx @openserv-labs/client deploy [path]

ここで [path] はエージェントのコードを含むディレクトリです（デフォルトはカレントディレクトリ）。

前提条件

1. .env 内の OPENSERV_USER_API_KEY — エージェントディレクトリの .env ファイルに OPENSERV_USER_API_KEY が含まれている必要があります。これは OpenServ プラットフォームのダッシュボードから取得してください。このキーはデプロイコマンド（および管理操作のための PlatformClient）で必要です。provision() 自体はこのキーを必要としないことに注意してください — 独自のウォレットを作成し、認証を行い、資格情報を .openserv.json に独立して永続化します。ユーザー API キーは、存在する場合、プロビジョニング後に .openserv.json にも保存されます。

2. 最初に provision() を呼び出す — provision() はデプロイ前に少なくとも一度は実行する必要があります。これはエージェントをプラットフォームに登録し、資格情報を .openserv.json に永続化します。推奨されるエージェントテンプレートはすでに main() 内で run(agent) の前に provision() を呼び出しているため、エージェントをローカルで起動する（npm run dev または npx tsx src/agent.ts）だけで十分です。コードが provision() を呼び出していない場合（たとえば、カスタムスクリプトで run(agent) のみを呼び出している場合）、明示的な provision() 呼び出しを追加し、デプロイ前に一度実行する必要があります。

デプロイワークフロー

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 .

---

状態管理

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

---

x402 サービスの検出と実行

利用可能なサービスの検出（認証不要）

discoverServices() は、公開されているすべての x402 対応ワークフローを一覧表示します。認証は不要です — 素の 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}`)
}

トリガーの実行

// 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（プログラムによる実行）

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

---

環境変数

変数	説明	必須
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: オンチェーンエージェントアイデンティティ

プロビジョニング後にエージェントをオンチェーンに登録します。これにより、Identity Registry 上で NFT がミントされ、エージェントのサービスエンドポイントが IPFS に公開されます。

Base 上の ETH が必要です。 provision() によって作成されたウォレットは残高ゼロで開始します。登録前に Base メインネット上の少量の ETH を入金してください。失敗しても run(agent) の起動が妨げられないよう、常に try/catch でラップしてください。

provision() の後に .env を再読み込みしてください。 provision() は実行時に WALLET_PRIVATE_KEY を .env に書き込みますが、process.env は起動時に空の値をすでに読み込んでいます。provision() の後に dotenv.config({ override: true }) を使用して、新しく書き込まれたキーを取得してください。完全な dotenv パターンについては openserv-agent-sdk スキルを参照してください。

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

• 初回実行で新しい 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 の変更、バグ修正は、更新するまでここに反映されません。何かが期待どおりに動作しない場合、または最新の情報を確実に入手したい場合は、続行する前にスキルを更新してください。

# Check if updates are available
npx skills check

# Update all installed skills to latest versions
npx skills update

または、OpenServ スキルを直接再インストールします:

npx skills add openserv-labs/skills

---

関連スキル

• openserv-agent-sdk - 機能を備えたエージェントの構築
• openserv-multi-agent-workflows - マルチエージェント連携のパターン
• openserv-launch - Base ブロックチェーンでのトークン発行
• openserv-ideaboard-api - Ideaboard でアイデアを見つけ、エージェントサービスを提供