DEV Community: Necati Özmen

Awesome AI Agent Papers 2026

Necati Özmen — Sun, 22 Feb 2026 17:12:05 +0000

A curated collection of AI agent research papers released in 2026, covering agent engineering, memory, evaluation, workflows, and autonomous systems.

You can view the repository here.

New AI Agent Example

Necati Özmen — Tue, 28 Oct 2025 08:48:25 +0000

Necati Özmen

Oct 28 '25

[Tutorial] WhatsApp Order AI Agent

#webdev #beginners #llm #tutorial

Comments

4 min read

[Tutorial] WhatsApp Order AI Agent

Necati Özmen — Tue, 28 Oct 2025 08:05:35 +0000

Build a WhatsApp chatbot that takes food orders through natural conversation, manages menu items from a database, and processes orders with conversation context.

Full example: github.com/VoltAgent/voltagent/tree/main/examples/with-whatsapp

What We're Building

A WhatsApp AI agent that:

Shows menu items from Supabase
Takes orders through natural conversation
Collects delivery addresses
Tracks order status
Maintains conversation context with working memory

Setup

Clone the example:

npm create voltagent-app@latest -- --example with-whatsapp
cd with-whatsapp

Create .env:

OPENAI_API_KEY=your_openai_api_key
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
WHATSAPP_WEBHOOK_TOKEN=your_webhook_verification_token
WHATSAPP_ACCESS_TOKEN=your_whatsapp_access_token
WHATSAPP_PHONE_NUMBER_ID=your_whatsapp_phone_number_id

Database Schema

Run this SQL in your Supabase dashboard:

