Solana Agent Kit v2 Beta Integration Guide

This guide demonstrates how to integrate and use Solana Agent Kit v2 Beta in your applications, showcasing a modular, plugin-based architecture for building Solana-powered applications and AI agents.

Overview

Solana Agent Kit v2 introduces a plugin-based architecture that allows developers to:

Extend functionality through modular plugins
Create interactive AI agents that can perform on-chain operations
Build programmatic interfaces for Solana dApps
Seamlessly integrate with AI frameworks like Vercel AI SDK

Prerequisites

Node.js 16+ and npm/yarn/pnpm
Solana wallet with private key
OpenAI API key (for AI agent functionality)
Solana RPC URL

Installation

Start by installing the core package and desired plugins:

npm install solana-agent-kit @solana-agent-kit/plugin-token @solana-agent-kit/plugin-nft @solana-agent-kit/plugin-defi @solana-agent-kit/plugin-misc @solana-agent-kit/plugin-blinks

Additional dependencies:

npm install @solana/web3.js bs58 dotenv @ai-sdk/openai ai

Basic Setup

Environment Setup

Create a .env file with the following variables:

OPENAI_API_KEY=your_openai_api_key
RPC_URL=your_solana_rpc_url
SOLANA_PRIVATE_KEY=your_solana_wallet_private_key

Core Initialization

import { SolanaAgentKit, KeypairWallet } from "solana-agent-kit";
import TokenPlugin from "@solana-agent-kit/plugin-token";
import NFTPlugin from "@solana-agent-kit/plugin-nft";
import DefiPlugin from "@solana-agent-kit/plugin-defi";
import MiscPlugin from "@solana-agent-kit/plugin-misc";
import BlinksPlugin from "@solana-agent-kit/plugin-blinks";
import * as dotenv from "dotenv";
import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";

dotenv.config();

// Initialize wallet
// We are using Keypair for this demo, but it can be connected to Embedded wallet

const keyPair = Keypair.fromSecretKey(
  bs58.decode(process.env.SOLANA_PRIVATE_KEY as string)
);
const wallet = new KeypairWallet(keyPair, process.env.RPC_URL as string);

// Initialize agent with wallet and RPC URL, then add plugins
const agent = new SolanaAgentKit(wallet, process.env.RPC_URL!, {
  OPENAI_API_KEY: process.env.OPENAI_API_KEY,
})
  .use(TokenPlugin)
  .use(NFTPlugin)
  .use(DefiPlugin)
  .use(MiscPlugin)
  .use(BlinksPlugin);

Plugins Overview

Solana Agent Kit v2 uses a modular plugin system to extend functionality:

TokenPlugin: SPL token operations (transfers, balances, minting)
NFTPlugin: NFT operations (minting, transfers, metadata)
DefiPlugin: DeFi operations (swaps, pools, lending)
MiscPlugin: Miscellaneous utilities (airdrop, network info)
BlinksPlugin: Integration with Blinks protocol

Plugins encapsulate related functionality in a modular way, allowing you to include only what your application needs.

Usage Modes

Solana Agent Kit v2 supports two primary usage modes:

1. AI Agent Mode

Create interactive agents that can respond to natural language instructions:

import { createOpenAI } from "@ai-sdk/openai";
import { type Message, streamText } from "ai";
import { randomUUID } from "node:crypto";
import { createVercelAITools } from "solana-agent-kit";

export default async function (agent: SolanaAgentKit) {
  // Create AI tools from agent's actions
  const tools = createVercelAITools(agent, agent.actions);
  
  // Initialize OpenAI client
  const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY as string,
  });
  
  // Initialize message history
  const messages: Message[] = [];
  
  // Interactive chat loop
  while (true) {
    const prompt = await question("\nYou: ");
    if (prompt === "exit") break;
    
    // Add user message to history
    messages.push({
      content: prompt,
      id: randomUUID(),
      role: "user",
    });
    
    // Stream response from the AI model with tools
    const response = streamText({
      model: openai("gpt-4o"),
      tools,
      messages,
      system: `You are a helpful agent that can interact onchain using the Solana Agent Kit...`,
      maxSteps: 5,
    });
    
    // Display streaming response
    process.stdout.write("Agent: ");
    for await (const textPart of response.textStream) {
      process.stdout.write(textPart);
    }
    console.log();
    
    // Add AI response to history
    messages.push({
      content: await response.text,
      id: randomUUID(),
      role: "assistant",
    });
  }
}

