OpenServ Agent SDK - 使用TypeScript构建和部署自定义AI智能体

openserv-agent-sdk by openserv-labs/skills

101 周安装量

13 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/openserv-labs/skills --skill openserv-agent-sdk

AI/机器学习自动化 TypeScript

🇨🇳中文介绍

OpenServ Agent SDK

使用 TypeScript 为 OpenServ 平台构建和部署自定义 AI 智能体。

为什么要构建智能体？

OpenServ 智能体是一种运行您的代码并将其暴露在 OpenServ 平台上的服务——因此它可以被工作流、其他智能体或付费调用（例如 x402）触发。平台向您的智能体发送任务；您的智能体运行您的能力（API、工具、文件处理）并返回结果。您不必使用 LLM——例如，它可以是一个只返回数据的静态 API。如果您需要 LLM 推理，您有两个选择：使用 无运行能力（平台为您处理 AI 调用——无需 API 密钥）或使用 generate()（将 LLM 调用委托给平台）；或者，使用您自己的 LLM（您有权访问的任何提供商）。

工作原理（流程）

定义您的智能体 — 系统提示加上能力。能力有两种类型：可运行的（带有 Zod 模式和一个 run 处理函数）和 无运行的（仅名称和描述——平台自动处理 AI 调用）。您也可以在可运行能力内部使用 generate() 将 LLM 调用委托给平台。
在平台注册 — 您需要在平台上有一个账户；通常最简单的方法是让 provision() 通过创建钱包并用它注册来自动为您创建一个（该账户在后续运行中会被重用）。调用 provision()（来自 @openserv-labs/client）：它会创建或重用钱包，注册智能体，并将 API 密钥和身份验证令牌写入您的环境变量（或者您传递来直接绑定它们）。在开发中，您可以跳过设置端点 URL；SDK 可以使用内置隧道连接到平台。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

您的智能体能做什么

无运行能力 — 仅名称和描述。平台自动处理 AI 调用——无需 API 密钥，无需 run() 函数。可选地定义 inputSchema 和 outputSchema 用于结构化输入/输出。
可运行能力 — 您的智能体可以运行的工具（例如搜索、转换数据、调用 API）。每个都有名称、描述、inputSchema 和 run() 函数。
generate() 方法 — 从任何可运行能力内部将 LLM 调用委托给平台。无需 API 密钥——平台执行调用并记录使用情况。支持文本和结构化输出。
任务上下文 — 在任务中运行时，智能体可以通过 addLogToTask() 和 uploadFile() 等方法将日志和上传内容附加到该任务。
多智能体工作流 — 您的智能体可以成为与其他智能体一起的工作流的一部分；请参阅 openserv-client 技能以了解平台 API、工作流和链上身份 ERC-8004。

参考： reference.md（模式） · troubleshooting.md（常见问题） · examples/（完整示例）

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

注意： 仅当您使用 process() 方法进行直接 OpenAI 调用时才需要 openai。大多数智能体不需要它——请使用无运行能力或 generate() 代替。

完整可运行示例请参阅 examples/basic-agent.ts。

使用系统提示创建一个 Agent
使用 agent.addCapability() 添加能力
调用 provision() 在平台注册（传递 agent.instance 以绑定凭证）
调用 run(agent) 启动

完整智能体模板

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

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

注意： 项目必须在 package.json 中使用 "type": "module"。为本地开发添加一个 "dev": "tsx src/agent.ts" 脚本。仅当您使用 process() 方法进行直接 OpenAI 调用时才安装 openai。

大多数智能体不需要任何 LLM API 密钥——使用 无运行能力 或 generate()，平台会为您处理 LLM 调用。如果您使用 process() 进行直接 OpenAI 调用，请设置 OPENAI_API_KEY。其余部分由 provision() 填充。

# 仅在使用 process() 进行直接 OpenAI 调用时需要：
# OPENAI_API_KEY=your-openai-key
# ANTHROPIC_API_KEY=your_anthropic_key  # 如果直接使用 Claude

# 部署所需（从 OpenServ 平台仪表板获取）
OPENSERV_USER_API_KEY=your-user-api-key

