VoltAgent : クイックスタート – ゼロから作成

by

VoltAgent を既存の TypeScript プロジェクトに追加しましょう。このガイドは構成設定のセットアップ、依存関係のインストール、そして最初のエージェントの作成を段階的に説明します。

VoltAgent : クイックスタート – ゼロから作成

作成 : クラスキャット・セールスインフォメーション
作成日時 : 12/18/2025
バージョン : @voltagent/core@1.4.0

* 本記事は voltagent.dev/docs の以下のページを独自に翻訳した上で、補足説明を加えてまとめ直しています。スニペットはできる限り日本語を使用しています :

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

 

 

VoltAgent : クイックスタート – ゼロから作成

VoltAgent を既存の TypeScript プロジェクトに追加しましょう。このガイドは構成設定のセットアップ、依存関係のインストール、そして最初のエージェントの作成を段階的に説明します。

  1. プロジェクト・ディレクトリの作成

    新しいプロジェクト・ディレクトリを作成して npm or pnpm を初期化します :

    mkdir my-voltagent-project
cd my-voltagent-project

    npm

    npm init -y

    pnpm

    pnpm init

  2. TypeScript の設定

    tsconfig.json を作成します :

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

    tsconfig.json とともに tsdown.config.ts を追加して、プロダクション・ビルドで正しくバンドルされるようにします :

    import { defineConfig } from "tsdown";

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

  3. 依存関係のインストール

    VoltAgent と開発ツールをインストールします :

    npm

    # Install development dependencies
npm install --save-dev typescript tsx tsdown @types/node @voltagent/cli

# Install dependencies
npm install @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/logger ai @ai-sdk/openai@^2 zod@3

    pnpm

    # Install development dependencies
pnpm add --save-dev typescript tsx tsdown @types/node @voltagent/cli

# Install dependencies
pnpm add @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/logger ai @ai-sdk/openai@^2 zod@3

  4. エージェントの作成

    ソースディレクトリとエージェントファイルを作成します :

    mkdir src

    Create src/index.ts:

    import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono"; // HTTP server
import { LibSQLMemoryAdapter } from "@voltagent/libsql"; // For persistent memory
import { openai } from "@ai-sdk/openai"; // Example model
import { createPinoLogger } from "@voltagent/logger";

// Create logger (optional but recommended)
const logger = createPinoLogger({
  name: "my-agent",
  level: "info",
});

// Define a simple agent
const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that answers questions without using tools",
  // VoltAgent uses ai-sdk directly - pick any ai-sdk model
  model: openai("gpt-4o-mini"),
  // Optional: Add persistent memory (remove this to use default in-memory storage)
  memory: new Memory({
    storage: new LibSQLMemoryAdapter({
      url: "file:./.voltagent/memory.db",
    }),
  }),
});

// Initialize VoltAgent with your agent(s)
new VoltAgent({
  agents: { agent },
  server: honoServer(), // Default port: 3141
  logger,
});

  5. 環境設定

    .env ファイルを作成して API キーを追加します (以下のいずれか) :

    OPENAI_API_KEY=your-api-key-here
ANTHROPIC_API_KEY=your-api-key-here
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key-here
GROQ_API_KEY=your-api-key-here

    package.json に以下を追加します :

    "type": "module",
"scripts": {
  "build": "tsdown",
  "dev": "tsx watch --env-file=.env ./src",
  "start": "node dist/index.js",
  "volt": "volt"
}

    プロジェクト構造はこのようになります :

    my-voltagent-project/
├── node_modules/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
├── tsdown.config.ts
├── .env
└── .voltagent/ (created automatically when you run the agent)

  6. エージェントの実行

    npm

    npm run dev

    pnpm

    pnpm dev

    VoltAgent サーバの起動メッセージを見るはずです :

    ══════════════════════════════════════════════════
  VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
  ✓ HTTP Server:  http://localhost:3141
  ↪ Share it:    pnpm volt tunnel 3141 (secure HTTPS tunnel for teammates)
     Docs: https://voltagent.dev/docs/deployment/local-tunnel/
  ✓ Swagger UI:   http://localhost:3141/ui

  Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════

  7. エージェントのテスト

    https://console.voltagent.dev を開き、サイドバーの Agents & Workflows をクリックしてエージェントを見つけます。

    それを選択し、右下のチャットアイコンをクリックして、”Hello” のようなメッセージを送信してみてください。

    AI エージェントからレスポンスを受け取るはずです。dev スクリプトは tsx watch を使用しているので、コードに変更を加えると自動的に再起動します。

 

以上