Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

5.3 KB
Raw Blame

@savoir/sdk

SDK for Knowledge Agent Template — AI agents with up-to-date knowledge base access.

Provides AI SDK compatible tools to query content in a sandboxed environment.

See also: Main README, Architecture, Environment Variables

Installation

npm install @savoir/sdk
# or
bun add @savoir/sdk
# or
pnpm add @savoir/sdk

Configuration

Set the following environment variables:

Variable Required Description
SAVOIR_API_URL Yes Base URL of your API
SAVOIR_API_KEY No API key for authentication (Better Auth API key).

Quick Start

import { createSavoir } from '@savoir/sdk'
import { generateText } from 'ai'

const savoir = createSavoir({
  apiUrl: process.env.SAVOIR_API_URL!,
  apiKey: process.env.SAVOIR_API_KEY, // Optional if API doesn't require auth
})

const { text } = await generateText({
  model: 'google/gemini-3-flash',
  tools: savoir.tools,
  maxSteps: 10,
  prompt: 'How do I configure authentication?',
})

console.log(text)

API Reference

createSavoir(config)

Creates an instance with API client and AI SDK tools.

import { createSavoir } from '@savoir/sdk'

const savoir = createSavoir({
  apiUrl: process.env.SAVOIR_API_URL!,
  apiKey: process.env.SAVOIR_API_KEY,
  sessionId: 'optional-session-id', // For sandbox reuse
  onToolCall: (info) => {
    // Optional callback for tool execution states
    console.log(`Tool ${info.toolName}: ${info.state}`)
  },
})

Config Options

Option Type Required Description
apiUrl string Yes Base URL of your API
apiKey string No API key for authentication
sessionId string No Reuse an existing sandbox session
source string No Usage source identifier (e.g. 'github-bot'). Defaults to 'sdk'.
sourceId string No Tracking ID (e.g. 'issue-123'). Can be overridden per reportUsage() call.
onToolCall function No Callback fired on tool execution (loading/done/error)

Returns

interface Savoir {
  client: SavoirClient           // Low-level HTTP client
  tools: {
    bash: Tool                   // Execute single bash command
    bash_batch: Tool             // Execute multiple commands (more efficient)
  }
  getSessionId(): string | undefined
  setSessionId(sessionId: string): void
  getAgentConfig(): Promise<AgentConfig>
  reportUsage(result: GenerateResult, options?: ReportUsageOptions): Promise<void>
}

Tools

bash

Execute a single bash command in the documentation sandbox.

const { text } = await generateText({
  model,
  tools: { bash: savoir.tools.bash },
  prompt: 'List all markdown files in the docs folder',
})

bash_batch

Execute multiple bash commands in a single request. More efficient than multiple single calls as the sandbox is reused between commands.

const { text } = await generateText({
  model,
  tools: { bash_batch: savoir.tools.bash_batch },
  prompt: 'Find all TypeScript files and show their first 10 lines',
})

SavoirClient

Low-level HTTP client for direct API access. Use createSavoir() for the high-level interface.

import { SavoirClient } from '@savoir/sdk'

const client = new SavoirClient({
  apiUrl: process.env.SAVOIR_API_URL!,
  apiKey: process.env.SAVOIR_API_KEY,
})

// Execute bash command
const result = await client.bash('ls -la')
console.log(result.stdout)

// Execute multiple commands
const batchResult = await client.bashBatch(['pwd', 'ls', 'cat README.md'])

// Get sources configuration
const sources = await client.getSources()

// Trigger sync
await client.sync({ reset: false, push: true })

// Get agent configuration
const config = await client.getAgentConfig()

// Report usage from an AI SDK generate result
await client.reportUsage(result, { startTime: Date.now() })

Error Handling

The SDK exports two error classes:

SavoirError

Thrown when the API returns an error response.

import { SavoirError } from '@savoir/sdk'

try {
  await client.bash('some-command')
} catch (error) {
  if (error instanceof SavoirError) {
    console.log(error.statusCode) // HTTP status code
    console.log(error.message)    // Error message

    if (error.isAuthError()) {
      // Handle 401
    } else if (error.isRateLimitError()) {
      // Handle 429
    } else if (error.isServerError()) {
      // Handle 5xx
    }
  }
}

NetworkError

Thrown when the request fails to reach the API (network issues, DNS errors, etc.).

import { NetworkError } from '@savoir/sdk'

try {
  await client.bash('some-command')
} catch (error) {
  if (error instanceof NetworkError) {
    console.log(error.message)
    console.log(error.cause) // Original error
  }
}

Types

All types are exported for TypeScript users:

import type {
  SavoirConfig,
  ShellResponse,
  ShellBatchResponse,
  SyncOptions,
  SyncResponse,
  SourcesResponse,
  AgentConfig,
  GenerateResult,
  ReportUsageOptions,
  ToolCallInfo,
  ToolCallCallback,
  ToolCallState,
} from '@savoir/sdk'

License

MIT