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 の場合は不要）

---

最短手順

1 つのコマンドで新しい 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：依存関係をインストールする

サーバーパッケージを 1 つ選択します：

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