--- name: openserv-agent-sdk description: Build 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. ---

OpenServ Agent SDK

Build and deploy custom AI agents for the OpenServ platform using TypeScript.

Why build an agent?

An OpenServ agent is a service that runs your code and exposes it on the OpenServ platform—so it can be triggered by workflows, other agents, or paid calls (e.g. x402). The platform sends tasks to your agent; your agent runs your capabilities (APIs, tools, file handling) and returns results. You don't have to use an LLM—e.g. it could be a static API that just returns data. If you need LLM reasoning, you have two options: use runless capabilities (the platform handles the AI call for you—no API key needed) or use generate() (delegates the LLM call to the platform); alternatively, bring your own LLM (any provider you have access to).

How it works (the flow)

1. Define your agent — System prompt plus _capabilities_. Capabilities come in two flavors: runnable (with a Zod schema and a run handler) and runless (just a name and description—the platform handles the AI call automatically). You can also use generate() inside runnable capabilities to delegate LLM calls to the platform.
2. Register with the platform — You need an account on the platform; often the easiest way is to let provision() create one for you automatically by creating a wallet and signing up with it (that account is reused on later runs). Call provision() (from @openserv-labs/client): it creates or reuses a wallet, registers the agent, and writes API key and auth token into your env (or you pass agent.instance to bind them directly). In development you can skip setting an endpoint URL; the SDK can use a built-in tunnel to the platform.
3. Start the agent — Call run(agent). The agent listens for tasks, runs your capabilities (and your LLM if you use one), and responds. Use reference.md and troubleshooting.md for details; examples/ has full runnable code.

What your agent can do

• Runless Capabilities — Just a name and description. The platform handles the AI call automatically—no API key, no run() function needed. Optionally define inputSchema and outputSchema for structured I/O.
• Runnable Capabilities — The tools your agent can run (e.g. search, transform data, call APIs). Each has a name, description, inputSchema, and run() function.
• generate() method — Delegate LLM calls to the platform from inside any runnable capability. No API key needed—the platform performs the call and records usage. Supports text and structured output.
• Task context — When running in a task, the agent can attach logs and uploads to that task via methods like addLogToTask() and uploadFile().
• Multi-agent workflows — Your agent can be part of workflows with other agents; see the openserv-client skill for the Platform API, workflows, and ERC-8004 on-chain identity.

Reference: reference.md (patterns) · troubleshooting.md (common issues) · examples/ (full examples)

Quick Start

Installation

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

> Note: openai 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.

Minimal Agent

See examples/basic-agent.ts for a complete runnable example.

The pattern is simple:

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

---

Complete Agent Template

File Structure

my-agent/
├── src/agent.ts
├── .env
├── .gitignore
├── package.json
└── tsconfig.json

Dependencies

npm init -y && npm pkg set type=module
npm i @openserv-labs/sdk @openserv-labs/client dotenv 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. Only install openai if you use the process() method for direct OpenAI calls.

.env

Most agents don't need any LLM API key—use runless capabilities or generate() and the platform handles LLM calls for you. If you use process() for direct OpenAI calls, set OPENAI_API_KEY. The rest is filled by provision().

# Only needed if you use process() for direct OpenAI calls:
# OPENAI_API_KEY=your-openai-key
# ANTHROPIC_API_KEY=your_anthropic_key  # If using Claude directly

# Auto-populated by provision():
WALLET_PRIVATE_KEY=
OPENSERV_API_KEY=
OPENSERV_AUTH_TOKEN=
PORT=7378
# Production: skip tunnel and run HTTP server only
# DISABLE_TUNNEL=true
# Force tunnel even when endpointUrl is set
# FORCE_TUNNEL=true

---

Capabilities

Capabilities come in two flavors:

Runless Capabilities (recommended for most use cases)

Runless capabilities don't need a run function—the platform handles the AI call automatically. Just provide a name and description:

// Simplest form — just name + description
agent.addCapability({
  name: 'generate_haiku',
  description: 'Generate a haiku poem (5-7-5 syllables) about the given input.'
})

// With custom input schema
agent.addCapability({
  name: 'translate',
  description: 'Translate text to the target language.',
  inputSchema: z.object({
    text: z.string(),
    targetLanguage: z.string()
  })
})

// With structured output
agent.addCapability({
  name: 'analyze_sentiment',
  description: 'Analyze the sentiment of the given text.',
  outputSchema: z.object({
    sentiment: z.enum(['positive', 'negative', 'neutral']),
    confidence: z.number().min(0).max(1)
  })
})

• No run function — the platform performs the LLM call
• No API key needed — the platform handles it
• inputSchema is optional — defaults to z.object({ input: z.string() }) if omitted
• outputSchema is optional — define it for structured output from the platform

See examples/haiku-poet-agent.ts for a complete runless example.

Runnable Capabilities

Runnable capabilities have a run function for custom logic. Each requires:

• name - Unique identifier
• description - What it does (helps AI decide when to use it)
• inputSchema - Zod schema defining parameters
• run - Function returning a string

agent.addCapability({
  name: 'greet',
  description: 'Greet a user by name',
  inputSchema: z.object({ name: z.string() }),
  async run({ args }) {
    return `Hello, ${args.name}!`
  }
})

See examples/capability-example.ts for basic capabilities.

> Note: The schema property still works as an alias for inputSchema but is deprecated. Use inputSchema for new code.

Using Agent Methods

Access this in capabilities to use agent methods like addLogToTask(), uploadFile(), generate(), etc.

See examples/capability-with-agent-methods.ts for logging and file upload patterns.

---

Agent Methods

generate() — Platform-Delegated LLM Calls

The generate() method lets you make LLM calls without any API key. The platform performs the call and records usage to the workspace.

// Text generation
const poem = await this.generate({
  prompt: `Write a short poem about ${args.topic}`,
  action
})

// Structured output (returns validated object matching the schema)
const metadata = await this.generate({
  prompt: `Suggest a title and 3 tags for: ${poem}`,
  outputSchema: z.object({
    title: z.string(),
    tags: z.array(z.string()).length(3)
  }),
  action
})

...