Vercel AI SDK - Larkup

Larkup integrates seamlessly with the Vercel AI SDK. You can connect using our official TypeScript SDK to build an AI agent tool, or connect directly to the OpenAI compatible endpoint generated by the Larkup server.

Using the Official SDK (Tool Integration)

You can use the official @larkup/sdk to expose your knowledge base as a tool for the Vercel AI SDK. This enables the LLM to search your documents dynamically for current answers that reflect the available context.

import { tool } from 'ai';
import { z } from 'zod';
import { LarkupClient } from '@larkup/sdk';

// The client automatically picks up LARKUP_API_URL and LARKUP_API_KEY
const ragClient = new LarkupClient();

export const ragTool = tool({
  description: 'Search the knowledge base for relevant context.',
  parameters: z.object({
    query: z.string().describe('The search query'),
  }),
  execute: async ({ query }) => {
    // Retrieve the top 5 most relevant chunks
    const results = await ragClient.query(query, 5);

    // Concatenate the chunks into a single text block for the LLM
    return results.hits.map((hit) => hit.text).join('\n\n');
  },
});

Connecting via OpenAI Compatible Endpoint

Because the Larkup server automatically exposes an OpenAI compatible API, you can use the @ai-sdk/openai package to connect directly, treating the RAG server as an LLM provider.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const larkup = createOpenAI({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'not-needed-for-local', // Replace with actual key if deployed
});

const { text } = await generateText({
  model: larkup('rag-model'), // The model name doesn't matter for local RAG
  prompt: 'What is Larkup?',
});

console.log(text);

Using a local Agent Server as a remote tool

Start the Agent profile in Settings → Larkup Server. The card shows its endpoint, Scalar reference at /reference, and machine-readable OpenAPI document at /openapi.json. Use the Agent client as an AI SDK tool executor. This calls the running agent over HTTP, so the parent agent can be a separate application or model.

import { tool } from 'ai';
import { z } from 'zod';
import { createLarkupAgentToolExecutor } from '@larkup/sdk';

export const specialistAgent = tool({
  description: 'Ask the locally running Larkup specialist agent.',
  inputSchema: z.object({
    message: z.string().describe('Question to send to the specialist'),
  }),
  execute: createLarkupAgentToolExecutor({
    baseUrl: 'http://localhost:8083',
    // apiKey: process.env.LARKUP_AGENT_API_KEY,
    // joinCode: process.env.LARKUP_AGENT_JOIN_CODE,
  }),
});

The same operation is available directly at POST /chat and the explicit POST /agent/chat alias. Both accept {"messages":[...]} and return an AI SDK UI-message stream. For an OpenAI-compatible model provider, use http://localhost:8080/v1 with createOpenAI.