internet-court/internet-court-skill / vendored/openserv/openserv-agent-sdk
openserv-agent-sdk
VerifiedBuild and deploy autonomous AI agents using the OpenServ SDK (@openserv-labs/sdk). IMPORTANT - Always read the companion skill openserv-client alongside this skill, as both packages are required to build and run agents. openserv-client covers the full Platform API for multi-agent workflows and ERC-8004 on-chain identity. Read reference.md for the full API reference.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 346 B |
| SKILL.md | skill md | 19.2 KB |
| examples/basic-agent.ts | script | 1.7 KB |
| examples/capability-example.ts | script | 1.6 KB |
| examples/capability-with-agent-methods.ts | script | 1.9 KB |
| examples/env.example | other | 483 B |
| examples/error-handling.ts | script | 1.7 KB |
| examples/file-operations.ts | script | 1.6 KB |
| examples/haiku-poet-agent.ts | script | 2.0 KB |
| examples/multiple-capabilities.ts | script | 1.5 KB |
| examples/task-management.ts | script | 2.4 KB |
| reference.md | markdown | 10.9 KB |
| troubleshooting.md | markdown | 6.1 KB |
troubleshooting.md
View on GitHub# OpenServ SDK Troubleshooting
Common issues and solutions.
---
## "OpenServ API key is required"
**Error:** `Error: OpenServ API key is required. Please provide it in options, set OPENSERV_API_KEY environment variable, or call provision() first.`
**Cause:** The agent was started without credentials being set up.
**Solution:** Pass the agent instance to `provision()` for automatic credential binding:
```typescript
const agent = new Agent({ systemPrompt: '...' })
agent.addCapability({ ... })
await provision({
agent: {
instance: agent, // Binds credentials directly to agent (v2.1+)
name: 'my-agent',
description: '...'
},
workflow: { ... }
})
await run(agent) // Credentials already bound
```
The `provision()` function creates the wallet, API key, and auth token on first run. When you pass `agent.instance`, it calls `agent.setCredentials()` automatically, so you don't need to rely on environment variables.
---
## Port already in use (EADDRINUSE)
```bash
lsof -ti:7378 | xargs kill -9
```
Or set a different port in `.env`: `PORT=7379`
---
## "OPENSERV_AUTH_TOKEN is not set" warning
This is a security warning. The `provision()` function auto-generates this token. If missing, re-run provision or manually generate:
```typescript
const { authToken, authTokenHash } = await client.agents.generateAuthToken()
await client.agents.saveAuthToken({ id: agentId, authTokenHash })
// Save authToken to .env as OPENSERV_AUTH_TOKEN
```
---
## Trigger not firing
1. Check workflow is running: `await client.workflows.setRunning({ id: workflowId })`
2. Check trigger is active: `await client.triggers.activate({ workflowId, id: triggerId })`
3. Verify the trigger is connected to the task in the workflow graph
---
## Tunnel connection issues
The `run()` function connects via WebSocket to `agents-proxy.openserv.ai`. If connection fails:
1. Check internet connectivity
2. Verify no firewall blocking WebSocket connections
3. The agent retries with exponential backoff (up to 10 retries)
For production, set `DISABLE_TUNNEL=true` and use `run(agent)` — it will start only the HTTP server without the WebSocket tunnel. The platform reaches your agent directly at its public `endpointUrl`.
To force tunnel mode even when `endpointUrl` is configured, set `FORCE_TUNNEL=true`.
---
## OpenAI API errors (process() only)
`OPENAI_API_KEY` is only needed if you use the `process()` method for direct OpenAI calls. Most agents don't need it—use **runless capabilities** or `generate()` instead, which delegate LLM calls to the platform (no API key required).
If you do use `process()`:
- Verify `OPENAI_API_KEY` is set correctly
- Check API key has credits/billing enabled
- SDK requires `openai@^5.x` as a peer dependency
---
## ERC-8004 registration fails with "insufficient funds"
**Error:** `ContractFunctionExecutionError: insufficient funds for transfer`
**Cause:** The wallet created by `provision()` has no ETH on Base mainnet to pay gas.
**Solution:** Fund the wallet address logged during provisioning (`Created new wallet: 0x...`) with a small amount of ETH on Base. Always wrap `registerOnChain` in a try/catch so the agent can still start via `run(agent)`.
---
## ERC-8004 registration fails with 401 Unauthorized
**Error:** `AxiosError: Request failed with status code 401` during `client.authenticate()`
**Cause:** `WALLET_PRIVATE_KEY` is empty. `provision()` writes it to `.env` at runtime, but `process.env` already loaded the empty value at startup.
**Solution:** Use `dotenv` programmatically and reload after `provision()`:
```typescript
import dotenv from 'dotenv'
dotenv.config()
// ... provision() ...
dotenv.config({ override: true }) // reload to pick up WALLET_PRIVATE_KEY
```
Do **not** use `import 'dotenv/config'` — it only loads `.env` once at import time and cannot be reloaded.
---
## 401 Unauthorized when using PlatformClient for debugging
**Error:** `AxiosError: Request failed with status code 401` when calling `client.tasks.list()` or other `PlatformClient` methods.
**Cause:** You are using the **agent** API key (`OPENSERV_API_KEY`) instead of the **user** API key. These are different:
- **`OPENSERV_API_KEY`** — The agent's API key, set by `provision()`. Used internally by the agent to authenticate with the platform when receiving tasks. **Cannot** be used with `PlatformClient` for management calls.
- **`OPENSERV_USER_API_KEY`** — Your user/account API key. Required for `PlatformClient` calls like listing tasks, managing workflows, etc.
**Solution:** Authenticate `PlatformClient` using your wallet (recommended) or your user API key:
```typescript
// Option 1: Wallet authentication (recommended — uses the wallet from provision)
const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)
// Option 2: User API key (from platform dashboard, NOT the agent key)
const client = new PlatformClient({
apiKey: process.env.OPENSERV_USER_API_KEY // NOT OPENSERV_API_KEY
})
```
**Tip:** After `provision()` runs, the `WALLET_PRIVATE_KEY` is stored in `.env`. Use `dotenv.config({ override: true })` to reload it if needed (see the ERC-8004 401 section above).
---
## ESM / CommonJS import errors
**Error:** `SyntaxError: Named export 'Agent' not found` or `ERR_REQUIRE_ESM` or similar module resolution errors.
**Cause:** Mismatch between your project's module system and how you import the packages.
**Solution:** The recommended setup is ESM (`"type": "module"` in `package.json`) with `tsx` as the runtime:
```json
{
"type": "module",
"scripts": {
"dev": "tsx src/agent.ts"
}
}
```
```bash
npm i -D tsx typescript @types/node
```
Use standard ESM imports:
```typescript
import { Agent, run } from '@openserv-labs/sdk'
import { provision, triggers } from '@openserv-labs/client'
```
**If you must use CommonJS** (no `"type": "module"`), use dynamic `import()`:
```typescript
async function main() {
const { Agent, run } = await import('@openserv-labs/sdk')
const { provision, triggers } = await import('@openserv-labs/client')
// ... rest of your code
}
main()
```
**Do not** mix `require()` with ESM-only packages. If you see `ERR_REQUIRE_ESM`, switch to `"type": "module"` or use dynamic imports.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |