Skip to main content
The Superserve class is the main entry point for the SDK. It provides methods for running agents, creating sessions, and querying agent metadata.

​
Constructor

import Superserve from '@superserve/sdk'

const client = new Superserve(options)

​
Options

​
apiKey
string
required
Your API key from superserve login. Format: ss_...
​
baseUrl
string
Base URL for the Superserve API. Defaults to https://api.superserve.ai
​
timeout
number
Request timeout in milliseconds. Defaults to 30000 (30 seconds). Only applies to non-streaming requests.

​
Methods

​
run()

Send a message to an agent and wait for the full response. This creates a session, sends the message, collects the response, and ends the session automatically. 
const result = await client.run('my-agent', {
  message: 'Hello!'
})

console.log(result.text)
console.log('Tool calls:', result.toolCalls)
console.log('Duration:', result.duration, 'ms')

​
Parameters

​
agent
string
required
Agent name or ID. Can be a human-readable name like my-agent or an ID like agt_...
​
options
RunOptions
required
Configuration for the run
​
options.message
string
required
The message to send to the agent
​
options.sessionId
string
Reuse an existing session ID instead of creating a new one. Use this to continue a conversation.
​
options.idleTimeout
number
Session idle timeout in seconds. Defaults to 1740 (29 minutes).

​
Returns

​
result
RunResult
The complete response from the agent

​
ToolCall Type

interface ToolCall {
  name: string        // Tool name
  input: unknown      // Input passed to the tool
  duration: number    // Execution time in milliseconds
}

​
stream()

Send a message to an agent and get a streaming response. Returns an AgentStream you can iterate over to receive events in real-time. 
const stream = client.stream('my-agent', {
  message: 'Write a report about TypeScript',
  onText: (text) => process.stdout.write(text),
  onFinish: (result) => console.log('\nDone!', result)
})

// Iterate over text chunks
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

​
Parameters

​
agent
string
required
Agent name or ID
​
options
StreamOptions
required
Configuration for the stream
​
options.message
string
required
The message to send to the agent
​
options.sessionId
string
Reuse an existing session ID
​
options.idleTimeout
number
Session idle timeout in seconds
​
options.onText
(text: string) => void
Callback invoked for each text chunk
​
options.onToolStart
(event: ToolStartEvent) => void
Callback invoked when a tool starts executing
​
options.onToolEnd
(event: ToolEndEvent) => void
Callback invoked when a tool completes
​
options.onFinish
(result: RunResult) => void
Callback invoked when the run completes successfully
​
options.onError
(error: Error) => void
Callback invoked on errors

​
Returns

​
stream
AgentStream
An async iterable stream of events. See Streaming for details.

​
createSession()

Create a multi-turn conversation session with an agent. Sessions maintain context across multiple messages. 
const session = await client.createSession('my-agent', {
  title: 'Debug Session',
  idleTimeout: 1800 // 30 minutes
})

console.log('Session ID:', session.id)

​
Parameters

​
agent
string
required
Agent name or ID
​
options
SessionOptions
Configuration for the session
​
options.title
string
Optional title for the session
​
options.idleTimeout
number
Idle timeout in seconds. Defaults to 1740 (29 minutes). Sessions are automatically ended after this period of inactivity.

​
Returns

​
session
Session
A Session instance. See Sessions for details.

​
agents.list()

List all deployed agents in your account. 
const agents = await client.agents.list()

for (const agent of agents) {
  console.log(agent.name, '—', agent.id)
  console.log('  Status:', agent.depsStatus)
  console.log('  Secrets:', agent.requiredSecrets)
}

​
Returns

​
agents
Agent[]
Array of agent metadata objects

​
agents.get()

Get metadata for a specific agent by name or ID. 
const agent = await client.agents.get('my-agent')
console.log('Agent ID:', agent.id)
console.log('Status:', agent.depsStatus)

​
Parameters

​
nameOrId
string
required
Agent name or ID

​
Returns

​
agent
Agent
Agent metadata (same structure as agents.list() items)

​
Error Handling

The SDK throws typed errors for different failure scenarios: 
import { SuperserveError, APIError } from '@superserve/sdk'

try {
  const result = await client.run('my-agent', {
    message: 'Hello'
  })
} catch (error) {
  if (error instanceof APIError) {
    console.error('API error:', error.status, error.message)
    console.error('Details:', error.details)
  } else if (error instanceof SuperserveError) {
    console.error('SDK error:', error.message)
  } else {
    console.error('Unexpected error:', error)
  }
}

​
APIError

Thrown for HTTP errors from the Superserve API.
​
status
number
HTTP status code (e.g., 404, 500)
​
message
string
Error message
​
details
Record<string, unknown>
Additional error details from the API

​
SuperserveError

Base error class for all SDK errors.

​
Examples

​
One-shot with Error Handling

import Superserve, { APIError } from '@superserve/sdk'

const client = new Superserve({
  apiKey: process.env.SUPERSERVE_API_KEY!
})

try {
  const result = await client.run('my-agent', {
    message: 'Analyze this codebase'
  })

  console.log(result.text)
  
  if (result.toolCalls.length > 0) {
    console.log('\nTools used:')
    for (const tool of result.toolCalls) {
      console.log(`  - ${tool.name} (${tool.duration}ms)`)
    }
  }
} catch (error) {
  if (error instanceof APIError && error.status === 404) {
    console.error('Agent not found. Did you deploy it?')
  } else {
    console.error('Failed to run agent:', error)
  }
}

​
Streaming with Callbacks

const stream = client.stream('my-agent', {
  message: 'Write a poem',
  onText: (text) => {
    process.stdout.write(text)
  },
  onToolStart: (event) => {
    console.log(`\n[Tool: ${event.name}]`)
  },
  onFinish: (result) => {
    console.log(`\n\nCompleted in ${result.duration}ms`)
  },
  onError: (error) => {
    console.error('Stream error:', error)
  }
})

// Wait for completion
await stream.result

​
Custom Base URL

// Point to a local development server
const client = new Superserve({
  apiKey: 'ss_dev',
  baseUrl: 'http://localhost:8000'
})

​
Next Steps

Sessions

Build multi-turn conversations

Streaming

Handle real-time agent responses

Build docs developers (and LLMs) love

Get started for freeTalk to us