2. Programmatic Mode

For direct programmatic usage without AI:

async function programmaticExample(agent: SolanaAgentKit) {
  // Get SOL balance
  const balance = await agent.methods.getBalance();
  console.log("SOL Balance:", balance);
  
  // Airdrop SOL (devnet/testnet only)
  const airdropResult = await agent.methods.requestAirdrop("1");
  console.log("Airdrop result:", airdropResult);
  
  // Transfer SPL token
  const transferResult = await agent.methods.transferToken({
    destination: "recipient_address",
    amount: "1",
    mint: "token_mint_address",
  });
  console.log("Transfer result:", transferResult);
  
  // Swap tokens using Jupiter
  const swapResult = await agent.methods.swapToken({
    inputMint: "input_token_mint",
    outputMint: "output_token_mint",
    amount: "1",
    slippage: 0.5,
  });
  console.log("Swap result:", swapResult);
}

Integrating with Vercel AI SDK

Solana Agent Kit v2 provides built-in integration with Vercel AI SDK:

import { createVercelAITools } from "solana-agent-kit";
import { createAI } from "ai";

// Create AI tools from agent's actions
const tools = createVercelAITools(agent, agent.actions);

// Create AI configuration
const ai = createAI({
  actions: tools,
  initialMessages: [
    {
      role: "system",
      content: "You are a helpful agent that can interact with Solana blockchain."
    }
  ]
});

Custom Plugins

Create your own plugins to extend functionality:

import { SolanaAgentKitPlugin } from "solana-agent-kit";

// Define custom plugin
const CustomPlugin: SolanaAgentKitPlugin = {
  name: "custom",
  
  // Methods that will be available on agent.methods
  methods: {
    customFunction: async (agent, param1: string, param2: number) => {
      // Implementation
      return { status: "success", data: {} };
    }
  },
  
  // Actions for AI integration
  actions: [
    {
      name: "CUSTOM_ACTION",
      description: "Performs a custom function",
      schema: z.object({
        param1: z.string(),
        param2: z.number(),
      }),
      handler: async (agent, input) => {
        const result = await agent.methods.customFunction(
          input.param1,
          input.param2
        );
        return { status: "success", data: result };
      }
    }
  ]
};

// Use the custom plugin
const agent = new SolanaAgentKit(wallet, rpcUrl)
  .use(CustomPlugin);

Error Handling

Implement proper error handling for blockchain operations:

try {
  const result = await agent.methods.transferToken({
    destination: "recipient_address",
    amount: "1",
    mint: "token_mint_address",
  });
  
  console.log("Transfer successful:", result);
} catch (error) {
  if (error.message.includes("insufficient funds")) {
    console.error("Insufficient funds for transfer");
  } else if (error.message.includes("invalid address")) {
    console.error("Invalid recipient address");
  } else {
    console.error("Transfer failed:", error);
  }
}

Utility Functions

For a better developer experience, create utility functions:

// Environment validation
function validateEnvironment(): void {
  const missingVars: string[] = [];
  const requiredVars = ["OPENAI_API_KEY", "RPC_URL", "SOLANA_PRIVATE_KEY"];
  
  requiredVars.forEach((varName) => {
    if (!process.env[varName]) {
      missingVars.push(varName);
    }
  });
  
  if (missingVars.length > 0) {
    console.error("Error: Required environment variables are not set");
    missingVars.forEach((varName) => {
      console.error(`${varName}=your_${varName.toLowerCase()}_here`);
    });
    process.exit(1);
  }
}

// Interactive prompt
const question = (prompt: string): Promise<string> =>
  new Promise((resolve) => rl.question(prompt, resolve));

Mode Selection

Allow users to choose between AI agent and programmatic modes:

async function chooseMode(): Promise<"agent" | "programmatic"> {
  while (true) {
    console.log("\nAvailable modes:");
    console.log("1. agent    - Interactive agent chat mode");
    console.log("2. programmatic    - Programmatic tests written using Jest");
    
    const choice = (await question("\nChoose a mode (enter number or name): "))
      .toLowerCase()
      .trim();
      
    if (choice === "1" || choice === "agent") {
      return "agent";
    } else if (choice === "2" || choice === "programmatic") {
      return "programmatic";
    }
    
    console.log("Invalid choice. Please try again.");
  }
}

