AgentSkillsCN

VoltAgent Development

借助工具、记忆模块、钩子及子代理，创建并配置VoltAgent AI智能体。适用于构建AI智能体、为智能体添加工具、配置VoltAgent记忆库、打造多智能体工作流，或对VoltAgent集成进行调试时使用。

SKILL.md
--- frontmatter
name: "VoltAgent Development"
description: "Create and configure VoltAgent AI agents with tools, memory, hooks, and sub-agents. Use when building AI agents, adding agent tools, configuring VoltAgent memory, creating multi-agent workflows, or debugging VoltAgent integrations."

VoltAgent Development

What This Skill Does

Guides development of VoltAgent-based AI agents including:

  • •Agent creation and configuration
  • •Tool development with Zod schemas
  • •Memory persistence with LibSQL
  • •Multi-agent orchestration with sub-agents
  • •Lifecycle hooks and guardrails
  • •Streaming and structured output

Prerequisites

  • •@voltagent/core package
  • •AI SDK provider (e.g., @ai-sdk/anthropic, @ai-sdk/openai)
  • •zod for schema validation

Quick Start

Basic Agent

typescript
import { Agent } from '@voltagent/core'
import { anthropic } from '@ai-sdk/anthropic'

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
  model: anthropic('claude-3-5-haiku-20241022'),
})

const result = await agent.generateText('Hello!')
console.log(result.text)

Agent with Tools

typescript
import { Agent, createTool } from '@voltagent/core'
import { z } from 'zod'

const weatherTool = createTool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: z.object({
    location: z.string().describe('The city name'),
  }),
  execute: async ({ location }) => {
    return { location, temperature: 72, conditions: 'sunny' }
  },
})

const agent = new Agent({
  name: 'Weather Assistant',
  instructions: 'Help users with weather information.',
  model: anthropic('claude-3-5-haiku-20241022'),
  tools: [weatherTool],
})

Tool Development

Basic Tool Pattern

typescript
import { createTool } from '@voltagent/core'
import { z } from 'zod'

export const myTool = createTool({
  name: 'tool_name',           // snake_case convention
  description: 'Clear description of what this tool does',
  parameters: z.object({
    param: z.string().describe('What this parameter is for'),
    optional: z.number().optional().describe('Optional parameter'),
  }),
  execute: async (args, options) => {
    // Access context from options
    const userId = options?.context?.get('userId')
    const isAdmin = options?.context?.get('isAdmin') === 'true'

    // Implement tool logic
    return { result: 'data' }
  },
})

Tool with Database Access (Project Pattern)

typescript
import { createTool } from '@voltagent/core'
import { z } from 'zod'

export const fetchClientsTool = createTool({
  name: 'fetch_clients',
  description: 'Get list of clients for the current trainer',
  parameters: z.object({
    limit: z.number().optional().describe('Max clients to return'),
  }),
  execute: async ({ limit = 10 }, options) => {
    const db = useDB()
    const trainerId = options?.context?.get('trainerId')
    const isSuperAdmin = options?.context?.get('isSuperAdmin') === 'true'

    // Super admins see all clients, trainers see only assigned
    const clients = isSuperAdmin
      ? await db.select().from(users).limit(limit)
      : await db.select().from(users)
          .innerJoin(clientsTrainers, eq(users.id, clientsTrainers.clientId))
          .where(eq(clientsTrainers.trainerId, trainerId))
          .limit(limit)

    return { clients, count: clients.length }
  },
})

Tool with Cancellation Support

typescript
const longRunningTool = createTool({
  name: 'search_web',
  description: 'Search the web (supports cancellation)',
  parameters: z.object({
    query: z.string().describe('Search query'),
  }),
  execute: async ({ query }, options) => {
    const signal = options?.abortController?.signal

    if (signal?.aborted) {
      throw new Error('Search cancelled before start')
    }

    const response = await fetch(`https://api.search.com?q=${query}`, { signal })
    return await response.json()
  },
})

See tool-template.ts for a complete template.

Critical Rules

✅ DO

  • •Use model directly with ai-sdk LanguageModel instances
  • •Use instructions (string or function), NOT systemPrompt
  • •Provide detailed descriptions for tools AND parameters
  • •Use Zod .describe() for all parameters
  • •Always provide userId and conversationId for memory
  • •Use LibSQL/Turso for production memory persistence

❌ DON'T

  • •Use deprecated llm + model pattern from v0.x
  • •Use generateObject/streamObject if you need tool calling
  • •Assume memory persists by default (it's in-memory only)
  • •Skip parameter descriptions (LLM needs these)
  • •Let tools throw unhandled errors

Project Architecture

code
server/
  agents/
    client-insights/          # Main agent
      index.ts               # Agent definition
      tools/                 # Agent tools
        fetchClients.ts
        fetchClientDetails.ts
        searchExercises.ts
  services/
    voltagent.ts            # VoltAgent initialization
  api/
    agents/
      client-insights/
        text.post.ts        # Sync endpoint
        stream.post.ts      # Streaming endpoint

Environment Variables

bash
# Required for Anthropic (accessed directly by AI SDK)
ANTHROPIC_API_KEY=sk-ant-...

# Optional: For observability
VOLTAGENT_PUBLIC_KEY=pk_...
VOLTAGENT_SECRET_KEY=sk_...

# Optional: For Turso remote memory
TURSO_DATABASE_URL=libsql://...
TURSO_AUTH_TOKEN=...

Advanced Topics

Reference