create-voltagent

创建 VoltAgent 项目技能

创建新 VoltAgent 项目的完整指南。包括 CLI 流程和完整的手动设置步骤。

官方文档：https://voltagent.dev/docs/

---

从这里开始

当用户想要创建 VoltAgent 项目时，询问：

“你想如何创建 VoltAgent 项目？”

1. 自动设置 - 运行 npm create voltagent-app@latest 并处理提示
2. 交互式指南 - 逐步引导并确认选项
3. 手动安装 - 设置依赖项并提供完整的可运行示例

根据用户的选择：

• 选项 1：运行 CLI，记录服务和提供商的选择，并完成设置
• 选项 2：收集服务、提供商和 API 密钥，然后运行 CLI
• 选项 3：按照下面的手动步骤操作

---

开始之前

• Node.js 20+（建议使用 >= 20.19.0）
• Git（可选，用于自动执行 git init）
• 模型提供商的 API 密钥（使用 Ollama 时不需要）

---

快速开始

只需一条命令即可创建新的 VoltAgent 项目：

npm create voltagent-app@latest

其他包管理器：

pnpm create voltagent-app@latest
yarn create voltagent-app@latest
bun create voltagent-app@latest

---

CLI 流程

create-voltagent-app 命令会：

1. 请求输入项目名称（默认值：my-voltagent-app）
2. 提示选择服务框架（Hono 或 Elysia）
3. 提示选择 AI 提供商（OpenAI、Anthropic、Google、Groq、Mistral、Ollama）
4. 在需要时提示输入 API 密钥
5. 安装依赖项并搭建项目框架
6. 写入 .env、README.md、tsconfig.json、tsdown.config.ts 和 Docker 文件
7. 在可用时初始化 git 仓库

---

CLI 操作步骤

1. 运行：

   npm create voltagent-app@latest
   

2. 出现提示时：

   • 选择服务（推荐 Hono，也可选择 Elysia）
   • 选择 AI 提供商
   • 输入 API 密钥（使用 Ollama 时可跳过）

3. 启动开发服务器：

   cd <your-project-directory>
   npm run dev
   

4. 如果选择了 Ollama：

   ollama pull llama3.2
   

---

CLI 标志和示例

在指定目录中创建：

npm create voltagent-app@latest my-voltagent-app

从 VoltAgent 仓库下载示例：

npm create voltagent-app@latest -- --example with-workflow

pnpm / yarn / bun 对应命令：

pnpm create voltagent-app@latest -- --example with-workflow
yarn create voltagent-app@latest -- --example with-workflow
bun create voltagent-app@latest -- --example with-workflow

说明：

• 示例取自 https://github.com/voltagent/voltagent/tree/main/examples
• 某些包管理器要求在 --example 前添加 --。
• 下载示例后，运行 npm install 和 npm run dev。

---

生成的目录结构

my-voltagent-app/
|-- src/
|   |-- index.ts
|   |-- tools/
|   |   |-- index.ts
|   |   `-- weather.ts
|   `-- workflows/
|       `-- index.ts
|-- .env
|-- .voltagent/
|-- Dockerfile
|-- .dockerignore
|-- .gitignore
|-- README.md
|-- package.json
|-- tsconfig.json
`-- tsdown.config.ts

如果在此仓库中运行文档同步脚本，还可能会看到生成的 packages/core/docs。

---

环境变量键

CLI 会写入包含提供商密钥（或占位符）的 .env。常见的键：

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_GENERATIVE_AI_API_KEY=...
GROQ_API_KEY=...
MISTRAL_API_KEY=...
OLLAMA_HOST=http://localhost:11434

VOLTAGENT_PUBLIC_KEY=...
VOLTAGENT_SECRET_KEY=...

---

手动设置（完整步骤）

如果不想使用 CLI，请按照以下步骤操作：

步骤 1：创建项目目录

mkdir my-voltagent-app && cd my-voltagent-app
npm init -y
mkdir -p src/tools src/workflows .voltagent

步骤 2：安装依赖项

选择一个服务包：

npm install @voltagent/core @voltagent/libsql @voltagent/logger @voltagent/server-hono @voltagent/cli ai zod dotenv

或

npm install @voltagent/core @voltagent/libsql @voltagent/logger @voltagent/server-elysia @voltagent/cli ai zod dotenv

开发依赖项：

npm install -D typescript tsx tsdown @types/node @biomejs/biome

步骤 3：向 package.json 添加脚本

{
  "scripts": {
    "dev": "tsx watch --env-file=.env ./src",
    "build": "tsdown",
    "start": "node dist/index.js",
    "lint": "biome check ./src",
    "lint:fix": "biome check --write ./src",
    "typecheck": "tsc --noEmit",
    "volt": "volt"
  }
}

