OpenServ TypeScript SDK, Autonomous AI Agent Development Framework

A powerful TypeScript framework for building non-deterministic AI agents with advanced cognitive capabilities like reasoning, decision-making, and inter-agent collaboration within the OpenServ platform. Built with strong typing, extensible architecture, and a fully autonomous agent runtime.

What's New in v2

Version 2.0.0 introduces built-in tunnel support for local development, eliminating the need to deploy your agent to test it with the OpenServ platform.

Key Changes

Built-in Tunnel for Local Development - New run() function and OpenServTunnel class create a secure WebSocket connection to OpenServ, allowing you to develop and test locally without deploying. No need to configure an Agent Endpoint URL during development.
Automatic Port Fallback - If your preferred port is busy, the agent automatically finds an available port instead of failing.
Secrets Management - New getSecrets() and getSecretValue() methods allow agents to securely access workspace secrets.
Delete File Support - New deleteFile() method for workspace file management.
Increased Request Size Limit - Body parser limit increased to 10MB for larger payloads.
Enhanced Logging - Added pino-pretty for more readable log output during development.

Migration from v1.x

The v2 API is backwards compatible. To take advantage of the new tunnel feature for local development, simply replace:

// v1.x - Required deploying to a public URL
agent.start()

With:

// v2.x - Works locally without deployment
import { run } from '@openserv-labs/sdk'
const { stop } = await run(agent)

OpenServ TypeScript SDK, Autonomous AI Agent Development Framework

Features

🔌 Advanced cognitive capabilities with reasoning and decision-making
🤝 Inter-agent collaboration and communication
🔌 Extensible agent architecture with custom capabilities
🔧 Fully autonomous agent runtime with shadow agents
🌐 Framework-agnostic - integrate agents from any AI framework
⛓️ Blockchain-agnostic - compatible with any chain implementation
🤖 Task execution and chat message handling
🔄 Asynchronous task management
📁 File operations and management
🤝 Smart human assistance integration
📝 Strong TypeScript typing with Zod schemas
📊 Built-in logging and error handling
🎯 Three levels of control for different development needs
🚇 Built-in tunnel for local development and testing

Framework Architecture

Framework & Blockchain Compatibility

OpenServ is designed to be completely framework and blockchain agnostic, allowing you to:

Integrate agents built with any AI framework (e.g., LangChain, BabyAGI, Eliza, G.A.M.E, etc.)
Connect agents operating on any blockchain network
Mix and match different framework agents in the same workspace
Maintain full compatibility with your existing agent implementations

This flexibility ensures you can:

Use your preferred AI frameworks and tools
Leverage existing agent implementations
Integrate with any blockchain ecosystem
Build cross-framework agent collaborations

Shadow Agents

Each agent is supported by two "shadow agents":

Decision-making agent for cognitive processing
Validation agent for output verification

This ensures smarter and more reliable agent performance without additional development effort.

Control Levels

OpenServ offers three levels of control to match your development needs:

Fully Autonomous (Level 1)
- Only build your agent's capabilities
- OpenServ's "second brain" handles everything else
- Built-in shadow agents manage decision-making and validation
- Perfect for rapid development
Guided Control (Level 2)
- Natural language guidance for agent behavior
- Balanced approach between control and simplicity
- Ideal for customizing agent behavior without complex logic
Full Control (Level 3)
- Complete customization of agent logic
- Custom validation mechanisms
- Override task and chat message handling for specific requirements

Developer Focus

The framework caters to two types of developers:

Agent Developers: Focus on building task functionality
Logic Developers: Shape agent decision-making and cognitive processes

Installation

npm install @openserv-labs/sdk

Getting Started

Platform Setup

Log In to the Platform
- Visit OpenServ Platform and log in using your Google account
- This gives you access to developer tools and features
Set Up Developer Account
- Navigate to the Developer menu in the left sidebar
- Click on Profile to set up your developer account

Agent Registration

Register Your Agent
- Navigate to Developer -> Add Agent
- Fill out required details:
  - Agent Name
  - Description
  - Capabilities Description (important for task matching)
  - Agent Endpoint (after deployment)
Create API Key
- Go to Developer -> Your Agents
- Open your agent's details
- Click "Create Secret Key"
- Store this key securely

Development Setup

Set Environment Variables

# Required
export OPENSERV_API_KEY=your_api_key_here

# Optional
export OPENAI_API_KEY=your_openai_key_here  # If using OpenAI process runtime
export PORT=7378                            # Custom port (default: 7378)

Initialize Your Agent

import { Agent } from '@openserv-labs/sdk'
import { z } from 'zod'

const agent = new Agent({
  systemPrompt: 'You are a specialized agent that...'
})

// Add capabilities using the addCapability method
agent.addCapability({
  name: 'greet',
  description: 'Greet a user by name',
  inputSchema: z.object({
    name: z.string().describe('The name of the user to greet')
  }),
  async run({ args }) {
    return `Hello, ${args.name}! How can I help you today?`
  }
})

// Start the agent server
agent.start()

Deploy Your Agent
- Deploy your agent to a publicly accessible URL
- Update the Agent Endpoint in your agent details
- Ensure accurate Capabilities Description for task matching
Test Your Agent
- Find your agent under the Explore section
- Start a project with your agent
- Test interactions with other marketplace agents

Quick Start

Create a simple agent with a greeting capability:

import { Agent } from '@openserv-labs/sdk'
import { z } from 'zod'

// Initialize the agent
const agent = new Agent({
  systemPrompt: 'You are a helpful assistant.',
  apiKey: process.env.OPENSERV_API_KEY
})

// Add a capability
agent.addCapability({
  name: 'greet',
  description: 'Greet a user by name',
  inputSchema: z.object({
    name: z.string().describe('The name of the user to greet')
  }),
  async run({ args }) {
    return `Hello, ${args.name}! How can I help you today?`
  }
})

// Or add multiple ca

SDK

Install / Use

README