# 由 provision() 自动填充：
WALLET_PRIVATE_KEY=
OPENSERV_API_KEY=
OPENSERV_AUTH_TOKEN=
PORT=7378
# 生产环境：跳过隧道，仅运行 HTTP 服务器
# DISABLE_TUNNEL=true
# 即使设置了 endpointUrl 也强制使用隧道
# FORCE_TUNNEL=true

能力有两种类型：

无运行能力（推荐用于大多数用例）

无运行能力不需要 run 函数——平台自动处理 AI 调用。只需提供名称和描述：

// 最简单形式 — 仅名称 + 描述
agent.addCapability({
  name: 'generate_haiku',
  description: '根据给定输入生成一首俳句诗（5-7-5 音节）。'
})

// 带有自定义输入模式
agent.addCapability({
  name: 'translate',
  description: '将文本翻译成目标语言。',
  inputSchema: z.object({
    text: z.string(),
    targetLanguage: z.string()
  })
})

// 带有结构化输出
agent.addCapability({
  name: 'analyze_sentiment',
  description: '分析给定文本的情感。',
  outputSchema: z.object({
    sentiment: z.enum(['positive', 'negative', 'neutral']),
    confidence: z.number().min(0).max(1)
  })
})

无 run 函数 — 平台执行 LLM 调用
无需 API 密钥 — 平台处理
inputSchema 是可选的 — 如果省略，默认为 z.object({ input: z.string() })
outputSchema 是可选的 — 定义它以从平台获取结构化输出

完整无运行示例请参阅 examples/haiku-poet-agent.ts。

可运行能力有一个用于自定义逻辑的 run 函数。每个都需要：

name - 唯一标识符
description - 它的作用（帮助 AI 决定何时使用它）
inputSchema - 定义参数的 Zod 模式
run - 返回字符串的函数

agent.addCapability({ name: 'greet', description: '按名称问候用户', inputSchema: z.object({ name: z.string() }), async run({ args }) { return Hello, ${args.name}! } })

基本能力示例请参阅 examples/capability-example.ts。

注意： schema 属性仍然可以作为 inputSchema 的别名使用，但已弃用。新代码请使用 inputSchema。

使用智能体方法

在能力中访问 this 以使用智能体方法，如 addLogToTask()、uploadFile()、generate() 等。

日志记录和文件上传模式请参阅 examples/capability-with-agent-methods.ts。

`generate()` — 平台委托的 LLM 调用

generate() 方法允许您无需任何 API 密钥即可进行 LLM 调用。平台执行调用并将使用情况记录到工作区。

// 文本生成
const poem = await this.generate({
  prompt: `写一首关于 ${args.topic} 的短诗`,
  action
})

// 结构化输出（返回经过验证的、符合模式的对象的）
const metadata = await this.generate({
  prompt: `为以下内容建议一个标题和 3 个标签：${poem}`,
  outputSchema: z.object({
    title: z.string(),
    tags: z.array(z.string()).length(3)
  }),
  action
})

// 带有对话历史
const followUp = await this.generate({
  prompt: '建议一个相关主题。',
  messages,  // 来自 run 函数的对话历史
  action
})

prompt (string) — 给 LLM 的提示
action (ActionSchema) — 操作上下文（传入您的 run 函数）
outputSchema (Zod 模式，可选) — 提供时，返回经过验证的结构化输出
messages (数组，可选) — 用于多轮生成的对话历史

action 参数是必需的，因为它标识了用于计费的工作区/任务。在可运行能力内部使用它，其中 action 可从 run 函数参数中获得。

await agent.createTask({ workspaceId, assignee, description, body, input, dependencies })
await agent.updateTaskStatus({ workspaceId, taskId, status: 'in-progress' })
await agent.addLogToTask({ workspaceId, taskId, severity: 'info', type: 'text', body: '...' })
await agent.markTaskAsErrored({ workspaceId, taskId, error: 'Something went wrong' })
const task = await agent.getTaskDetail({ workspaceId, taskId })
const tasks = await agent.getTasks({ workspaceId })

