Custom OpenServ Agents (Client Package)
Create platform-managed agents using PlatformClient. Define a system prompt and capabilities — OpenServ handles the rest.
Custom OpenServ Agents: Define Once, Run Forever
A Custom OpenServ Agent is a platform-managed agent you create through the PlatformClient from @openserv-labs/client. You define a system prompt (capabilities_description), pick a model, and the platform handles hosting, execution, and LLM calls using your OpenServ credits.
Think of it as creating a specialist employee: you give them a job description and they follow it on every single task. No run() function, no self-hosting required.
The Concept
- You Define: A
capabilities_description(the agent's instructions) +model_parameters(model, temperature). - OpenServ Runs It: The platform manages the agent, handles LLM calls via your OpenServ credits, and executes tasks.
- No Runtime Code: You run a setup script once, and the platform does the rest.
Best for:
- Helper agents with a specific purpose (e.g., "You are a legal contract reviewer")
- Text processing with custom context or instructions
- Agents that just need a good prompt and a model, not external tools or APIs
The Master Template
Copy & Paste:
--- 📋 BUILD REQUEST (customize to whatever you need) ---
Build a custom OpenServ agent called "[AGENT_NAME]" that acts as a "[ROLE — e.g., legal contract reviewer, brand copywriter]". It should follow these instructions: "[DETAILED SYSTEM PROMPT]". Use [MODEL — e.g., gpt-4o] with temperature [TEMP — e.g., 0.3]. Then create a workflow with a webhook trigger, assign a task to this agent, trigger it once with "[TEST_PROMPT]", and print the response to verify it works.
--- 🤖 AGENT GUARDRAILS (don't change this) ---
Read the openserv-client skill (SKILL.md + reference.md): https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
Reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
Create a new file in the project folder. The setup script must:
1. Authenticate using `provision()` (automatically creates or reuses wallet).
2. Use `PlatformClient` + `client.agents.create()` with `capabilities_description` and `model_parameters`.
3. Get API key via `client.agents.getApiKey()`, generate + save auth token hash via `client.agents.generateAuthToken()` + `client.agents.saveAuthToken()`.
4. Create workflow via `client.workflows.create()` with a DETAILED `goal` (vague goals cause 400 errors).
5. Create a Webhook trigger (waitForCompletion: true, timeout: 600).
6. Create a task assigned to the agent.
7. CRITICAL: `client.triggers.activate()` — triggers start disabled.
8. Set workflow to running via `workflow.setRunning()`.
9. Fire the webhook once and print the response to verify.Example Recipes
1. The "Legal Contract Reviewer"
Copy & Paste:
--- 📋 BUILD REQUEST (customize to whatever you need) ---
Build a custom OpenServ agent called "Legal Contract Reviewer" that reviews contracts and highlights risks. Instructions: "You are a senior legal analyst. When given a contract, identify key risks, missing clauses, and potential liabilities. Always structure as: 1) Summary, 2) Key Risks, 3) Missing Clauses, 4) Recommendations." Use gpt-4o with temperature 0.3. Create a workflow with a webhook trigger, trigger it once with "Review this NDA: The party agrees to disclose all proprietary information without limitation of liability", and show me the result.
--- 🤖 AGENT GUARDRAILS (don't change this) ---
Read: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
Reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
Create `legal-reviewer.ts` in the project folder:
1. `provision()` (auto wallet).
2. `client.agents.create()` with `capabilities_description` and `model_parameters`.
3. Get API key, generate + save auth token hash.
4. Workflow goal: "Receive legal documents, analyze for risks and missing clauses, return structured reviews."
5. Webhook trigger (waitForCompletion: true, timeout: 600).
6. CRITICAL: `client.triggers.activate()`.
7. Fire webhook once and print result to verify.2. The "Brand Voice Writer"
Copy & Paste:
--- 📋 BUILD REQUEST (customize to whatever you need) ---
Build a custom OpenServ agent called "Brand Voice Writer" that writes marketing copy. Instructions: "You are a copywriter for a premium tech brand. Tone is confident, minimal, slightly playful. Never use exclamation marks. Short paragraphs. Produce 3 variations: formal, casual, and tweet-length." Use gpt-4o with temperature 0.7. Create a workflow, trigger it once with "Write about our new AI-powered search feature", and show me the 3 variations.
--- 🤖 AGENT GUARDRAILS (don't change this) ---
Read: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
Reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
Create `brand-writer.ts` in the project folder:
1. `provision()` (auto wallet).
2. `client.agents.create()` with `capabilities_description` and `model_parameters`.
3. Get API key, generate + save auth token hash.
4. Workflow goal: "Generate brand-consistent marketing copy in three tonal variations for any given topic."
5. Webhook trigger (waitForCompletion: true, timeout: 600).
6. CRITICAL: `client.triggers.activate()`.
7. Fire webhook once and print result to verify.3. The "Custom Agent + Marketplace Agent" Combo
This is the real power — your custom agent does step 1, then a marketplace agent handles step 2.
Copy & Paste:
--- 📋 BUILD REQUEST (customize to whatever you need) ---
Build a two-agent pipeline: First, a custom OpenServ agent called "Trend Analyst" that identifies trending topics and writes a brief for each one. Instructions: "You are a trend analyst. When given a category, identify the top 3 trending topics and write a one-paragraph brief for each." Then, hand off those briefs to the Nano Banana Pro marketplace agent to expand each brief into a full article. Create a workflow that chains both agents together with a webhook trigger, trigger it once with "AI and robotics", and show me the final articles.
--- 🤖 AGENT GUARDRAILS (don't change this) ---
Read these skills:
- openserv-client: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/SKILL.md
- openserv-client reference: https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/reference.md
- openserv-multi-agent-workflows: https://github.com/openserv-labs/skills/blob/main/skills/openserv-multi-agent-workflows/SKILL.md
Create `trend-pipeline.ts` in the project folder:
1. `provision()` (auto wallet).
2. Create custom agent via `client.agents.create()` with capabilities_description and model_parameters.
3. Find "Nano Banana Pro Agent" via `agents.listMarketplace`.
4. Create workflow with `tasks` array: step 1 assigned to custom agent, step 2 assigned to marketplace agent. Edges auto-generated sequentially.
5. Webhook trigger (waitForCompletion: true, timeout: 600).
6. CRITICAL: `client.triggers.activate()`.
7. Fire webhook once and print result to verify.How It Works
| Step | What Happens |
|---|---|
client.agents.create() | Registers a new agent on the platform with your system prompt and model. |
| Auth Token | generateAuthToken() + saveAuthToken() secures the agent endpoint. |
| Workflow + Trigger | The workflow defines the SOP. The trigger is how work enters it. |
client.triggers.activate() | Enables the trigger. Without this, nothing fires. |
| Multi-Agent | Use tasks array in provision() to chain custom + marketplace agents. |
Comparison with Custom External Agents
| Feature | Custom OpenServ Agent (This Guide) | Custom External Agent (Agent SDK) |
|---|---|---|
| Package | @openserv-labs/client only | @openserv-labs/sdk + @openserv-labs/client |
| Hosting | Platform-managed | Self-hosted (your server or local machine) |
| Customization | System prompt + model params | Full code: run(), generate(), external APIs |
| Runtime | Setup script only (runs once) | Persistent runtime: run(agent) stays open |
| Use Case | Helper agents, text processing | API integrations, custom logic, data pipelines |
Debugging
If something isn't working, paste this to OpenClaw:
Check https://github.com/openserv-labs/skills/blob/main/skills/openserv-client/troubleshooting.md for a fix to this error: [PASTE_ERROR_HERE]