-- Menu items table
CREATE TABLE public.menu_items (
  id SERIAL PRIMARY KEY,
  category VARCHAR(50) NOT NULL,
  name VARCHAR(100) NOT NULL,
  description TEXT,
  price NUMERIC(10, 2) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Orders table
CREATE TABLE public.orders (
  id SERIAL PRIMARY KEY,
  customer_phone VARCHAR(20) NOT NULL,
  customer_address TEXT NOT NULL,
  total_amount NUMERIC(10, 2) NOT NULL,
  status VARCHAR(20) NOT NULL DEFAULT 'preparing',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Order items table
CREATE TABLE public.order_items (
  id SERIAL PRIMARY KEY,
  order_id INTEGER REFERENCES orders(id) ON DELETE CASCADE,
  menu_item_id INTEGER REFERENCES menu_items(id) ON DELETE CASCADE,
  quantity INTEGER NOT NULL DEFAULT 1,
  price NUMERIC(10, 2) NOT NULL
);

-- Sample data
INSERT INTO menu_items (category, name, description, price) VALUES
  ('Pizza', 'Margherita', 'Fresh tomatoes, mozzarella, basil', 12.99),
  ('Pizza', 'Pepperoni', 'Pepperoni, mozzarella, tomato sauce', 14.99),
  ('Burger', 'Classic Burger', 'Beef patty, lettuce, tomato, onion', 10.99),
  ('Drinks', 'Coke', 'Coca-Cola 330ml', 2.99);

Core Components

Working Memory Schema

Define conversation state with Zod:

const workingMemorySchema = z.object({
  orders: z.array(z.object({
    menuItemId: z.number(),
    itemName: z.string(),
    quantity: z.number(),
    price: z.number(),
  })).default([]),
  deliveryAddress: z.string().default(""),
  orderStatus: z.enum(["selecting", "address_needed", "completed"]).default("selecting"),
});

Memory Configuration

const memory = new Memory({
  storage: new LibSQLMemoryAdapter({
    url: "file:./.voltagent/memory.db",
  }),
  workingMemory: {
    enabled: true,
    scope: "conversation",
    schema: workingMemorySchema,
  },
});

Working memory maintains cart state across messages without asking customers to repeat information.

Agent Setup

const agent = new Agent({
  name: "whatsapp-order-agent",
  instructions: `You are a WhatsApp ordering agent.

Order Flow:
1. Show menu if orders array is empty
2. When customer orders, keep orderStatus as "selecting"
3. When done ordering, change to "address_needed"
4. After receiving address, change to "completed" and execute createOrder tool

Always be friendly and helpful.`,
  model: openai("gpt-4o-mini"),
  tools: [listMenuItemsTool, createOrderTool, checkOrderStatusTool],
  memory,
});

Tools

List Menu Items:

export const listMenuItemsTool = createTool({
  name: "listMenuItems",
  description: "Lists all menu items from the database",
  parameters: z.object({
    limit: z.number().optional().default(100),
  }),
  execute: async ({ limit }) => {
    const { data, error } = await supabase
      .from("menu_items")
      .select("*")
      .limit(limit);

    return {
      success: !error,
      data: data || [],
    };
  },
});

Create Order:

export const createOrderTool = createTool({
  name: "createOrder",
  description: "Creates a new order",
  parameters: z.object({
    items: z.array(z.object({
      menuItemId: z.number(),
      quantity: z.number(),
      price: z.number(),
    })),
    deliveryAddress: z.string(),
  }),
  execute: async ({ items, deliveryAddress }, context) => {
    const totalAmount = items.reduce((sum, item) =>
      sum + item.price * item.quantity, 0);

    const { data: orderData } = await supabase
      .from("orders")
      .insert({
        customer_phone: context?.userId,
        customer_address: deliveryAddress,
        total_amount: totalAmount,
        status: "preparing",
      })
      .select()
      .single();

    const orderItems = items.map(item => ({
      order_id: orderData.id,
      menu_item_id: item.menuItemId,
      quantity: item.quantity,
      price: item.price,
    }));

    await supabase.from("order_items").insert(orderItems);

    return {
      success: true,
      orderId: orderData.id,
      totalAmount,
    };
  },
});

WhatsApp Webhook

new VoltAgent({
  agents: { agent },
  server: honoServer({
    configureApp: (app) => {
      // Verification (GET)
      app.get("/webhook/whatsapp", async (c) => {
        const mode = c.req.query("hub.mode");
        const token = c.req.query("hub.verify_token");
        const challenge = c.req.query("hub.challenge");

        if (mode === "subscribe" && token === process.env.WHATSAPP_WEBHOOK_TOKEN) {
          return c.text(challenge || "", 200);
        }
        return c.text("Forbidden", 403);
      });

      // Message handler (POST)
      app.post("/webhook/whatsapp", async (c) => {
        const body = await c.req.json();
        const message = body.entry?.[0]?.changes?.[0]?.value?.messages?.[0];

        if (message?.type === "text") {
          const response = await agent.generateText(message.text.body, {
            userId: message.from,
            conversationId: `whatsapp_${message.from}`,
          });

          await sendWhatsAppMessage(message.from, response.text);
        }

        return c.json({ status: "processed" }, 200);
      });
    },
  }),
  logger,
});

Run the Agent

npm run dev

Visit VoltOps Console to test and debug.

Example Conversation

Customer: Hi
Agent: Welcome! Would you like to see our menu?

Customer: Yes
Agent: Here's our menu:
**Pizza**
" Margherita - $12.99
" Pepperoni - $14.99
**Burgers**
" Classic Burger - $10.99

What would you like to order?

Customer: 2 pepperoni pizzas and a coke
Agent: Added to cart:
- 2x Pepperoni Pizza ($29.98)
- 1x Coke ($2.99)
Total: $32.97

Anything else?

Customer: No thanks
Agent: Please provide your delivery address.

Customer: 123 Main St
Agent: Order #1057 confirmed!
=� 123 Main St
=� $32.97
� 30-45 minutes

Key Features

TypeScript Tools: Zod-typed tools with automatic inference
Working Memory: Maintains cart state across messages
WhatsApp Integration: Webhook handlers for Meta API
Observability: VoltOps platform traces every interaction
Database Integration: Supabase for menu and orders

[Boost]

Necati Özmen — Thu, 16 Oct 2025 11:52:32 +0000

Building a ChatGPT App with VoltAgent and the Apps SDK

Ekim Cem Ülger ・ Oct 15 '25

#agents #mcp #chatgpt #voltagent

Your Top 10 Claude Code Subagents for Instant Productivity

Necati Özmen — Tue, 23 Sep 2025 09:01:49 +0000

We're curating Awesome Claude Code Subagents, your launchpad to production-ready specialists that plug straight into your workflow.

Maintained by VoltAgent Framework community

🔟 Top 10 Most-Used Specialists by Category

Pulled from community analytics, these are the subagents teams call on the most—one standout from each category.

1. Core Development

fullstack-developer – ships end-to-end features with type-safe APIs, shared models, and Playwright-powered journeys that prove the experience before launch.

2. Language Specialists

rust-engineer – enforces zero-unsafe patterns, clippy::pedantic standards, and async ownership mastery for mission-critical Rust builds.

3. Infrastructure

platform-engineer – crafts self-service golden paths, GitOps flows, and Backstage-powered portals that keep developers shipping without ticket ping-pong.

4. Quality & Security

penetration-tester – runs scope-safe recon, validates exploits, and hands back hard evidence plus remediation notes before attackers ever try.

5. Data & AI

llm-architect – designs RAG stacks, tunes LoRA pipelines, and keeps vLLM serving below 200 ms while safety filters stay locked.

6. Developer Experience

documentation-engineer – treats docs-as-code, auto-syncs OpenAPI specs, and enforces WCAG-friendly, searchable knowledge bases devs actually use.

7. Specialized Domains

iot-engineer – hardens device fleets, orchestrates MQTT flows, and optimizes edge-to-cloud latency for massive IoT rollouts.

8. Business & Product

product-manager – balances user insight, analytics, and outcome-driven roadmaps to keep feature bets aligned with north-star metrics.

9. Meta & Orchestration

multi-agent-coordinator – prevents deadlocks, optimizes task graphs, and keeps 100+ agents moving in concert without dropping messages.

10. Research & Analysis

trend-analyst – surfaces weak signals, projects impact timelines, and packages foresight so strategy teams can act before markets pivot.

📦 Grab 110+ Claude Code Subagents

👉 Explore the full collection on GitHub

Every profile arrives with:

✅ Production-grade defaults
✅ MCP tool wiring
✅ Proven best practices
✅ Living updates
✅ Active community support

🎯 Quick Start

# 1. Launch the Claude Code agent manager
/agents

# 2. Spin up a new specialist or call an existing pro
# 3. Let Claude delegate and deliver

🤝 Join the Community

We love contributors! Jump in to:

Submit fresh subagents
Level-up current experts
Share experiments and wins
Report issues or gaps

Check the Contributing Guidelines and hop into our Discord Community.

⚡️10 Claude Code Subagents Every Developer Needs in 2025

Necati Özmen — Fri, 08 Aug 2025 09:04:31 +0000

As developers, we're always searching for ways to boost our productivity and code quality. After working extensively with Claude Code's subagent ecosystem, I've identified the 10 most impactful subagents that have revolutionized my development workflow. These aren't just tools - they're AI-powered specialists that handle complex tasks with precision.

Maintaining by VoltAgent Framework community

🌟 The Complete Collection

These 10 subagents are just the beginning. The Awesome Claude Code Subagents repository contains over 110 specialized agents across 10 categories:

Core Development (9 agents)
Language Specialists (22 agents)
Infrastructure (12 agents)
Quality & Security (12 agents)
Data & AI (12 agents)
Developer Experience (9 agents)
Specialized Domains (10 agents)
Business & Product (10 agents)
Meta & Orchestration (8 agents)
Research & Analysis (6 agents)

🚀 Why These 10 Subagents?

I selected these based on:

Real-world impact on development speed
Frequency of use in daily workflows
Problem-solving capability for common challenges
Time saved on repetitive tasks
Code quality improvements they deliver

Let's dive into each one and see why they're essential for modern development.

1. 🔍 Code Reviewer

The Quality Guardian

This subagent has saved me countless hours and prevented numerous production bugs. It performs comprehensive code reviews with the thoroughness of a senior engineer.

What it does:

Identifies potential bugs before they reach production
Suggests performance optimizations
Ensures coding standards compliance
Spots security vulnerabilities
Recommends architectural improvements

Real impact: On a recent project, it caught a subtle race condition that would have caused intermittent failures in production. The fix took 5 minutes; debugging it in production would have taken days.

// Example: It caught this potential issue
// Before
const processPayments = async (payments) => {
  payments.forEach(async (payment) => {
    await processPayment(payment); // Won't wait for all!
  });
};

// After (suggested fix)
const processPayments = async (payments) => {
  await Promise.all(payments.map(payment => processPayment(payment)));
};

2. 🐛 Debugger

The Bug Elimination Specialist

When you're stuck on a perplexing bug, this subagent is your best friend. It systematically analyzes issues and provides targeted solutions.

Superpowers:

Root cause analysis of complex bugs
Step-by-step debugging strategies
Memory leak detection
Performance bottleneck identification
Suggests debugging tools and techniques

Why it's essential: Instead of spending hours with console.log statements, it guides you directly to the problem source with surgical precision.

3. ⚛️ React Specialist

The Modern React Expert

For React developers, this subagent is indispensable. It's always up-to-date with React 18+ patterns and best practices.

Key capabilities:

Server Components optimization
Advanced hooks patterns
Performance optimization strategies
State management solutions
Testing strategies with React Testing Library

Game-changer moment: It helped me refactor a complex component from 300 lines to 80 lines using custom hooks and composition patterns, improving both readability and performance.

// Transforms complex components into elegant solutions
const useDataFetching = (endpoint) => {
  // Custom hook it suggested that eliminated 50+ lines of repetitive code
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch(endpoint);
        setData(await response.json());
      } catch (err) {
        setError(err);
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, [endpoint]);

  return { data, loading, error };
};

4. 🔄 Refactoring Specialist

The Code Transformation Expert

Legacy code doesn't stand a chance against this subagent. It transforms messy, hard-to-maintain code into clean, scalable solutions.

Transformation capabilities:

Identifies code smells automatically
Suggests design pattern implementations
Breaks down monolithic functions
Improves naming conventions
Reduces cyclomatic complexity

Success story: Refactored a 2000-line legacy controller into a clean, testable service architecture with 60% less code and 100% test coverage.

5. 🚢 DevOps Engineer

The Deployment Automation Master

This subagent turns deployment nightmares into smooth, automated processes. It's your personal DevOps expert on demand.

DevOps excellence:

CI/CD pipeline configuration
Docker optimization strategies
Kubernetes deployment manifests
Infrastructure as Code with Terraform
Monitoring and alerting setup

Time saved: What used to take me days to set up (CI/CD pipelines) now takes hours with this subagent's guidance.

# Example: Generated GitHub Actions workflow
name: Production Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build and Test
        run: |
          npm ci
          npm test
          npm run build
      - name: Deploy to Production
        # Perfectly configured deployment steps

6. 🧪 Test Automator

The Testing Framework Architect

Writing tests is no longer a chore with this subagent. It creates comprehensive test suites that actually catch bugs.

Testing mastery:

Unit test generation
Integration test strategies
E2E test scenarios
Test data factories
Coverage optimization

Quality boost: Helped achieve 95% test coverage on a complex application, catching 15 bugs before they reached staging.

7. 🗄️ Database Optimizer

The Query Performance Wizard

Database performance issues disappear when this subagent gets involved. It's like having a DBA on your team.

Optimization skills:

Query performance tuning
Index strategy recommendations
Schema optimization
Migration planning
Caching strategies

Performance win: Reduced a critical query from 30 seconds to 0.3 seconds by suggesting the right indexes and query restructuring.

-- Before: 30-second query
SELECT * FROM orders o
LEFT JOIN users u ON o.user_id = u.id
WHERE o.created_at > '2024-01-01'
AND u.country = 'US';

-- After: 0.3-second optimized query with suggested indexes
-- Added indexes: (created_at, user_id), (country, id)
SELECT o.id, o.total, u.name, u.email
FROM orders o
INNER JOIN users u ON o.user_id = u.id
WHERE o.created_at > '2024-01-01'
AND u.country = 'US'
ORDER BY o.created_at DESC
LIMIT 1000;

8. 🏗️ API Designer

The RESTful & GraphQL Architect

Building APIs that developers love to use is an art, and this subagent is the master artist.

API expertise:

RESTful best practices
GraphQL schema design
Authentication strategies
Rate limiting implementation
API versioning strategies

Developer experience win: Designed an API that reduced frontend integration time by 50% through intuitive endpoints and comprehensive documentation.

9. 🔐 Security Engineer

The Vulnerability Shield

Security can't be an afterthought, and this subagent ensures it never is. It thinks like both a developer and a hacker.

Security capabilities:

Vulnerability scanning
Security best practices implementation
Authentication/authorization setup
Encryption strategies
OWASP compliance

Crisis averted: Identified and fixed 3 critical security vulnerabilities before our security audit, saving thousands in potential remediation costs.

10. 📊 Performance Engineer

The Speed Optimization Expert

When milliseconds matter, this subagent delivers. It transforms sluggish applications into lightning-fast experiences.

Performance magic:

Frontend optimization techniques
Backend performance tuning
Caching strategy implementation
Load testing scenarios
Memory optimization

User impact: Reduced page load time from 8 seconds to 1.2 seconds, resulting in 40% better user engagement metrics.

🎯 How to Start Using These Subagents

Getting started is incredibly simple:

Access the subagent manager in Claude Code:

/agents

Browse or search for the subagent you need
Let Claude automatically delegate tasks or invoke manually:

"Have the code-reviewer subagent analyze my latest changes"

Watch your productivity soar 🚀

💡 Pro Tips for Maximum Impact

Combine subagents for complex tasks: Use the debugger with the performance engineer for optimization debugging.
Create project-specific configurations: Customize subagents with your team's coding standards.
Share with your team: Export your configured subagents for consistent team practices.
Regular updates: The community constantly improves these subagents - pull updates regularly.

🤝 Join the Revolution

The subagent ecosystem is community-driven and constantly evolving. Here's how you can get involved:

Star the repository: Show your support for the project
Contribute new subagents: Share your specialized configurations
Report issues: Help improve existing subagents
Join the discussion: Connect with other developers on Discord

🎬 Conclusion

These 10 subagents have fundamentally changed how I approach development. What used to take hours now takes minutes. What used to be error-prone is now bulletproof. What used to be tedious is now automated.

The future of development isn't about AI replacing developers - it's about AI empowering developers to focus on what truly matters: solving problems and building amazing products.

Start with these 10 essential subagents and explore the full collection at Awesome Claude Code Subagents.

100+ Claude Code Subagent Collection

Necati Özmen — Tue, 05 Aug 2025 12:44:23 +0000

Looking to supercharge your development workflow with specialized AI agents? We've been working on Awesome Claude Code Subagents - a comprehensive collection of production-ready subagents for Claude Code.

Maintaining by VoltAgent Framework community

📦 Get All 110+ Claude Code Subagents.

👉 Explore the full collection on GitHub

Each subagent includes:

✅ Production-ready configurations
✅ MCP Tool integration
✅ Best practices compliance
✅ Regular updates
✅ Community support

🎯 Quick Start

# 1. Access subagent manager in Claude Code
/agents

# 2. Create new agent or use existing ones
# 3. Let Claude automatically delegate tasks

🤝 Join the Community

We're always looking for contributors! Whether you want to:

Submit new subagents
Improve existing ones
Share your use cases
Report issues

Check out our Contributing Guidelines and join our Discord Community.

What are Subagents?

Subagents are specialized AI assistants that enhance Claude Code's capabilities by providing task-specific expertise. Each operates with its own context window and domain-specific intelligence, making them perfect for focused development tasks.

🌟 All Categories with 110+ Specialized Subagents

1. Core Development (9 subagents)

Essential development subagents for everyday coding tasks:

2. Language Specialists (22 subagents)

Language-specific experts with deep framework knowledge:

3. Infrastructure (12 subagents)

DevOps, cloud, and deployment specialists:

4. Quality & Security (12 subagents)

Testing, security, and code quality experts:

5. Data & AI (12 subagents)

Data engineering, ML, and AI specialists:

6. Developer Experience (9 subagents)

Tooling and developer productivity experts:

7. Specialized Domains (10 subagents)

Domain-specific technology experts:

8. Business & Product (10 subagents)

Product management and business analysis:

9. Meta & Orchestration (8 subagents)

Agent coordination and meta-programming:

10. Research & Analysis (6 subagents)

Research, search, and analysis specialists:

AI Agent tutorial from the basics to building multi-agent teams

Necati Özmen — Mon, 21 Jul 2025 09:33:43 +0000

We’ve been building OSS dev tools for over 7 years. From that experience, we’ve seen that tutorials which combine key concepts with hands-on code examples are the most effective way to understand the why and how of agent development.

Tutorial: https://voltagent.dev/tutorial/introduction/

GitHub Repo: https://github.com/voltagent/voltagent

Tutorial Source Code: https://github.com/VoltAgent/voltagent/tree/main/website/src/pages/tutorial

What we implemented:

1 – The Chatbot Problem

Why most chatbots are limited and what makes AI agents fundamentally different.

2 – Tools: Give Your Agent Superpowers

Let your agent do real work: call APIs, send emails, query databases, and more.

3 – Memory: Remember Every Conversation

Persist conversations so your agent builds context over time.

4 – MCP: Connect to Everything

Using MCP to integrate GitHub, Slack, databases, etc.

5 – Subagents: Build Agent Teams

Create specialized agents that collaborate to handle complex tasks.

It’s all built using VoltAgent, our TypeScript-first open-source AI agent framework.(I'm maintainer) It handles routing, memory, observability, and tool execution, so you can focus on logic and behavior.

Although the tutorial uses VoltAgent, the core ideas tools, memory, coordination are framework-agnostic. So even if you’re using another framework or building from scratch, the steps should still be useful.

We’d love your feedback, especially from folks building agent systems. If you notice anything unclear or incomplete, feel free to open an issue or PR. It’s all part of the open-source repo.

🚀 VoltAgent Launch Week #1 — What’s New?

Necati Özmen — Wed, 18 Jun 2025 11:44:08 +0000

Hey everyone! 👋

We just kicked off Launch Week #1 for VoltAgent — our open-source TypeScript framework for building and observing LLM agents.

This is our first-ever launch week, and everything we’re shipping is shaped by community feedback over the past few months. Each day this week, we’re introducing new features designed to help you build, scale, and monitor AI agents more effectively.

💡 What’s VoltAgent?

VoltAgent is a flexible framework for orchestrating AI agents, with built-in support for:

Multi-agent workflows
Tool integrations
Custom routing & hooks

Tracing & debugging via VoltOps

🔎 What’s VoltOps?

VoltOps is our framework-agnostic observability layer for LLM apps. Even if you’re not using VoltAgent, you can still monitor your agents and see detailed traces using VoltOps. It now works with:

Vanilla JS / Python agents
Vercel AI SDK
LangChain, LangGraph (coming soon)

🔥 Launch Week Highlights (So far)

🟢 Day 1 – Framework-Agnostic Observability

VoltAgent Developer Console is now VoltOps — supports observability across any framework.

🟢 Day 2 – Streaming with fullStream

Capture every reasoning step, tool call, and completion signal — not just raw text.

🟢 Day 3 – Vercel AI UI Support

VoltAgent now includes plug-and-play UI components for building agent UIs with Vercel AI SDK.

(More days coming soon… 👀)

⸻

🙌 Join the Community

We’re open source and community-driven. You can:

⭐ Star the repo: https://github.com/VoltAgent/voltagent
💬 Join our Discord: https://s.voltagent.dev/discord

⸻

Thanks to everyone who’s given us feedback so far, it’s been amazing to see what people are building with VoltAgent.

Let’s build better agents, together. 🦾

— VoltAgent Team ⚡

✨ What an LLM Agent Framework Looks Like in 2025

Necati Özmen — Wed, 04 Jun 2025 10:03:08 +0000

"ChatGPT is amazing, but how do I integrate this into my own app?" - How many developers have heard this question...

LLMs changed our lives, no doubt about it. Since ChatGPT came out, everyone sees incredible possibilities. But let me tell you the truth as a developer: Using this power in our own applications is way harder than we thought.

Most of us go through the same cycle. First there's excitement: "I have an amazing AI idea!" Then quick start: We do API integration, simple examples work, everything looks good. But when real users come... that's when everything gets complicated. Code becomes unmanageable, every new feature breaks old code, debugging becomes a nightmare.

Did you go through this cycle? You're not alone.

The Real Problem: From API to Application

When you look at AI development with the traditional approach, it looks like this:

// Manual API call every time
const response = await openai.chat.completions.create({
  messages: [{ role: "user", content: userInput }],
});
// Custom code for every feature...

No problem at first. But then user requests start coming: "Can it use this tool?", "Can it remember past conversations?", "Can it behave differently in different situations?" You write code from scratch for every request. You solve the same problems over and over.

This is where an LLM agent framework comes in right here. They hide complexity behind abstraction layers:

// Define agent once, complexity handled by framework
const agent = new Agent({
  name: "customer-support",
  instructions: "Do customer support",
  tools: [orderTool, refundTool],
  memory: conversationMemory,
});

See the difference? The framework handles those thousands of lines of boilerplate code, error handling, memory management, tool orchestration and gives you a chance to just focus on business logic.

What's Out There?

At this point, developers have three main options.

Those who choose the DIY approach want full control but their lives become hell. They write everything from scratch, solve the same problems over and over. Might be reasonable for companies with big engineering teams but overkill for most projects.

Those who choose no-code/low-code platforms start fast but then hit walls. Visual editors are nice, don't require technical knowledge at first but when you want a custom feature, you get "you can't do that" as an answer. Vendor lock-in risk is also a pain.

LLM agent framework find a place between the two. They give you ready-made building blocks but don't compromise on flexibility. Production-ready, best practices built-in but you can customize however you want.

When deciding which option to go with, think about these: How's the programming language support? Is switching between LLM providers easy? What's the performance and scalability situation? How's the documentation quality? Is there community support? Are error handling, monitoring, security features good?

Tip

Start with a framework if you're building your first AI application. You can always migrate to custom solutions later when you understand your specific needs better.

Voltagent Example

:::note
The following examples show Voltagent's approach, but similar patterns exist in other frameworks like LangChain, AutoGen, and CrewAI. The concepts are transferable.
:::

At this point I want to give a concrete example. While developing Voltagent, we experienced exactly these problems and tried to solve them.

Voltagent's design philosophy is: "Powerful defaults, infinite customization" - meaning provide ready solutions for most use cases, but unlimited flexibility for special needs.

One of our most important decisions was being TypeScript-first. Why? Because type safety really saves lives. In complex agent systems, knowing which function takes what parameters is critical. We also made a modular package system - you only use what you need:

// Only use what you need
import { Agent } from "@voltagent/core";
import { VoiceAgent } from "@voltagent/voice"; // If needed

Provider-agnostic design was also very important. We didn't want vendor lock-in:

// Easy provider switching
const openaiAgent = new Agent({
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
});

const anthropicAgent = new Agent({
  llm: new AnthropicProvider(),
  model: anthropic("claude-3-5-sonnet"),
});

From Simple Agents to Complex Systems

Creating an agent in its simplest form is really easy:

const agent = new Agent({
  name: "My Assistant",
  instructions: "Helpful and friendly assistant",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
});

// Usage is also simple
const response = await agent.generateText("Hello!");
console.log(response.text);

But the beautiful thing is, you can do much more complex stuff with the same API. For example structured data generation:

// Define schema for data extraction
const personSchema = z.object({
  name: z.string().describe("Full name"),
  age: z.number(),
  occupation: z.string(),
  skills: z.array(z.string()),
});

// Ask agent for structured data
const result = await agent.generateObject(
  "Create a profile for a software developer named Alex.",
  personSchema
);

console.log(result.object); // Type-safe JSON object

This feature is especially useful for data extraction and API responses. You're not saying "give it in JSON format" and then trying to parse it anymore.

Tool Integration: Real World Connection

We added MCP (Model Context Protocol) support in the tool integration part. This really became a game-changing feature:

// Define local tool
const weatherTool = createTool({
  name: "get_weather",
  description: "Get the current weather for a specific location",
  parameters: z.object({
    location: z.string().describe("City and state"),
  }),
  execute: async ({ location }) => {
    // Real API call would be here
    return { temperature: 72, conditions: "sunny" };
  },
});

// Connect to external MCP server
const mcpTools = await connectMCPServer("stdio://weather-server");

const agent = new Agent({
  name: "Weather Assistant",
  instructions: "Can check weather using available tools",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  tools: [weatherTool, ...mcpTools], // Combine both
});

The agent decides which tool to use when by itself. You just say "How's the weather in London?", it calls its own tool and brings you the result.

Memory: Context Management

We also carefully designed the memory system. It's critical for agents to remember past conversations:

import { LibSQLStorage } from "@voltagent/core";

const memoryStorage = new LibSQLStorage({
  url: "file:local.db",
});

const agent = new Agent({
  name: "Assistant with Memory",
  instructions: "Remember our conversation history",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  memory: memoryStorage, // Automatic context management
});

// First conversation
await agent.generateText("My name is John and I love pizza");

// Next conversation - will remember the previous one
await agent.generateText("What's my favorite food?");
// "Based on our previous conversation, you love pizza!"

The framework automatically fetches relevant context and saves new interactions.

Multi-Agent Systems

One of my favorite features is the sub-agent system. You can break complex tasks into small pieces and distribute them to expert agents:

const researchAgent = new Agent({
  name: "Researcher",
  instructions: "Research topics thoroughly using web search",
  tools: [webSearchTool],
});

const writerAgent = new Agent({
  name: "Writer",
  instructions: "Write engaging content based on research",
  tools: [contentGenerator],
});

const coordinator = new Agent({
  name: "Coordinator",
  instructions: "Coordinate research and writing tasks",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  subAgents: [researchAgent, writerAgent], // Automatic delegate_task tool
});

// Complex workflow in a single call
await coordinator.generateText("Write a blog post about quantum computing");
// Coordinator will give research to researcher, writing to writer

:::important
Memory management and tool integration are the foundation of production-ready agents. Without these, you'll hit scaling issues quickly as your application grows.
:::

Debugging and Monitoring: Hooks System

One of my favorite features is also the visual console for debugging. I saw this approach for the first time in the framework world. But there's also a hooks system at the code level:

const hooks = createHooks({
  onStart: async ({ agent, context }) => {
    const requestId = `req-${Date.now()}`;
    context.userContext.set("requestId", requestId);
    console.log(`[${agent.name}] Started: ${requestId}`);
  },
  onToolStart: async ({ agent, tool, context }) => {
    const reqId = context.userContext.get("requestId");
    console.log(`[${reqId}] Tool starting: ${tool.name}`);
  },
  onToolEnd: async ({ agent, tool, output, context }) => {
    const reqId = context.userContext.get("requestId");
    console.log(`[${reqId}] Tool finished: ${tool.name}`, output);
  },
  onEnd: async ({ agent, output, context }) => {
    const reqId = context.userContext.get("requestId");
    console.log(`[${reqId}] Operation complete`);
  },
});

const agent = new Agent({
  name: "Observable Agent",
  // ... other config
  hooks, // Full traceability
});

This system is very valuable in production. You can trace every tool call, every agent interaction.

Voice Capabilities

Voice integration is also one of the features we added recently. We have both OpenAI and ElevenLabs support:

import { ElevenLabsVoiceProvider } from "@voltagent/voice";

const voiceProvider = new ElevenLabsVoiceProvider({
  apiKey: process.env.ELEVENLABS_API_KEY,
  voice: "Rachel",
});

const agent = new Agent({
  name: "Voice Assistant",
  instructions: "A helpful voice assistant",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o"),
  voice: voiceProvider,
});

// Generate text response
const response = await agent.generateText("Tell me a short story");

// Convert to voice
if (agent.voice && response.text) {
  const audioStream = await agent.voice.speak(response.text);
  // Save audioStream to file or play it
}

Speech-to-text is there too, you can convert audio inputs to text.

VoltOps Platform Experience

npm run dev
# ══════════════════════════════════════════════════
# VOLTAGENT SERVER STARTED SUCCESSFULLY
# ══════════════════════════════════════════════════
# ✓ HTTP Server: http://localhost:3141
# VoltOps Platform: https://console.voltagent.dev
# ══════════════════════════════════════════════════

From the console you can do real-time conversation monitoring, tool execution tracing, memory state inspection, performance metrics, error debugging. Debugging has never been this fun.

The best part is, all these features are composable. You can use whatever combination you want - just memory, just tools, just voice, or all of them together. The framework doesn't force you into anything but everything is ready when you need it.

Real World Examples

Examples from the community are really inspiring. Like an e-commerce customer support bot:

const supportAgent = new Agent({
  name: "support-bot",
  instructions: "E-commerce customer support, can track orders",
  tools: [orderLookupTool, refundProcessTool, humanHandoffTool],
  memory: new ConversationMemory(),
});

This system achieved 35% less human escalation, 60% faster response time, 24/7 availability.

A developer made a repository analysis tool:

const codeAnalyzer = new Agent({
  name: "code-analyzer",
  instructions: "Analyze repository, make suggestions",
  tools: [githubConnector, codeQualityAnalyzer, documentationChecker],
});

Their feedback was: "I made a production-ready tool in 3 days, normally it would take weeks!"

A company also set up a RAG system for their documentation:

const retrieverAgent = new Agent({
  name: "document-finder",
  instructions: "Find relevant documents from vector DB",
  tools: [vectorSearchTool, rankingTool],
});

const responderAgent = new Agent({
  name: "answer-generator",
  instructions: "Create detailed answer using context",
  subAgents: [retrieverAgent],
});

Performance and Cost Reality

warning

LLM costs can escalate quickly in production. A single poorly optimized agent can burn through hundreds of dollars per day. Always implement cost monitoring from day one.

AI services are expensive, let's not forget that. But you can save serious money with the right optimizations. You can filter unnecessary tokens with smart context compression, you don't make API calls again for the same questions with response caching, you combine operations with batch processing.

My favorite feature is intelligent model selection:

const adaptiveAgent = new Agent({
  name: "smart-agent",
  model: adaptiveModel({
    simple: "gpt-4o-mini", // Simple tasks
    complex: "gpt-4o", // Complex reasoning
    coding: "claude-3-5-sonnet", // Code writing
  }),
});

Typical results are around 30-50% token savings.

Scaling challenges exist too of course. Memory management becomes difficult when thousands of agents run simultaneously, you need to be careful not to exceed provider API limits, the system should continue when an agent fails. To solve these, you need systems like connection pooling, circuit breaker pattern, automatic retry, graceful degradation.

Community and Ecosystem

The most valuable asset of frameworks is their community. Open source frameworks have these advantages: community contributions, transparency, customization freedom, no vendor lock-in. Commercial solutions offer professional support, enterprise features, SLA guarantees.

In Voltagent for example, MCP integration came from the community, now it's a core feature. Voice improvements, provider extensions, real-world examples - all community contributions.

Future Trends

Multi-modal agents are coming - text + vision + audio capabilities are combining. There's an autonomous learning trend - agents improving themselves. Agent-to-agent communication will become widespread, we'll see cross-organization agent networks. Edge deployment is also growing - lightweight agents running in browsers. No-code builders are developing for non-technical users.

Practical Tips

When choosing a framework, start small, test with a pilot project. Evaluate the community - how are documentation, support, examples? Think about migration path - how hard will it be if you need to change frameworks?

Build a simple chatbot first, then gradually add memory, tools, and multi-agent features. This approach helps you understand each component before building complex systems.

During development give specific instructions - not "do everything", but clear tasks. Apply single responsibility principle in tool design. Think about your memory strategy - how much context, how long? Don't neglect error handling - graceful failures, user experience is important.

When going to production don't forget monitoring setup - metrics, alerting, debugging. Keep API costs under control with rate limiting. Don't neglect security - input validation, output filtering. Do load testing, performance optimization for scalability.

Conclusion

The AI agent space is evolving rapidly. What you build today should be flexible enough to adapt to new models, capabilities, and paradigms that will emerge in the coming months.

LLM Agent Framework aren't just a technology. They're building the foundation of AI-first software development. By the end of 2025, every software company will have AI agents, LLM agent frameworks will become part of the standard development stack, multi-modal interaction will become normal, cost/performance ratio will improve dramatically.

To get started, research existing frameworks - Voltagent, LangChain, AutoGen and others. Try with a small pilot project. Read documentation, check examples, join communities. Test with real users.

This post is just the beginning. AI agent technology is developing so fast that in 6 months there will be new trends, new frameworks, new possibilities. What matters is being part of this transformation.

What is Vercel AI SDK?

Necati Özmen — Thu, 29 May 2025 09:10:01 +0000

We all want to add those smart, cool features to our apps, but sometimes the tech side war can get a bit much for all of us. That's where tools like Vercel AI SDK come in, and I wanted to share a few notes on how they can simplify things. When I first looked into it, the practical solutions it offered really caught my eye.

A Quick Look at Vercel AI SDK

So, in a nutshell, Vercel AI SDK is a library aimed at making it easier to build AI-powered user interfaces and apps. Its main goal is to make working with Large Language Models (LLMs) and other AI models smoother and more manageable.

Basically, instead of wrestling with complex APIs and endless configs, it offers a more developer-friendly approach.

When to Use What

If you're building simple AI features like a chat interface or text completion, Vercel AI SDK alone might be enough. But for more complex, autonomous agents that need memory and advanced decision-making, consider combining it with VoltAgent as we'll discuss later.

Of course, if your goal is to build more comprehensive, autonomous AI agents that can make their own decisions, then frameworks like VoltAgent are also worth checking out. I'll get to that in a bit.

What's Vercel AI SDK Got to Offer?

So, what makes Vercel AI SDK so interesting for us developers? Let's take a closer look at some of its standout features:

Broad Model Support and Flexibility
One of its biggest pluses, I think, is that it lets you work with popular model providers like OpenAI, Anthropic, Google Gemini, and Hugging Face through a single API. This saves you the hassle of dealing with different SDKs and integrations for each model.

This kind of standardization can be a real time-saver in development. It usually auto-detects API keys like OPENAI_API_KEY or ANTHROPIC_API_KEY that you define in your .env files or system environment variables and sets up the connection. Easy peasy.

:::note API Key Management
Vercel AI SDK will automatically look for environment variables like OPENAI_API_KEY or ANTHROPIC_API_KEY. Make sure these are properly set in your development environment or deployed application.
:::

Streaming and Ease of Use
You know how important streaming responses from AI is for user experience, especially in chat apps. Vercel AI SDK provides tools to make this easier.

It supports streaming not just text, but also structured data like JSON. Plus, if you're working with frameworks like Next.js, the React hooks and helper functions like useChat and useCompletion provided by Vercel AI SDK make building common AI interactions like chat and autocomplete on the UI side pretty straightforward.

Other Key Features:

generateText / streamText: These are the basic functions for text-based interactions and instant responses. Core stuff for Vercel AI SDK.
generateObject / streamObject: Super useful when you need to generate structured data (like JSON). It works integrated with schema definition libraries like Zod, so you can get the model to produce data in a specific structure. This can be a lifesaver, especially for data extraction or scenarios requiring formatted output. Keep in mind, support for these functions might depend on the capabilities of the underlying model.
Function Calling: Compatible models can call predefined external functions or tools, which seriously boosts the agents' capabilities. For example, an agent can fetch data from an external API or perform an action this way.
Multi-modal Support: It also supports models that can process inputs in different formats, not just text, like images. Vercel AI SDK passes these multi-modal message structures to the underlying model if it supports them.
Provider-Specific Options: Sometimes, even when you're using a higher-level tool like VoltAgent, you might want to use a very specific parameter offered by Vercel AI SDK or a specific model provider underneath it (like OpenAI). Vercel AI SDK gives you the flexibility to pass these provider-specific options (under the provider object) directly to the underlying SDK functions during calls. This means more fine-tuning and control for you.

Performance Tip

When using features like streamObject() with large response structures, consider implementing progressive UI rendering to maintain responsiveness, as the validation process might cause slight delays in complex response schemas.

So yeah, the speed, flexibility, and ease of use that Vercel AI SDK offers developers probably explain why it's become so popular.

VoltAgent: For Building More Advanced AI Agents

Now let's talk a bit about VoltAgent. While Vercel AI SDK makes interacting with LLMs easier, VoltAgent is a TypeScript framework designed for creating more complex and autonomous AI agents. With VoltAgent, you can develop agents that can perform specific tasks, make decisions, and interact with various tools.

Core Components of VoltAgent

At the heart of VoltAgent is the Agent class, which defines the agent's behaviors and capabilities. An agent basically consists of these components: instructions (defining the agent's purpose and behavior), an LLM Provider (managing communication with the model), and, of course, the specific model to be used.

There are also some additional features that make VoltAgent particularly powerful:

Tools: Allow agents to interact with the outside world, use APIs, or gather data.
Memory: Stores conversation history or important information to provide more consistent and context-aware interactions.
Sub-Agents: Allows complex tasks to be broken down and delegated to smaller, specialized agents.
Providers: These are the interfaces that define how VoltAgent communicates with different LLM services. And this is where our integration with Vercel AI SDK comes into play.

VoltAgent and Vercel AI SDK Working Together

The integration between VoltAgent and Vercel AI SDK is handled quite elegantly through the @voltagent/vercel-ai Provider. This provider acts as a bridge between VoltAgent and Vercel AI SDK, allowing VoltAgent agents to easily use Vercel AI SDK's core functions like generateText, streamText, and generateObject. If you're curious about the details, you can check out our documentation in the website/docs/providers/vercel-ai.md file.

So How Does This Integration Work in Practice?
When you create an Agent with VoltAgent, you use an instance of VercelAIProvider as the LLM provider and Vercel AI SDK's model definition functions (e.g., openai("gpt-4o") via @ai-sdk/openai) for the model. This way, model selection and management are done according to Vercel AI SDK's standards.

Below is a basic code example from our VoltAgent documentation that shows this integration:

import { Agent } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
// Model definitions come from Vercel AI SDK's respective packages
import { openai } from "@ai-sdk/openai";
// If you want to use a different model, for example Anthropic:
// import { anthropic } from "@ai-sdk/anthropic";

// An example agent using an OpenAI model via Vercel AI SDK
const agent = new Agent({
  name: "Vercel Powered Assistant",
  instructions: "This assistant uses an OpenAI model via Vercel AI SDK.",
  llm: new VercelAIProvider(), // The Vercel AI Provider
  model: openai("gpt-4o"), // OpenAI model defined with Vercel AI SDK
});

// Now you can call methods like generateText, streamText on this 'agent' instance
// using the Vercel AI SDK infrastructure.
// For example:
// async function testAgent() {
//   const response = await agent.generateText("Hello, world!");
//   console.log(response.text);
// }
// testAgent();

Installation Note

Don't forget to install both packages:

npm install @voltagent/core @voltagent/vercel-ai @ai-sdk/openai

And ensure you have the appropriate API keys in your environment.

As you can see in this example, an Agent can be easily configured using VercelAIProvider and Vercel AI SDK's model definition functions (openai, anthropic, etc.). This allows you to combine VoltAgent's agent capabilities with Vercel AI SDK's model variety and ease of use.

What Are the Advantages of This Integration for Us Developers?

Easy access to the wide range of models supported by Vercel AI SDK through VoltAgent.
Leveraging Vercel AI SDK's powerful capabilities for text and structured data generation within VoltAgent.
Easier integration of features like multi-modal support into VoltAgent agents with Vercel AI SDK's backing.
And of course, our documentation at Vercel AI Provider docs serves as a practical example of this integration.

Use Cases

We can think of a few scenarios where this integration can be practically useful:

Example 1: Chat Applications with Streaming Responses
If you're developing a chatbot for customer service or information queries, providing quick and streaming responses to user questions is crucial. By using VoltAgent with VercelAIProvider and leveraging the streamText feature, you can ensure that responses flow to the user instantly.

Example 2: Extracting Structured Data from Text
Let's say you need to extract specific information (like keywords from an article or technical specs from a product description) from long texts into a structured format like JSON. VoltAgent can help you automate such tasks by using Vercel AI SDK's generateObject capability and schema definition tools like Zod.

Common Integration Pitfall

When working with schema validation in generateObject, avoid overly complex nested schemas in your initial implementation. Start with simpler structures and gradually build complexity, as deeply nested objects can sometimes cause validation errors that are difficult to debug.

Also, as we mentioned in our Vercel AI Provider file, it's also possible to pass specific configuration options (provider-specific options) for Vercel AI SDK through VoltAgent if you need to. This gives you flexibility.

A General Assessment

In short, Vercel AI SDK offers a really useful toolkit for modern AI application development. It saves us all time by simplifying interactions with LLMs. VoltAgent, on the other hand, provides a platform to build more complex and autonomous AI agents on top of this solid foundation. The combination of these two tools offers us developers quite a wide range of possibilities for creating various AI solutions.

What's Next? And What's This About AI SDK 5

The Vercel team recently announced AI SDK 5 - a complete redesign of the SDK's protocol and architecture. Based on two years of real-world usage, they've rebuilt the foundation to better support today's more complex LLM capabilities.

What's New in AI SDK 5

AI SDK 5 represents a fundamental redesign based on real-world usage. The original protocol was designed when LLMs mainly generated text or tool calls, but today's models can generate reasoning, sources, images, and much more. The new protocol is designed to support these advanced capabilities and emerging use cases like computer-using agents.

Why the change? Simply put, the LLM landscape has evolved dramatically. Modern models do far more than just text generation - they reason, cite sources, create visuals, and even control computers. The old architecture wasn't designed for these capabilities, so a fresh start was needed.

warning: Migration Considerations

If you're already using Vercel AI SDK v3/v4 and planning to upgrade to v5, be prepared for breaking changes. The protocol has been completely redesigned, so you'll need to update your integration code. Consider creating a migration plan and testing thoroughly before deploying to production.

Building a Data-Aware Chatbot with VoltAgent and Peaka

Necati Özmen — Tue, 27 May 2025 06:44:29 +0000

Introduction

In this article, I'll demonstrate how we can use the Model Context Protocol (MCP) by integrating VoltAgent and Peaka to create an AI agent with data retrieval capabilities.

Refer to example project built in this post.

Wait, What's Peaka?

Right, before I show you the code stuff, let me tell you about Peaka.

Their idea is pretty simple: make it less annoying to work with data. Think of it like a data middleman. You hook up your databases, spreadsheets, whatever, to Peaka. Then you can ask it questions (using fancy SQL code or just regular English), and it pulls the info together from all those places for you.

Usually, connecting different data sources is a real pain and costs a lot. Peaka feels like a simpler option, especially if you're not a huge company or just don't want to mess with complicated data pipelines. They wanna be the easy button for getting data.

And VoltAgent?

It's our toolkit for putting together AI powered applications. We provide the core engine (@voltagent/core) to get you started, and then you can add extra capabilities, like voice interaction (@voltagent/voice) or support for different LLMs (OpenAI, Google, etc.). VoltAgent handles the complex stuff (like history and tool connections) so you can focus on your agent's unique features.

We designed VoltAgent to hit a nice sweet spot. It gives you more helpful structure than trying to build everything from raw AI libraries, but it offers a lot more freedom and customization than the simpler no-code platforms out there.

We also built the VoltAgent Console a web interface that lets you monitor your agents, see exactly how they're working, and chat with them directly. We find it incredibly useful ourselves for debugging and testing!

Making My Agent Talk to Peaka

Okay, so my plan was: build a chatbot with VoltAgent that could answer questions by checking data in Peaka.

To make these two talk, I used something called MCP (Model Context Protocol). It sounds fancy, but it's basically just a standard way for different programs to give each other tasks. If you wanna know more, I wrote about what MCP is over here.

For this project, it lets VoltAgent tell Peaka, "Hey, go run this data query!"

To follow along, you'll want to sign up for a free Peaka account first over at https://www.peaka.com/. For this example, I'm just using the sample data they provide, which you'll have access to once you sign up.

Here's how I did it.

1. Starting a New VoltAgent Project

First up, I needed a blank VoltAgent project. Their setup tool makes this easy:

npm create voltagent-app@latest my-peaka-agent
# Answer the questions it asks
cd my-peaka-agent

That just makes a folder with the basic files I need to get started.

2. Telling VoltAgent About Peaka (The MCP Bit)

This is where the magic happens. I had to edit the main code file (src/index.ts) to tell VoltAgent how to find and talk to the Peaka tool using MCP.

This is the key chunk of code I put in:

// src/index.ts

import { VoltAgent, Agent, MCPConfiguration } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai"; // Using Vercel's helper stuff for the AI
import { openai } from "@ai-sdk/openai"; // And using OpenAI's model

// 1. Set up the connection to the Peaka MCP tool
const mcp = new MCPConfiguration({
  id: "peaka-mcp", // Just a nickname for this setup
  servers: {
    // Here's the info for the Peaka tool
    peaka: {
      type: "stdio", // Means it runs like a command-line program
      command: "npx", // The command to start it
      // npx is neat, it grabs the latest Peaka MCP tool automatically
      args: ["-y", "@peaka/mcp-server-peaka@latest"],
      // Gotta give it my Peaka API key (stored safely elsewhere!)
      env: { PEAKA_API_KEY: process.env.PEAKA_API_KEY || "" },
    },
  },
});

// 2. Find out what the Peaka tool can actually *do*
// (Need this `async` stuff because it takes a moment to connect)
(async () => {
  // Ask the MCP connection: "What tools does Peaka give us?"
  const tools = await mcp.getTools();

  // 3. Create our actual chatbot agent
  const agent = new Agent({
    name: "Peaka Data Agent",
    instructions: "I can look things up in Peaka's data.",
    llm: new VercelAIProvider(), // Which AI service to use
    model: openai("gpt-4o-mini"), // Which specific AI brain
    tools, // <-- Super important! Give the agent the tools from Peaka!
  });

  // 4. Fire up VoltAgent
  new VoltAgent({
    agents: {
      // Make our agent live
      agent,
    },
  });

  console.log("VoltAgent is running with Peaka powers!");
})();

So, what's happening here?

MCPConfiguration: I'm telling VoltAgent, "There's this Peaka tool you can run. Use npx to find the @peaka/mcp-server-peaka thing, and give it my API key when you run it." The stdio part just means it runs like a regular program on my computer.
mcp.getTools(): This is the clever bit. VoltAgent starts the Peaka tool and then asks it, "What can you do?" Peaka sends back a list of its abilities (like querying data).
new Agent(...): I'm making the chatbot itself. I give it a name, tell it what AI brain to use (gpt-4o-mini), and crucially, pass in those tools I got from Peaka. Now the chatbot knows it has these extra data powers.
new VoltAgent(...): This just starts the main VoltAgent system with my new agent included.

Before running, I needed my API keys. I made a file called .env in the project folder and put them in there:

//".env"

PEAKA_API_KEY=your_secret_peaka_key
# Don't forget your OpenAI key!
OPENAI_API_KEY=your_secret_openai_key

(Use your real keys, obviously! Keep 'em secret!)

3. Running It and Asking Stuff

Okay, code's ready, keys are in place. Time to run it!

npm run dev

My terminal showed VoltAgent starting up, and it also started the Peaka tool automatically in the background. I saw something like this:

══════════════════════════════════════════════════
  VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
  ✓ HTTP Server: http://localhost:3141

  Developer Console:    https://console.voltagent.dev
══════════════════════════════════════════════════

Now the fun test:

I popped open the VoltAgent Console in my browser.
Found my agent ("Peaka Data Assistant").
Opened the chat window.
Asked it something that needed data from Peaka, maybe like:

"Hey, what was my Stripe balance yesterday?"

Here's the cool part of what goes on:

The chatbot AI gets my question.
It figures out I need data and sees it has that Peaka tool.
It decides to use the tool.
VoltAgent sends the request over to the Peaka tool (using MCP).
The Peaka tool does its thing, querying my actual Stripe data (or whatever I connected).
Peaka sends the answer back to VoltAgent.
VoltAgent gives the raw answer back to the chatbot AI.
The AI turns that raw data into a normal sentence and shows it to me in the chat.

Conclusion

Getting Peaka hooked up to my VoltAgent bot with MCP wasn't too bad! It's pretty awesome to have a chatbot that can actually use real-time data from different places. I can see this being useful for building smarter internal tools, helpdesk bots that know current info, or anything where the AI needs to know more than just what it was trained on.

Definitely worth playing around with if you're building AI stuff!