AI SDK

The Vercel AI SDK lets you connect LLMs to tools — functions the model can call when it needs data or wants to take actions. Katman can automatically convert your procedures into AI tools, extracting JSON Schema from your Zod input schemas.

This means your existing API becomes callable by AI models with zero extra code.

Prerequisites

You need a Katman router and the AI SDK:

npm install ai @ai-sdk/openai

(Or any other AI SDK provider — Anthropic, Google, etc.)

Quick start

import { routerToTools } from "katman/ai"
import { appRouter } from "./router"

const tools = routerToTools(appRouter)

import { generateText } from "ai"
import { openai } from "@ai-sdk/openai"

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools,
  prompt: "List all users with limit 5, then create a user named Bob",
})

How it works

For each procedure, Katman:

1. Extracts a description from route.description or route.summary in your procedure definition. Falls back to "Call {name}".
2. Converts the Zod input schema to JSON Schema, which is the format LLMs use for function calling.
3. Creates an AI SDK tool that executes the procedure when the model calls it.

This means your existing route metadata doubles as AI tool documentation:

const listUsers = k.query({
  input: z.object({ limit: z.number().optional() }),
  route: {
    summary: "List all registered users",
    description: "Returns a list of users, optionally limited by count.",
  },
  resolve: ({ input, ctx }) => ctx.db.users.findMany({ take: input.limit }),
})

The AI model sees "List all registered users" as the tool description and knows it can pass { limit: number } as input.

Single procedure

For more control, convert individual procedures instead of the whole router:

import { procedureToTool } from "katman/ai"

const searchTool = procedureToTool("search", appRouter.search, {
  description: "Search the database for items matching a query",
})

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools: { search: searchTool },
  prompt: "Find all items related to TypeScript",
})

The description option overrides anything from the procedure's route metadata.

Filtering procedures

You probably don't want to expose every procedure to the AI. Use the filter option to control which ones become tools:

const tools = routerToTools(appRouter, {
  // Only expose query procedures, not mutations
  filter: (path, procedure) => procedure.type === "query",
})

Or filter by path:

const tools = routerToTools(appRouter, {
  filter: (path) => !path.startsWith("admin_"),
})

Custom descriptions

Override descriptions for specific tools:

const tools = routerToTools(appRouter, {
  descriptions: {
    users_list: "Get a list of all registered users. Supports a limit parameter.",
    users_create: "Create a new user account with a name and email.",
  },
})

These take priority over route metadata.

Supported input types

The Zod-to-JSON-Schema converter handles common types:

For procedures without an input schema, the tool accepts an empty object.

What's next?

• Getting Started — set up a Katman router to convert into tools
• Procedures — add route metadata that becomes tool descriptions
• Integrations — other available integrations