const files = await agent.getFiles({ workspaceId })
await agent.uploadFile({ workspaceId, path: 'output.txt', file: 'content', taskIds: [taskId] })
await agent.deleteFile({ workspaceId, fileId })

能力中的 action 参数是一个 联合类型 — task 仅存在于 'do-task' 变体中。在访问 action.task 之前，始终使用类型守卫进行缩小：

async run({ args, action }) {
  // action.task 并非在所有 action 类型上都存在 — 您必须先缩小范围
  if (action?.type === 'do-task' && action.task) {
    const { workspace, task } = action
    workspace.id        // 工作区 ID
    workspace.goal      // 工作区目标
    task.id             // 任务 ID
    task.description    // 任务描述
    task.input          // 任务输入
    action.me.id        // 当前智能体 ID
  }
}

不要在类型守卫之前提取 action?.task?.id — TypeScript 会报错 Property 'task' does not exist on type 'ActionSchema'。

工作流名称与目标

provision() 中的 workflow 对象需要两个重要属性：

name (string) - 这将成为 ERC-8004 中的智能体名称。使其精炼、有力且令人难忘——这是用户看到的面向公众的品牌名称。考虑产品发布，而不是变量名。示例：'Crypto Alpha Scanner'、'AI Video Studio'、'Instant Blog Machine'。
goal (string, 必需) - 工作流实现目标的详细描述。必须具有描述性且详尽——简短或模糊的目标将导致 API 调用失败。至少写一个完整的句子来解释工作流的目的。

workflow: { name: 'Haiku Poetry Generator', // 精炼的显示名称 — 用户看到的 ERC-8004 智能体名称 goal: '使用 AI 将任何主题或情感转化为优美的传统 5-7-5 俳句诗', trigger: triggers.x402({ ... }), task: { description: '生成一首关于给定主题的俳句' } }

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

重要： 对于 webhook 和 x402 触发器，始终将 timeout 设置为至少 600 秒（10 分钟）。智能体通常需要大量时间来处理请求——尤其是在执行研究、内容生成或其他复杂任务时。超时时间过短将导致过早失败。对于具有许多连续步骤的多智能体管道，请考虑 900 秒或更长。

API 密钥：智能体 vs 用户

provision() 创建两种类型的凭证。它们 不可互换：

OPENSERV_API_KEY (智能体 API 密钥) — 由 SDK 在接收任务时用于内部身份验证。当您传递 agent.instance 时，由 provision() 自动设置。请勿将此密钥与 PlatformClient 一起使用。
WALLET_PRIVATE_KEY / OPENSERV_USER_API_KEY (用户凭证) — 与 PlatformClient 一起使用以进行管理调用（列出任务、调试工作流等）。使用 client.authenticate(walletKey) 进行身份验证，或将 apiKey 传递给构造函数。

如果您需要调试任务或检查工作流，请使用钱包身份验证：

const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)
const tasks = await client.tasks.list({ workflowId: result.workflowId })

关于 401 错误的详细信息，请参阅 troubleshooting.md。

run() 函数自动：

启动智能体 HTTP 服务器（端口 7378，带自动回退）
通过 WebSocket 连接到 agents-proxy.openserv.ai
将平台请求路由到您的本地机器

无需 ngrok 或其他隧道工具 - run() 无缝处理此问题。只需调用 run(agent)，您的本地智能体即可被平台访问。

部署到 OpenServ 云

使用单个命令将您的智能体部署到 OpenServ 托管云：

npx @openserv-labs/client deploy [path]

其中 [path] 是包含您智能体代码的目录（默认为当前目录）。

.env 中的 OPENSERV_USER_API_KEY — 您智能体目录中的 .env 文件必须包含 OPENSERV_USER_API_KEY。从 OpenServ 平台仪表板获取此密钥。此密钥是部署命令（以及 PlatformClient 用于管理操作）所必需的。请注意，provision() 本身 不需要 此密钥——它会创建自己的钱包、进行身份验证，并将凭证独立地持久化到 .openserv.json。如果存在，用户 API 密钥在 provision 后也会保存到 .openserv.json。
首先调用 provision() — 在部署之前，provision() 必须至少运行一次。它在平台上注册智能体并将凭证持久化到 .openserv.json。推荐的智能体模板已经在 main() 中的 run(agent) 之前调用了 provision()，因此在本地启动智能体（npm run dev 或 npx tsx src/agent.ts）就足够了。如果您的代码不调用 provision()（例如，您只在自定义脚本中调用 run(agent)），则必须添加显式的 provision() 调用并在部署前运行一次。

