openserv-client

What this skill does

# 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

```bash
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

1. Creates or reuses an Ethereum wallet (and platform account if new)
2. Authenticates with the OpenServ platform
3. Creates or updates the agent (idempotent)
4. Generates API key and auth token
5. **Binds credentials to agent instance** (if `agent.instance` is provided)
6. Creates or updates the workflow with trigger and task
7. Creates workflow graph (edges linking trigger to task)
8. Activates trigger and sets workflow to running
9. 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.

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

### Agent Instance Binding (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: '...',
    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.

```typescript
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:

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

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

---

## 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` | `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:

```typescript
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