---
title: Overview
description: Introduction to the Octavus Server SDK for backend integration.
---

# Server SDK Overview

The `@octavus/server-sdk` package provides a Node.js SDK for integrating Octavus agents into your backend application. It handles session management, streaming, and the tool execution continuation loop.

**Current version:** `{{VERSION:@octavus/server-sdk}}`

## Installation

```bash
npm install @octavus/server-sdk
```

## Basic Usage

```typescript
import { OctavusClient } from '@octavus/server-sdk';

const client = new OctavusClient({
  baseUrl: 'https://octavus.ai',
  apiKey: 'your-api-key',
});
```

## Key Features

### Session Management

Create and manage agent sessions:

```typescript
// Create a new session
const sessionId = await client.agentSessions.create('agent-id', {
  COMPANY_NAME: 'Acme Corp',
  PRODUCT_NAME: 'Widget Pro',
});

// Get UI-ready session messages (for session restore)
const session = await client.agentSessions.getMessages(sessionId);
```

### Tool Handlers

Tools run on your server with your data:

```typescript
const session = client.agentSessions.attach(sessionId, {
  tools: {
    'get-user-account': async (args) => {
      // Access your database, APIs, etc.
      return await db.users.findById(args.userId);
    },
  },
});
```

### Streaming

All responses stream in real-time:

```typescript
import { toSSEStream } from '@octavus/server-sdk';

// trigger() returns an async generator of events
const events = session.trigger('user-message', {
  USER_MESSAGE: 'Hello!',
});

// Convert to SSE stream for HTTP responses
return new Response(toSSEStream(events), {
  headers: { 'Content-Type': 'text/event-stream' },
});
```

## API Reference

### OctavusClient

The main entry point for interacting with Octavus.

```typescript
interface OctavusClientConfig {
  baseUrl: string;  // Octavus API URL
  apiKey?: string;  // Your API key
}

class OctavusClient {
  readonly agents: AgentsApi;
  readonly agentSessions: AgentSessionsApi;

  constructor(config: OctavusClientConfig);
}
```

### AgentSessionsApi

Manages agent sessions.

```typescript
class AgentSessionsApi {
  // Create a new session
  async create(agentId: string, input?: Record<string, unknown>): Promise<string>;

  // Get full session state (for debugging/internal use)
  async get(sessionId: string): Promise<SessionState>;

  // Get UI-ready messages (for client display)
  async getMessages(sessionId: string): Promise<UISessionState>;

  // Attach to a session for triggering
  attach(sessionId: string, options?: SessionAttachOptions): AgentSession;
}

// Full session state (internal format)
interface SessionState {
  id: string;
  agentId: string;
  input: Record<string, unknown>;
  variables: Record<string, unknown>;
  resources: Record<string, unknown>;
  messages: ChatMessage[];  // Internal message format
  createdAt: string;
  updatedAt: string;
}

// UI-ready session state
interface UISessionState {
  sessionId: string;
  agentId: string;
  messages: UIMessage[];  // UI-ready messages for frontend
}
```

### AgentSession

Handles triggering and streaming for a specific session.

```typescript
class AgentSession {
  // Trigger an action and stream parsed events
  trigger(
    triggerName: string,
    input?: Record<string, unknown>
  ): AsyncGenerator<StreamEvent>;

  // Get the session ID
  getSessionId(): string;
}

// Helper to convert events to SSE stream
function toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;
```

## Next Steps

- [Sessions](/docs/server-sdk/sessions) — Deep dive into session management
- [Tools](/docs/server-sdk/tools) — Implementing tool handlers
- [Streaming](/docs/server-sdk/streaming) — Understanding stream events
