VoltAgent : クイックスタート – VoltAgent CLI による作成

by

VoltAgent で最初の AI エージェントを構築しましょう。このガイドは、エージェントの作成、外部イベントへの接続、ワークフローの実行、そして本番環境への配備をカバーしています。

VoltAgent : クイックスタート – VoltAgent CLI による作成

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

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

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

 

 

VoltAgent : クイックスタート – VoltAgent CLI による作成

VoltAgent で最初の AI エージェントを構築しましょう。このガイドは、エージェントの作成、外部イベントへの接続、ワークフローの実行、そして本番環境への配備をカバーしています。

Looking for full recipes? Check out the Recipes & Guides section.

  1. プロジェクトの作成

    以下のコマンドを実行して新しい VoltAgent プロジェクトを作成します :

    npm

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

    pnmp

    pnpm create voltagent-app my-agent-app

    CLI はプロジェクト名、AI プロバイダー、API キーの入力を求めます。完了したら :

    cd my-agent-app

  2. 構成設定と起動

    セットアップ中に API キーの入力をスキップした場合、プロジェクトルートの .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
MISTRAL_API_KEY=your-api-key-here

    Now start the development server:

    npm run dev

    You should see the VoltAgent server startup message:

    ══════════════════════════════════════════════════
  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
══════════════════════════════════════════════════

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

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

    それを選択し、右下のチャットアイコンをクリックして、”What’s the weather in San Francisco?” と質問してみてください。

    レスポンスを受け取るはずで、理解してレスポンスを生成する最初の基本的なエージェントの作成に成功しています。

    ⚡️ ここまでで、あなたは基本的な動作をする AI エージェントを作成してテストしたことになります。次のステップは、それを外部イベント、サービスに接続して、ワークフローを使用する方法を示すことです。

  4. あなたはメッセージに応答する AI エージェントを持ちました。VoltAgent はまたイベント駆動ワークフローもサポートしています。

    • VoltAgent トリガー は、GitHub webhooks や cron スケジュールのような外部イベントをリスンします。

    • Voltagent アクション はデータを Discord や Slack のような外部サービスに送信します。

     
    これらにより、エージェントがイベントに反応し、自動的にアクションを実行することを可能にします。

    ワークフロー・ステップ :

    1. トリガー – GitHub スター webhook イベントを捕捉する

    2. AI エージェント – イベントに基づいてメッセージを生成する

    3. アクション – メッセージを Discord に送信する

     
    このワークフローをエージェントで実装するには、VoltAgent コンソールの Get Started Guide に進み、ステップ 4 から続けます。

  5. ワークフローの実行

    最初の Human-in-the-Loop ワークフローを実行する

    ワークフロー は複数のステップ (データ変換、API 呼び出し、AI エージェント・インタラクション) を単一の実行に連鎖します。一度に一つのメッセージに応答するスタンドアロン・エージェントとは異なり、ワークフローはマルチステップのプロセスを調整します。

    生成されたプロジェクトは、suspend/resume (一時停止/再開) 機能を実演する、経費承認ワークフローを含みます。ワークフローを実行を一時停止し、ユーザによる入力を待機し、それから続行します。

    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(),
  }),
})
  // Step 1: 経費を検証し、承認が必要かどうか確認します
  .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,
        };
      }

      // $500 を超える経費はマネージャの承認を必要とします
      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,
      };
    },
  })
  // Step 2: 最終的な決定の処理
  .andThen({
    id: "process-decision",
    execute: async ({ data }) => {
      return {
        status: data.approved ? "approved" : "rejected",
        approvedBy: data.approvedBy,
        finalAmount: data.finalAmount,
      };
    },
  });

     
    サンプル・ワークフローの実行

    コンソールの Workflows ページを開き、”Expense Approval Workflow” を選択して、そして “Test Workflow” をクリックします。入力して “Execute Workflow” をクリックします。

    このワークフローは、続行する前に、特定の決定がユーザの入力を必要とするような経費承認プロセスをシミュレートします :

    • $500 未満の経費はシステムにより自動承認されます。
    • $500 を超える経費は中断のトリガーとなり、マネージャが承認または拒否するまでワークフローを一時停止します。

     
    自動承認の例 ($500 未満) :

    {
  "employeeId": "EMP-123",
  "amount": 250,
  "category": "office-supplies",
  "description": "New laptop mouse and keyboard"
}

    手動レビューの例 ($500 超) :

    {
  "employeeId": "EMP-456",
  "amount": 750,
  "category": "travel",
  "description": "Flight tickets for client meeting"
}

  6. ローカルサーバの共有

    エージェントをリモートでデモしたり、外部 webhooks を受け取る必要がある場合、VoltAgent CLI をインストールしてトンネルをオープンします :

    Install the CLI (adds a volt script and dev dependency)

    npx @voltagent/cli init

    次にローカルサーバを公開します :

    pnpm volt tunnel 3141

    このコマンドは、Ctrl+C が押されるまでトラフィックをローカルポートに転送 (forward) する HTTPS URL (例えば https://your-tunnel-address.tunnel.voltagent.dev) を表示します。依存関係をインストールせずにその場限りの (ad-hoc) 実行をすることもできま :

    npx @voltagent/cli tunnel 3141

    Tip : ポートをスキップする場合 (pnpm volt tunnel)、デフォルトの 3141 を使用します。

    See the Local Tunnel guide for details.

  7. 本番環境向けビルド

    配備する準備ができたら、アプリケーションをバンドルしてコンパイルされた JavaScript を Node で実行します :

    npm

    npm run build
npm start

    pnpm

    pnpm build
pnpm start

ビルドスクリプトは tsdown を呼び出し、TypeScript エントリポイント (及び ./workflows や ./tools のような sibling ディレクトリ) を dist/index.js にバンドルします。この追加のステップにより、開発中に拡張子なし import を維持したまま、Node の ESM loader が ERR_UNSUPPORTED_DIR_IMPORT を投げるのを防げます。

 

以上