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.
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',
schema: 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',
schema: 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 capabilities at once
agent.addCapabilities([
{
name: 'farewell',
description: 'Say goodbye to a user',
schema: z.object({
name: z.string().describe('The name of the user to bid farewell')
}),
async run({ args }) {
return `Goodbye, ${args.name}! Have a great day!`
}
},
{
name: 'help',
description: 'Show available commands',
schema: z.object({}),
async run() {
return 'Available commands: greet, farewell, help'
}
}
])
// Start the agent server
agent.start()
Environment Variables
Variable
Description
Required
Default
OPENSERV_API_KEY
Your OpenServ API key
Yes
-
OPENAI_API_KEY
OpenAI API key (for process() method)
No*
-
PORT
Server port
No
7378
*Required if using OpenAI integration features
Core Concepts
Capabilities
Capabilities are the building blocks of your agent. Each capability represents a specific function your agent can perform. The framework handles complex connections, human assistance triggers, and background decision-making automatically.
Each capability must include:
name: Unique identifier for the capability
description: What the capability does
schema: Zod schema defining the parameters
run: Function that executes the capability, receiving validated args and action context
import { Agent } from '@openserv-labs/sdk'
import { z } from 'zod'
const agent = new Agent({
systemPrompt: 'You are a helpful assistant.'
})
// Add a single capability
agent.addCapability({
name: 'summarize',
description: 'Summarize a piece of text',
schema: z.object({
text: z.string().describe('Text content to summarize'),
maxLength: z.number().optional().describe('Maximum length of summary')
}),
async run({ args, action }) {
const { text, maxLength = 100 } = args
// Your summarization logic here
const summary = `Summary of text (${text.length} chars): ...`
// Log progress to the task
await action.task.addLog({
severity: 'info',
type: 'text',
body: 'Generated summary successfully'
})
return summary
}
})
// Add multiple capabilities at once
agent.addCapabilities([
{
name: 'analyze',
description: 'Analyze text for sentiment and keywords',
schema: z.object({
text: z.string().describe('Text to analyze')
}),
async run({ args, action }) {
// Implementation here
return JSON.stringify({ result: 'analysis complete' })
}
},
{
name: 'help',
description: 'Show available commands',
schema: z.object({}),
async run({ args, action }) {
return 'Available commands: summarize, analyze, help'
}
}
])
Each capability's run function receives:
params: Object containing:
args: The validated arguments matching the capability's schema
action: The action context containing:
task: The current task context (if running as part of a task)
workspace: The current workspace context
me: Information about the current agent
Other action-specific properties
The run function must return a string or Promise.
Tasks
Tasks are units of work that agents can execute. They can have dependencies, require human assistance, and maintain state:
Agents can participate in chat conversations and maintain context:
const customerSupportAgent = new Agent({
systemPrompt: 'You are a customer support agent.',
capabilities: [
{
name: 'respondToCustomer',
description: 'Generate a response to a customer inquiry',
schema: z.object({
query: z.string(),
context: z.string().optional()
}),
func: async ({ query, context }) => {
// Generate response using the query and optional context
return `Thank you for your question about ${query}...`
}
}
]
})
// Send a chat message
await agent.sendChatMessage({
workspaceId: 123,
agentId: 456,
message: 'How can I assist you today?'
})
Allows agents to interact with external services and APIs that are integrated with OpenServ. This method provides a secure way to make API calls to configured integrations within a workspace. Authentication is handled securely and automatically through the OpenServ platform. This is primarily useful for calling external APIs in a deterministic way.
Parameters:
workspaceId: ID of the workspace where the integration is configured
integrationId: ID of the integration to call (e.g., 'twitter-v2', 'github')
details: Object containing:
endpoint: The endpoint to call on the integration
method: HTTP method (GET, POST, etc.)
data: Optional payload for the request
Returns: The response from the integration endpoint
Example:
// Example: Sending a tweet using Twitter integration
const response = await agent.callIntegration({
workspaceId: 123,
integrationId: 'twitter-v2',
details: {
endpoint: '/2/tweets',
method: 'POST',
data: {
text: 'Hello from my AI agent!'
}
}
})
Advanced Usage
OpenAI Process Runtime
The framework includes built-in OpenAI function calling support through the process() method:
const result = await agent.process({
messages: [
{
role: 'system',
content: 'You are a helpful assistant'
},
{
role: 'user',
content: 'Create a task to analyze the latest data'
}
]
})
Check out our examples directory for more detailed implementation examples.
License
MIT License
Copyright (c) 2024 OpenServ Labs
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