1. 在 .env 中设置 OPENSERV_USER_API_KEY
2. 在本地启动期间调用 provision() (npm run dev) — 注册智能体并写入 .openserv.json
3. npx @openserv-labs/client deploy .

自托管生产环境

当部署到像 Cloud Run 这样的托管提供商时，将 DISABLE_TUNNEL=true 设置为环境变量。这使得 run() 仅启动 HTTP 服务器而不打开 WebSocket 隧道——平台直接在其公共 URL 处访问您的智能体。

await provision({
  agent: {
    name: 'my-agent',
    description: '...',
    endpointUrl: 'https://my-agent.example.com' // 生产环境必需
  },
  workflow: {
    name: 'Lightning Service Pro',
    goal: '详细描述此工作流的作用 — 要详尽，模糊的目标会导致失败',
    trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),
    task: { description: '处理传入请求' }
  }
})

// 当 DISABLE_TUNNEL=true 时，run() 仅启动 HTTP 服务器（无隧道）
await run(agent)

ERC-8004：链上智能体身份

配置后，在链上注册您的智能体，以便通过身份注册表进行发现。

需要在 Base 上有 ETH。 注册会在 Base 主网（链 8453） 上的 ERC-8004 合约上调用 register()，这需要消耗 gas。由 provision() 创建的钱包初始余额为零。在首次注册尝试之前，请用少量 Base 上的 ETH 为其注资。钱包地址在配置期间记录（Created new wallet: 0x...）。

始终用 try/catch 包装，以便注册失败（例如，未注资的钱包）不会阻止 run(agent) 启动。

两个重要模式：

以编程方式使用 dotenv（而不是 import 'dotenv/config'），以便您可以在 provision() 写入 WALLET_PRIVATE_KEY 后重新加载 .env。
在 provision() 之后调用 dotenv.config({ override: true })，以便在 ERC-8004 注册之前获取新写入的密钥。

import dotenv from 'dotenv'

dotenv.config()

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

// ... 定义智能体和能力 ...

const result = await provision({
  agent: { instance: agent, name: 'my-agent', description: '...' },
  workflow: {
    name: 'My Service',
    goal: '工作流作用的详细描述',
    trigger: triggers.x402({ name: 'My Service', description: '...', price: '0.01', timeout: 600 }),
    task: { description: '处理请求' }
  }
})

// 重新加载 .env 以获取由 provision() 写入的 WALLET_PRIVATE_KEY
dotenv.config({ override: true })

// 链上注册（非阻塞 — 需要在 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: '此智能体的作用'
  })

  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 注册已跳过：', error instanceof Error ? error.message : error)
}

await run(agent)

首次运行 铸造一个新的身份 NFT。重新运行更新 URI — 智能体 ID 保持不变。
切勿清除钱包状态，除非您有意想要一个新的智能体 ID。要更新元数据，只需重新运行。
默认链：Base 主网 (8453)。对于其他链，传递 chainId / rpcUrl。

完整的 ERC-8004 API 参考和故障排除，请参阅 openserv-client 技能。

能力内部的 this.process() — 需要 OpenAI API 密钥的遗留方法。请改用 this.generate()（平台委托，无需密钥），或使用无运行能力
doTask 覆盖 — SDK 自动处理任务执行
this.completeTask() — 任务完成由 Runtime API 处理

此技能可能已过时。OpenServ 团队定期发布更新——新功能、API 更改和错误修复在您更新之前不会反映在此处。如果某些功能未按预期工作，或者您想确保拥有最新信息，请在继续之前更新技能。

# 检查是否有可用更新
npx skills check

# 将所有已安装技能更新到最新版本
npx skills update

