How to Integrate @osmosis-agent-toolkit/ai-sdk with Vercel's AI SDK: A Complete Developer Guide

The @osmosis-agent-toolkit/ai-sdk package acts as a thin wrapper that converts Osmosis DeFi tools into Vercel AI SDK-compatible tools using the tool() helper function, allowing seamless integration into streamText, generateObject, and other AI SDK workflows.

The jonator/osmosis-agent-toolkit repository provides a specialized bridge for DeFi applications, enabling developers to integrate Osmosis blockchain functionality into AI-powered applications. When you integrate @osmosis-agent-toolkit/ai-sdk with Vercel's AI SDK, you transform raw blockchain operations into structured, LLM-callable tools that handle account management, swap quoting, and transaction building automatically.

What is @osmosis-agent-toolkit/ai-sdk?

@osmosis-agent-toolkit/ai-sdk is a specialized adapter package that sits between the core Osmosis Agent Toolkit and Vercel's AI SDK. Unlike the core package (@osmosis-agent-toolkit/core), which handles direct blockchain interactions and LRU caching for quote data, the AI SDK wrapper focuses exclusively on protocol compatibility.

The wrapper lives in packages/ai-sdk/src/toolkit.ts and performs a single critical function: converting core toolkit methods into Vercel AI SDK Tool instances using the tool() helper from the ai package.

How the Integration Works

The integration relies on a transformation layer that preserves the core toolkit's functionality while adapting it to Vercel's expected interface. This happens through two main mechanisms: the makeAiSdkTool function and the extended OsmosisAgentToolkit class.

The Core Wrapper Function

The makeAiSdkTool function (lines 29-35 in packages/ai-sdk/src/toolkit.ts) handles the actual conversion:

export function makeAiSdkTool<I, O>(coreTool: CoreTool<I, O>) {
  return tool({
    description: coreTool.description,
    parameters: coreTool.parameters ?? z.never(),
    execute: coreTool.call,
  });
}

This function takes any core toolkit tool and wraps it with Vercel's tool() helper, preserving the original description, Zod parameters, and execution logic. The execute property maps directly to the core tool's call method, ensuring that when the LLM invokes the tool, it triggers the actual Osmosis blockchain logic defined in packages/core/src/toolkit.ts.

The Toolkit Class Structure

The OsmosisAgentToolkit class extends the core toolkit and exposes two critical getters:

export class OsmosisAgentToolkit extends CoreOsmosisAgentToolkit {
  get tools() {
    return {
      accountTool: makeAiSdkTool(super.accountTool),
      swapQuoteInGivenOutTool: makeAiSdkTool(super.swapQuoteInGivenOutTool),
      // …other tools
    };
  }
  
  get allTools(): Tool[] {
    return Object.values(this.tools);
  }
}

The tools getter returns an object containing Vercel-compatible versions of all core tools, while allTools provides them as an array for convenience. This structure allows you to spread the entire toolkit into Vercel's streamText or select individual tools based on your use case.

Step-by-Step Integration Guide

Follow these steps to integrate the Osmosis Agent Toolkit into your Vercel AI SDK application.

1. Install Dependencies

Add both the AI SDK wrapper and Vercel's AI SDK to your project:

npm i @osmosis-agent-toolkit/ai-sdk @vercel/ai

2. Instantiate the Toolkit

Create an instance of the OsmosisAgentToolkit class, providing the necessary credentials (typically a mnemonic for Osmosis blockchain authentication):

import { OsmosisAgentToolkit } from '@osmosis-agent-toolkit/ai-sdk';

const osmosisToolkit = new OsmosisAgentToolkit(process.env.OSMOSIS_MNEMONIC!);

3. Integrate with Vercel AI SDK

Use the toolkit within your AI SDK routes. The most common pattern involves spreading osmosisToolkit.tools into the tools parameter of streamText or generateObject:

import { xai } from '@ai-sdk/xai';
import { streamText } from 'ai';

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

  const result = streamText({
    model: xai('grok-beta'),
    system: `You are a knowledgeable DeFi assistant with access to Osmosis blockchain tools.`,
    messages,
    tools: {
      // Spread all Osmosis tools
      ...osmosisToolkit.tools,
      
      // Or select specific tools:
      // getSwapQuote: osmosisToolkit.tools.swapQuoteInGivenOutTool,
    },
  });

  return result.toDataStreamResponse();
}

This pattern, documented in packages/ai-sdk/README.md, allows the LLM to invoke Osmosis-specific functions like account queries or swap quotes automatically when the conversation context demands it.

4. Deploy Your Application

Deploy your endpoint as a Vercel Edge Function or Next.js API route. The toolkit handles all blockchain communication, caching, and transaction building internally, exposing only the high-level tool interface to your AI application.

Key Files and Architecture

Understanding the file structure helps debug integration issues and extend functionality:

File	Role
packages/ai-sdk/README.md	High-level usage guide and example code for integration.
packages/ai-sdk/src/toolkit.ts	Wrapper class that converts core tools to Vercel AI SDK Tool instances via makeAiSdkTool.
packages/core/src/toolkit.ts	Core Osmosis toolkit implementing concrete tool objects with LRU caching for quote data.
packages/core/src/tools/*	Individual tool implementations (e.g., account.ts, swap.ts) containing Osmosis logic.
packages/core/src/queries/sqs/*	Backend query clients for price quotes and chain data used by the core tools.

Summary

• @osmosis-agent-toolkit/ai-sdk provides a thin wrapper that adapts Osmosis blockchain tools for Vercel's AI SDK compatibility.
• The makeAiSdkTool function in packages/ai-sdk/src/toolkit.ts handles the conversion by wrapping core tools with Vercel's tool() helper.
• You can access Vercel-compatible tools via the tools getter or as an array through allTools on the OsmosisAgentToolkit class.
• Integration requires installing the package, instantiating the toolkit with credentials, and spreading osmosisToolkit.tools into the tools parameter of streamText or similar AI SDK functions.

Frequently Asked Questions

What is the difference between @osmosis-agent-toolkit/core and @osmosis-agent-toolkit/ai-sdk?

@osmosis-agent-toolkit/core contains the actual blockchain logic, including tool implementations for account management and swap quoting, along with LRU caching for performance. @osmosis-agent-toolkit/ai-sdk is a thin wrapper that imports these core tools and converts them into Vercel AI SDK-compatible formats using the tool() helper function.

Can I use individual tools instead of importing the entire toolkit?

Yes. While you can spread all tools using ...osmosisToolkit.tools, you can also reference specific tools individually. For example, you might pass only swapQuoteInGivenOutTool: osmosisToolkit.tools.swapQuoteInGivenOutTool to limit the LLM's access to specific blockchain functions.

What models are compatible with this integration?

The @osmosis-agent-toolkit/ai-sdk wrapper is model-agnostic and works with any model supported by Vercel's AI SDK, including xAI's Grok, OpenAI's GPT models, Anthropic's Claude, and others. The example in the repository uses xai('grok-beta'), but you can substitute any compatible model provider.

How does the toolkit handle authentication with the Osmosis blockchain?

The OsmosisAgentToolkit constructor expects credentials—typically a mnemonic phrase—that it passes to the core toolkit. This allows the underlying tools to sign transactions and query account data on the Osmosis blockchain. You should store these credentials securely in environment variables and pass them when instantiating the toolkit.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}