volt 是 VoltAgent CLI。可将其用于项目实用工具（例如 init、deploy、eval、prompts、tunnel、update）。

步骤 4：配置 TypeScript

创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "outDir": "dist",
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

步骤 5：添加 tsdown 配置

创建 tsdown.config.ts：

import { defineConfig } from "tsdown";

export default defineConfig({
  entry: ["./src/index.ts"],
  sourcemap: true,
  outDir: "dist",
});

步骤 6：创建 .env

OPENAI_API_KEY=your-api-key-here
VOLTAGENT_PUBLIC_KEY=your-public-key
VOLTAGENT_SECRET_KEY=your-secret-key
NODE_ENV=development

对于 Ollama：

OLLAMA_HOST=http://localhost:11434

步骤 7：创建工具

创建 src/tools/weather.ts：

import { createTool } from "@voltagent/core";
import { z } from "zod";

export const weatherTool = createTool({
  name: "getWeather",
  description: "Get the current weather for a specific location",
  parameters: z.object({
    location: z.string().describe("City or location to get weather for"),
  }),
  execute: async ({ location }) => {
    return {
      weather: {
        location,
        temperature: 21,
        condition: "Sunny",
        humidity: 45,
        windSpeed: 8,
      },
      message: `Current weather in ${location}: 21 C and sunny.`,
    };
  },
});

创建 src/tools/index.ts：

export { weatherTool } from "./weather";

步骤 8：创建工作流

创建 src/workflows/index.ts：

import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

export const expenseApprovalWorkflow = createWorkflowChain({
  id: "expense-approval",
  name: "Expense Approval Workflow",
  purpose: "Process expense reports with manager approval for high amounts",
  input: z.object({
    employeeId: z.string(),
    amount: z.number(),
    category: z.string(),
    description: z.string(),
  }),
  result: z.object({
    status: z.enum(["approved", "rejected"]),
    approvedBy: z.string(),
    finalAmount: z.number(),
  }),
})
  .andThen({
    id: "check-approval-needed",
    resumeSchema: z.object({
      approved: z.boolean(),
      managerId: z.string(),
      comments: z.string().optional(),
      adjustedAmount: z.number().optional(),
    }),
    execute: async ({ data, suspend, resumeData }) => {
      if (resumeData) {
        return {
          ...data,
          approved: resumeData.approved,
          approvedBy: resumeData.managerId,
          finalAmount: resumeData.adjustedAmount || data.amount,
          managerComments: resumeData.comments,
        };
      }

      if (data.amount > 500) {
        await suspend("Manager approval required", {
          employeeId: data.employeeId,
          requestedAmount: data.amount,
          category: data.category,
        });
      }

      return {
        ...data,
        approved: true,
        approvedBy: "system",
        finalAmount: data.amount,
      };
    },
  })
  .andThen({
    id: "process-decision",
    execute: async ({ data }) => {
      return {
        status: data.approved ? "approved" : "rejected",
        approvedBy: data.approvedBy,
        finalAmount: data.finalAmount,
      };
    },
  });

步骤 9：创建入口点

创建 src/index.ts：

import "dotenv/config";
import {
  Agent,
  Memory,
  VoltAgent,
  VoltAgentObservability,
  VoltOpsClient,
} from "@voltagent/core";
import { LibSQLMemoryAdapter, LibSQLObservabilityAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
import { expenseApprovalWorkflow } from "./workflows";
import { weatherTool } from "./tools";

const logger = createPinoLogger({ name: "my-voltagent-app", level: "info" });

const memory = new Memory({
  storage: new LibSQLMemoryAdapter({
    url: "file:./.voltagent/memory.db",
    logger: logger.child({ component: "libsql" }),
  }),
});

const observability = new VoltAgentObservability({
  storage: new LibSQLObservabilityAdapter({
    url: "file:./.voltagent/observability.db",
  }),
});

const agent = new Agent({
  name: "my-voltagent-app",
  instructions: "A helpful assistant that can check weather and help with various tasks",
  model: "openai/gpt-4o-mini",
  tools: [weatherTool],
  memory,
});

new VoltAgent({
  agents: { agent },
  workflows: { expenseApprovalWorkflow },
  server: honoServer(),
  logger,
  observability,
  voltOpsClient: new VoltOpsClient({
    publicKey: process.env.VOLTAGENT_PUBLIC_KEY || "",
    secretKey: process.env.VOLTAGENT_SECRET_KEY || "",
  }),
});

模型格式为 provider/model。示例：

• openai/gpt-4o-mini
• anthropic/claude-3-5-sonnet
• google/gemini-2.0-flash
• groq/llama-3.3-70b-versatile
• mistral/mistral-large-latest
• ollama/llama3.2

如果选择了 Elysia，请将 honoServer 替换为 elysiaServer，并更新导入语句。

步骤 10：运行开发服务器

npm run dev