Skip to main content
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 install @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:
ToolDescription
queryKnowledgeSearch the knowledge base for relevant information
findRelevantSpacesDiscover which spaces are most relevant for a query
listSpacesList all available knowledge spaces
getDocumentContentGet the full content of a specific document
uploadDocumentUpload new content (disabled by default)
createSpaceCreate 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

​
allowedSpaceIds
string[]
Restrict which spaces the AI can access. If not provided, all spaces are accessible.
​
defaultTopK
integer
default:"5"
Default number of results to return from queries.
​
enableUpload
boolean
default:"false"
Enable the uploadDocument tool. Keep disabled unless you want AI to modify your knowledge base.
​
enableSpaceCreation
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.