• reference.md

  - Quick reference for common patterns

• troubleshooting.md

  - Common issues and solutions

• examples/

  - Complete code examples

• DISABLE_TUNNEL

  Env Var - Set

  DISABLE_TUNNEL=true

  for production deployments (e.g. Cloud Run).

  run()

  starts only the HTTP server, no WebSocket tunnel.

• FORCE_TUNNEL

  Env Var - Set

  FORCE_TUNNEL=true

  to force tunnel mode even when an

  endpointUrl

  is configured.
• Public Health Check - The

  /health

  route now responds before auth middleware, so the platform health cron can reach it without credentials.
• Binary Tunnel Responses - Tunnel responses are sent as binary frames, preserving gzip, images, and other binary payloads transparently.

• Built-in Tunnel - The

  run()

  function auto-connects to

  agents-proxy.openserv.ai

• No Endpoint URL Needed - Skip

  endpointUrl

  in

  provision()

  during development
• Automatic Port Fallback - If your port is busy, the agent finds an available one
• Direct Credential Binding -

  provision()

  can bind credentials directly to agent instance via

  agent.instance

• setCredentials()

  Method - Manually bind API key and auth token to agent

npm install @openserv-labs/sdk @openserv-labs/client zod openai

Note: The SDK requires

openai@^5.x

as a peer dependency.

examples/basic-agent.ts

1. Create an

   Agent

   with a system prompt
2. Add capabilities with

   agent.addCapability()

3. Call

   provision()

   to register on the platform (pass

   agent.instance

   to bind credentials)
4. Call

   run(agent)

   to start

npm init -y && npm pkg set type=module
npm i @openserv-labs/sdk @openserv-labs/client dotenv openai zod
npm i -D @types/node tsx typescript

Note: The project must use

"type": "module"

in

package.json

. Add a

"dev": "tsx src/agent.ts"

script for local development.

• name

  - Unique identifier

• description

  - What it does (helps AI decide when to use it)

• schema

  - Zod schema defining parameters

• run

  - Function returning a string

examples/capability-example.ts

workflow

provision()

• 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:

  'Crypto Alpha Scanner'

  ,

  'AI Video Studio'

  ,

  'Instant Blog Machine'

  .

• 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: 'Haiku Poetry Generator',  // Polished display name — the ERC-8004 agent name users see
  goal: 'Transform any theme or emotion into a beautiful traditional 5-7-5 haiku poem using AI',
  trigger: triggers.x402({ ... }),
  task: { description: 'Generate a haiku about the given topic' }
}

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

triggers.webhook({ waitForCompletion: true, timeout: 600 })
triggers.x402({ name: '...', description: '...', price: '0.01', timeout: 600 })
triggers.cron({ schedule: '0 9 * * *' })
triggers.manual()

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 when performing research, content generation, or other complex tasks. A low timeout will cause premature failures. For multi-agent pipelines with many sequential steps, consider 900 seconds or more.

npm run dev

run()

• Starts the agent HTTP server (port 7378, with automatic fallback)
• Connects via WebSocket to

  agents-proxy.openserv.ai

• Routes platform requests to your local machine

run()

run(agent)

Requires ETH on Base. Registration calls

register()

on the ERC-8004 contract on Base mainnet (chain 8453), which costs gas. The wallet created by

provision()

starts with a zero balance. Fund it with a small amount of ETH on Base before the first registration attempt. The wallet address is logged during provisioning (

Created new wallet: 0x...

).

Always wrap in try/catch so a registration failure (e.g. unfunded wallet) doesn't prevent

run(agent)

from starting.

1. Use

   dotenv

   programmatically (not

   import 'dotenv/config'

   ) so you can reload

   .env

   after

   provision()

   writes

   WALLET_PRIVATE_KEY

   .
2. Call

   dotenv.config({ override: true })

   after

   provision()

   to pick up the freshly written key before ERC-8004 registration.

import dotenv from 'dotenv'
dotenv.config()

import { Agent, run } from '@openserv-labs/sdk'
import { provision, triggers, PlatformClient } from '@openserv-labs/client'

// ... define agent and capabilities ...

const result = await provision({
  agent: { instance: agent, name: 'my-agent', description: '...' },
  workflow: {
    name: 'My Service',
    goal: 'Detailed description of what the workflow does',
    trigger: triggers.x402({ name: 'My Service', description: '...', price: '0.01', timeout: 600 }),
    task: { description: 'Process requests' },
  },
})

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

// Register on-chain (non-blocking — requires funded wallet on Base)
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 Service',
    description: 'What this agent does',
  })

  console.log(`Agent ID: ${erc8004.agentId}`)  // "8453:42"
  console.log(`TX: ${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)
}

await run(agent)

• First run mints a new identity NFT. Re-runs update the URI — agent ID stays the same.
• Never clear the wallet state unless you intentionally want a new agent ID. To update metadata, just re-run.
• Default chain: Base mainnet (8453). Pass

  chainId

  /

  rpcUrl

  for others.

• this.process()

  inside capabilities - Use direct OpenAI calls instead

• doTask

  override - The SDK handles task execution automatically

• this.completeTask()

  - Task completion is handled by the Runtime API

• openserv-client - Full Platform Client API reference
• 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