或者直接重新安装 OpenServ 技能：

npx skills add openserv-labs/skills

openserv-client - 完整的平台客户端 API 参考
openserv-multi-agent-workflows - 多智能体协作模式
openserv-launch - 在 Base 区块链上启动代币
openserv-ideaboard-api - 在创意板上寻找想法并发布智能体服务

🇺🇸English

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)

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

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:

Create an Agent with a system prompt
Add capabilities with agent.addCapability()
Call provision() to register on the platform (pass agent.instance to bind credentials)
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

# Required for deploy (get from OpenServ platform dashboard)
OPENSERV_USER_API_KEY=your-user-api-key

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

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

// With conversation history
const followUp = await this.generate({
  prompt: 'Suggest a related topic.',
  messages,  // conversation history from run function
  action
})

Parameters:

prompt (string) — The prompt for the LLM
action (ActionSchema) — The action context (passed into your run function)
outputSchema (Zod schema, optional) — When provided, returns a validated structured output
messages (array, optional) — Conversation history for multi-turn generation

The action parameter is required because it identifies the workspace/task for billing. Use it inside runnable capabilities where action is available from the run function arguments.

Task Management

await agent.createTask({ workspaceId, assignee, description, body, input, dependencies })
await agent.updateTaskStatus({ workspaceId, taskId, status: 'in-progress' })
await agent.addLogToTask({ workspaceId, taskId, severity: 'info', type: 'text', body: '...' })
await agent.markTaskAsErrored({ workspaceId, taskId, error: 'Something went wrong' })
const task = await agent.getTaskDetail({ workspaceId, taskId })
const tasks = await agent.getTasks({ workspaceId })

File Operations

const files = await agent.getFiles({ workspaceId })
await agent.uploadFile({ workspaceId, path: 'output.txt', file: 'content', taskIds: [taskId] })
await agent.deleteFile({ workspaceId, fileId })

Action Context

The action parameter in capabilities is a union type — task only exists on the 'do-task' variant. Always narrow with a type guard before accessing action.task:

async run({ args, action }) {
  // action.task does NOT exist on all action types — you must narrow first
  if (action?.type === 'do-task' && action.task) {
    const { workspace, task } = action
    workspace.id        // Workspace ID
    workspace.goal      // Workspace goal
    task.id             // Task ID
    task.description    // Task description
    task.input          // Task input
    action.me.id        // Current agent ID
  }
}

Do not extract action?.task?.id before the type guard — TypeScript will error with Property 'task' does not exist on type 'ActionSchema'.

Workflow Name & Goal

The workflow object in provision() 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: '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' } }

Trigger Types

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.

API Keys: Agent vs User

provision() creates two types of credentials. They are not interchangeable :

OPENSERV_API_KEY (Agent API key) — Used internally by the SDK to authenticate when receiving tasks. Set automatically by provision() when you pass agent.instance. Do not use this key with PlatformClient.
WALLET_PRIVATE_KEY / OPENSERV_USER_API_KEY (User credentials) — Used with PlatformClient to make management calls (list tasks, debug workflows, etc.). Authenticate with client.authenticate(walletKey) or pass apiKey to the constructor.

If you need to debug tasks or inspect workflows, use wallet authentication:

const client = new PlatformClient()
await client.authenticate(process.env.WALLET_PRIVATE_KEY)
const tasks = await client.tasks.list({ workflowId: result.workflowId })

See troubleshooting.md for details on 401 errors.

Deployment

Local Development

npm run dev

The run() function automatically:

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

No need for ngrok or other tunneling tools - run() handles this seamlessly. Just call run(agent) and your local agent is accessible to the platform.

Deploy to OpenServ Cloud

Deploy your agent to the OpenServ managed cloud with a single command:

npx @openserv-labs/client deploy [path]

Where [path] is the directory containing your agent code (defaults to current directory).

Prerequisites