Full Example Application

import { SolanaAgentKit, KeypairWallet } from "solana-agent-kit";
import TokenPlugin from "@solana-agent-kit/plugin-token";
import NFTPlugin from "@solana-agent-kit/plugin-nft";
import DefiPlugin from "@solana-agent-kit/plugin-defi";
import MiscPlugin from "@solana-agent-kit/plugin-misc";
import BlinksPlugin from "@solana-agent-kit/plugin-blinks";
import * as dotenv from "dotenv";
import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";
import { chooseMode, rl } from "./utils";
import aiTests from "./agentTests";
import programmaticTests from "./programmaticTests";

dotenv.config();

// Validate environment
function validateEnvironment(): void {
  const missingVars: string[] = [];
  const requiredVars = ["OPENAI_API_KEY", "RPC_URL", "SOLANA_PRIVATE_KEY"];
  requiredVars.forEach((varName) => {
    if (!process.env[varName]) {
      missingVars.push(varName);
    }
  });
  if (missingVars.length > 0) {
    console.error("Error: Required environment variables are not set");
    missingVars.forEach((varName) => {
      console.error(`${varName}=your_${varName.toLowerCase()}_here`);
    });
    process.exit(1);
  }
}

validateEnvironment();

async function main() {
  // Choose mode
  const mode = await chooseMode();
  
  // Create wallet
  const keyPair = Keypair.fromSecretKey(
    bs58.decode(process.env.SOLANA_PRIVATE_KEY as string),
  );
  const wallet = new KeypairWallet(keyPair, process.env.RPC_URL as string);
  
  // Initialize agent with plugins
  const agent = new SolanaAgentKit(wallet, process.env.RPC_URL!, {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  })
    .use(TokenPlugin)
    .use(NFTPlugin)
    .use(DefiPlugin)
    .use(MiscPlugin)
    .use(BlinksPlugin);
  
  // Run selected mode
  if (mode === "agent") {
    await aiTests(agent);
  } else {
    await programmaticTests(agent);
  }
  
  rl.close();
}

main()
  .then(() => console.log("All tests completed successfully!"))
  .catch((error) => {
    console.error("Error during tests:", error);
    process.exit(1);
  });

Best Practices

Plugin Selection: Only include plugins your application needs to reduce bundle size
Error Handling: Implement robust error handling for all blockchain operations
Environment Variables: Use environment variables for sensitive information
Testing: Test on devnet before moving to mainnet
Rate Limiting: Be mindful of RPC rate limits in high-volume applications
User Experience: For AI agents, provide clear instructions and examples

Common Issues

Invalid Private Key: Ensure your private key is in the correct format (base58)
RPC Errors: Watch for rate limiting or connectivity issues with RPC providers
Plugin Conflicts: Some plugins may have overlapping functionality
AI Token Limits: Be aware of token limits when using AI models

Getting Started

Examples

Guides

v2-beta

Features

Classes

Functions

Interfaces

Getting started

Solana Agent Kit v2 Beta Integration Guide

Overview

Prerequisites

Installation

Basic Setup

Environment Setup

Core Initialization

Plugins Overview

Usage Modes

1. AI Agent Mode

2. Programmatic Mode

Integrating with Vercel AI SDK

Custom Plugins

Error Handling

Utility Functions

Mode Selection

Full Example Application

Best Practices

Common Issues

Resources

​Solana Agent Kit v2 Beta Integration Guide

​Overview

​Prerequisites

​Installation

​Basic Setup

​Environment Setup

​Core Initialization

​Plugins Overview

​Usage Modes

​1. AI Agent Mode

​2. Programmatic Mode

​Integrating with Vercel AI SDK

​Custom Plugins

​Error Handling

​Utility Functions

​Mode Selection

​Full Example Application

​Best Practices

​Common Issues

​Resources

Solana Agent Kit v2 Beta Integration Guide

Overview

Prerequisites

Installation

Basic Setup

Environment Setup

Core Initialization

Plugins Overview

Usage Modes

1. AI Agent Mode

2. Programmatic Mode

Integrating with Vercel AI SDK

Custom Plugins

Error Handling

Utility Functions

Mode Selection

Full Example Application

Best Practices

Common Issues

Resources