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

> Explore a complete developer guide on integrating the @osmosis-agent-toolkit/ai-sdk with Vercel AI SDK. Seamlessly connect Osmosis DeFi tools into your AI workflows and unlock powerful integrations.

- Repository: [Jon Ator/osmosis-agent-toolkit](https://github.com/jonator/osmosis-agent-toolkit)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/ai-sdk/src/toolkit.ts)) handles the actual conversion:

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/toolkit.ts).

### The Toolkit Class Structure

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

```typescript
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:

```bash
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):

```typescript
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`:

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/ai-sdk/README.md) | High-level usage guide and example code for integration. |
| [`packages/ai-sdk/src/toolkit.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/account.ts), [`swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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.