OPENSERV_USER_API_KEY in .env — Your .env file in the agent directory must contain OPENSERV_USER_API_KEY. Get this from the OpenServ platform dashboard. This key is required by the deploy command (and by PlatformClient for management operations). Note that provision() itself does not need this key — it creates its own wallet, authenticates, and persists credentials to .openserv.json independently. The user API key is also saved to .openserv.json after provision if present.
Callprovision() first — must run at least once before deploying. It registers the agent on the platform and persists credentials to . The recommended agent template already calls before in , so starting the agent locally ( or ) is enough. If your code does not call (e.g., you only call in a custom script), you must add an explicit call and run it once before deploying.

Deploy Workflow

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 .

Self-Hosted Production

When deploying to a hosting provider like Cloud Run, set DISABLE_TUNNEL=true as an environment variable. This makes run() start only the HTTP server without opening a WebSocket tunnel — the platform reaches your agent directly at its public URL.

await provision({
  agent: {
    name: 'my-agent',
    description: '...',
    endpointUrl: 'https://my-agent.example.com' // Required for production
  },
  workflow: {
    name: 'Lightning Service Pro',
    goal: 'Describe in detail what this workflow does — be thorough, vague goals cause failures',
    trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),
    task: { description: 'Process incoming requests' }
  }
})

// With DISABLE_TUNNEL=true, run() starts only the HTTP server (no tunnel)
await run(agent)

ERC-8004: On-Chain Agent Identity

After provisioning, register your agent on-chain for discoverability via the Identity Registry.

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.

Two important patterns:

Usedotenv programmatically (not import 'dotenv/config') so you can reload .env after provision() writes WALLET_PRIVATE_KEY.
Calldotenv.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.

See openserv-client skill for the full ERC-8004 API reference and troubleshooting.

DO NOT USE

this.process() inside capabilities — Legacy method requiring an OpenAI API key. Use this.generate() instead (platform-delegated, no key needed), or use runless capabilities
doTask override — The SDK handles task execution automatically
this.completeTask() — Task completion is handled by the Runtime API

Updating This Skill

This skill may be outdated. The OpenServ team ships updates regularly—new features, API changes, and bug fixes won't be reflected here until you update. If something isn't working as expected, or you want to make sure you have the latest information, update the skill before proceeding.

# Check if updates are available
npx skills check

# Update all installed skills to latest versions
npx skills update

Or reinstall the OpenServ skills directly:

npx skills add openserv-labs/skills

Related Skills

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

Weekly Installs

101

Repository

openserv-labs/skills

GitHub Stars

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex88

opencode73

kimi-cli64

gemini-cli64

amp64

github-copilot64

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

66,200 周安装

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.

npx tsx src/agent.ts

OpenServ Agent SDK - 使用TypeScript构建和部署自定义AI智能体

🇨🇳中文介绍

OpenServ Agent SDK

为什么要构建智能体？

工作原理（流程）

相关 Skills

您的智能体能做什么

快速开始

安装

最小化智能体

完整智能体模板

文件结构

依赖项

.env

能力

无运行能力（推荐用于大多数用例）

可运行能力

使用智能体方法

智能体方法

generate() — 平台委托的 LLM 调用

任务管理

文件操作

操作上下文

工作流名称与目标

触发器类型

API 密钥：智能体 vs 用户

部署

本地开发

部署到 OpenServ 云

先决条件

部署工作流

自托管生产环境

ERC-8004：链上智能体身份

请勿使用

更新此技能

相关技能

🇺🇸English

OpenServ Agent SDK

Why build an agent?

How it works (the flow)

What your agent can do

Quick Start

Installation

Minimal Agent

Complete Agent Template

File Structure

Dependencies

.env

Capabilities

Runless Capabilities (recommended for most use cases)

Runnable Capabilities

Using Agent Methods

Agent Methods

generate() — Platform-Delegated LLM Calls

Task Management

File Operations

Action Context

Workflow Name & Goal

Trigger Types

API Keys: Agent vs User

Deployment

Local Development

Deploy to OpenServ Cloud

Prerequisites

Deploy Workflow

Self-Hosted Production

ERC-8004: On-Chain Agent Identity

DO NOT USE

Updating This Skill

Related Skills

最新 Skills

`generate()` — 平台委托的 LLM 调用

`generate()` — Platform-Delegated LLM Calls