Tool Adapters

Tool adapters let you expose APIs, databases, and services as tools the AI can invoke. This section covers both schema-based and explicit adapters.

Adapter Types

Schema-Based Tools

Provide your API schema (GraphQL or OpenAPI), and Yak generates appropriate requests. You handle execution.

GraphQL – Provide your schema, handle queries
REST/OpenAPI – Provide your spec, handle requests

Explicit Tool Adapters

Define tools programmatically with full control over the interface.

tRPC – Expose tRPC procedures as tools
Custom – Build your own adapter

Quick Comparison

Approach	Best For	Setup
Schema-based	Existing APIs with schemas	Provide schema, implement handler
tRPC Adapter	Existing tRPC routers	Configure allowed procedures
Custom Adapter	Databases, custom logic	Define tools and execution

Combining Adapters

Use multiple adapters together:

import { createNextYakHandler } from "@yak-io/nextjs/server";
import { createTRPCToolAdapter } from "@yak-io/trpc";

const trpcTools = createTRPCToolAdapter({
  router: appRouter,
  allowedProcedures: ["orders.list", "orders.get"],
});

const databaseTools = {
  id: "database",
  getTools: async () => [...],
  executeTool: async (name, args) => {...},
};

export const { GET, POST } = createNextYakHandler({
  tools: [trpcTools, databaseTools],
});

Best Practices

Whitelist Operations

Only expose safe operations:

// ✓ Safe read operations
allowedProcedures: ["orders.list", "orders.get", "products.search"]

// ✗ Never expose destructive operations without safeguards
// "admin.deleteUser", "billing.refund"

Use Descriptive Names

Help the AI understand when to use each tool:

{
  name: "orders.searchByStatus",
  description: "Search orders by their current status (pending, shipped, delivered)",
}

Handle Errors Gracefully

Return meaningful error messages:

executeTool: async (name, args) => {
  try {
    return await executeOperation(name, args);
  } catch (error) {
    if (error instanceof AuthError) {
      return { error: "Not authorized to access this data" };
    }
    throw error;
  }
}

Be careful about which operations you expose. Always add authentication and validate that the current user should be able to perform the action.