AI SDK Integration

The Orchata SDK includes tools for the Vercel AI SDK v5+, allowing AI models to query your knowledge base directly.

Installation

Install the SDK along with the required peer dependencies:

npm
pnpm
yarn
bun

npm install @orchata-ai/sdk ai zod

pnpm add @orchata-ai/sdk ai zod

yarn add @orchata-ai/sdk ai zod

bun add @orchata-ai/sdk ai zod

The AI tools require ai v5.0.0+ and zod v3.22.0+ as peer dependencies. If you don’t need AI SDK integration, you can use the core SDK without them.

Basic Usage

Create Orchata tools and use them with the AI SDK:

import { Orchata } from '@orchata-ai/sdk';
import { createOrchataTools } from '@orchata-ai/sdk/ai';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const client = new Orchata({ apiKey: 'oai_xxx' });
const tools = createOrchataTools(client);

const { text } = await generateText({
  model: openai('gpt-4-turbo'),
  tools,
  prompt: 'What does our documentation say about authentication?'
});

console.log(text);

Available Tools

The createOrchataTools function creates these tools for your AI model:

Tool	Description
`queryKnowledge`	Search the knowledge base for relevant information
`findRelevantSpaces`	Discover which spaces are most relevant for a query
`listSpaces`	List all available knowledge spaces
`getDocumentContent`	Get the full content of a specific document
`uploadDocument`	Upload new content (disabled by default)
`createSpace`	Create a new space (disabled by default)

Simple Query Tool

For simple use cases where you want to query a specific space, use the createQueryTool helper:

import { Orchata } from '@orchata-ai/sdk';
import { createQueryTool } from '@orchata-ai/sdk/ai';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const client = new Orchata({ apiKey: 'oai_xxx' });

// Create a tool that queries a specific space
const queryTool = createQueryTool(client, 'space_123');

const { text } = await generateText({
  model: openai('gpt-4-turbo'),
  tools: { query: queryTool },
  prompt: 'What is our refund policy?'
});

Configuration Options

Customize the tools with configuration options:

const tools = createOrchataTools(client, {
  // Restrict which spaces the AI can access
  allowedSpaceIds: ['space_123', 'space_456'],

  // Default number of results (default: 5)
  defaultTopK: 10,

  // Enable document upload (default: false)
  enableUpload: true,

  // Enable space creation (default: false)
  enableSpaceCreation: true,
});

Configuration Options

string[]

Restrict which spaces the AI can access. If not provided, all spaces are accessible.

integer

default:"5"

Default number of results to return from queries.

boolean

default:"false"

Enable the uploadDocument tool. Keep disabled unless you want AI to modify your knowledge base.

boolean

default:"false"

Enable the createSpace tool. Keep disabled unless you want AI to create new spaces.

Streaming

Use streaming for real-time responses:

import { streamText } from 'ai';

const result = streamText({
  model: openai('gpt-4-turbo'),
  tools,
  prompt: 'Summarize our API documentation'
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Complete Example

Here’s a complete example of an AI-powered chatbot that queries your knowledge base:

import { Orchata } from '@orchata-ai/sdk';
import { createOrchataTools } from '@orchata-ai/sdk/ai';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const client = new Orchata({
  apiKey: process.env.ORCHATA_API_KEY!
});

// Create tools with restricted access
const tools = createOrchataTools(client, {
  allowedSpaceIds: ['space_123'], // Only allow access to specific space
  defaultTopK: 5,
  enableUpload: false, // Don't allow AI to upload documents
  enableSpaceCreation: false // Don't allow AI to create spaces
});

export async function POST(request: Request) {
  const { message } = await request.json();

  const result = streamText({
    model: openai('gpt-4-turbo'),
    tools,
    prompt: message,
    system: 'You are a helpful assistant that answers questions using our knowledge base. Always cite your sources.'
  });

  return new Response(result.textStream, {
    headers: { 'Content-Type': 'text/plain' }
  });
}

Tool Descriptions

Each tool includes a description that helps the AI understand when to use it:

queryKnowledge: “Search the knowledge base for information relevant to a query”
findRelevantSpaces: “Find which knowledge spaces are most relevant for a query”
listSpaces: “List all available knowledge spaces”
getDocumentContent: “Get the full content of a specific document”
uploadDocument: “Upload a new document to a knowledge space”
createSpace: “Create a new knowledge space”

The AI model uses these descriptions to decide which tools to call based on the user’s request.

Best Practices

Restrict Access

Use allowedSpaceIds to limit which spaces the AI can access. Don’t give AI access to sensitive data.

Disable Writes

Keep enableUpload and enableSpaceCreation disabled unless you specifically need AI to modify your knowledge base.

Set Limits

Use defaultTopK to control how many results the AI receives. Too many results can be overwhelming.

Provide Context

Use system prompts to guide the AI on how to use the knowledge base and cite sources.

Next Steps

Usage Guide

Learn about Spaces, Documents, and Queries APIs.

Error Handling

Handle errors gracefully with typed error classes.

Quickstart

Review the quickstart guide.

API Reference

Explore the REST API documentation.

Getting Started

MCP Server

AI Tool Setup

CLI

TypeScript SDK

AI SDK Integration

Installation

Basic Usage

Available Tools

Simple Query Tool

Configuration Options

Configuration Options

Streaming

Complete Example

Tool Descriptions

Best Practices

Restrict Access

Disable Writes

Set Limits

Provide Context

Next Steps

Usage Guide

Error Handling

Quickstart

API Reference

​Installation

​Basic Usage

​Available Tools

​Simple Query Tool

​Configuration Options

​Configuration Options

​Streaming

​Complete Example

​Tool Descriptions

​Best Practices

Restrict Access

Disable Writes

Set Limits

Provide Context

​Next Steps

Usage Guide

Error Handling

Quickstart

API Reference

Installation

Basic Usage

Available Tools

Simple Query Tool

Configuration Options

Configuration Options

Streaming

Complete Example

Tool Descriptions

Best Practices

Next Steps