🍣
VoltAgent V1ついにリリース！ 0.1.x → 1.x 移行ポイントまとめ＋VoltOpsの更新点
こんにちは！前々から使ってたTypescriptベースのAIエージェントフレームワークVoltAgentが先ほどV1.xにアップデートされました！
voltopsという管理画面でもUI面での改善が加えられ開発速度の向上が見込めそうです。
本記事は公式の移行ガイドをベースに、実機での所感（VoltOps の画面/ログ改善）も補足してまとめたものです。
参照: Migration guide: 0.1.x → 1.x
TL;DR
-
ai‑sdk をネイティブ採用: 独自 LLM プロバイダ層と
@voltagent/vercel-aiを廃止。モデルは ai‑sdk のプロバイダを直接指定。 -
サーバはプラガブル化: コア内蔵サーバ撤廃。
@voltagent/server-honoをserver: honoServer()で渡す。 - Memory v2（アダプタ化）: LibSQL / PostgreSQL / Supabase などに拡張可能（デフォルトは InMemory）。
- Observability は OpenTelemetry（OTel）に統一: レガシーのテレメトリエクスポータは削除。
-
Breaking Changes:
abortController → abortSignal、Message Helpers がUIMessageに統一、onHandoff.source → sourceAgent。
1.x の背景（なぜ変わったか）
- コアの表面積縮小 & 可搬性向上（Node/Edge/Workers）。
- ai‑sdk と一体化してストリーム/結果の挙動を安定化。
- Memory をモジュール化し、インメモリから本番規模（LibSQL/Postgres/Supabase）まで段階的に拡張可能。
- **標準的な観測（OTel）**を採用し、運用・可視化の選択肢を広げる。
Step 1. パッケージ更新
# レガシー削除
npm uninstall @voltagent/vercel-ai @voltagent/vercel-ui
# 必須導入
npm install @voltagent/core@latest @voltagent/server-hono@latest @voltagent/libsql@latest @voltagent/logger@latest ai
# 例: OpenAI（ai‑sdk の任意プロバイダに置き換え可）
npm install @ai-sdk/openai
- Node >= 20（推奨/要件）、TypeScript 5.x 推奨。
-
aiは@voltagent/coreの peer 依存。未導入だと LLM 呼び出し時にモジュール解決エラー。
Step 2. コード移行（サーバ/LLM/Memory）
Before（0.1.x）
import { VoltAgent } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
new VoltAgent({
agents: { agent },
port: 3141,
enableSwaggerUI: true,
// server auto-started
});
After（1.x）
import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { honoServer } from "@voltagent/server-hono";
import { createPinoLogger } from "@voltagent/logger";
import { openai } from "@ai-sdk/openai";
const logger = createPinoLogger({ name: "my-app", level: "info" });
const memory = new Memory({
storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});
const agent = new Agent({
name: "my-app",
instructions: "Helpful assistant",
// 0.1.x: llm: new VercelAIProvider(), // ← 削除
model: openai("gpt-4o-mini"),
memory,
});
new VoltAgent({
agents: { agent },
server: honoServer({
port: 3141,
enableSwaggerUI: true,
// 任意: 認証/カスタムルート
// auth: jwtAuth({ secret: process.env.JWT_SECRET! }),
// configureApp: (app) => {
// app.get("/api/health", (c) => c.json({ status: "ok" }));
// },
}),
logger,
});
破壊的変更（押さえるべきポイント）
1. abortController → abortSignal
const ac = new AbortController();
// 0.1.x: agent.generateText("...", { abortController: ac })
const res = await agent.generateText("...", { abortSignal: ac.signal }); // 1.x
2. Message Helpers は UIMessage を使用
import { addTimestampToMessage } from "@voltagent/core/utils";
import type { UIMessage } from "ai";
const msg: UIMessage = {
id: "m1",
role: "user",
parts: [{ type: "text", text: "hello" }],
metadata: {},
} as UIMessage;
const stamped = addTimestampToMessage(msg, "10:30");
3. onHandoff 引数名の変更
// 0.1.x
// onHandoff: ({ agent, source }) => { ... }
// 1.x
onHandoff: ({ agent, sourceAgent }) => {
console.log(`${sourceAgent.name} → ${agent.name}`);
};
Memory v2（アダプタ方式）
-
new Memory({ storage: new LibSQLMemoryAdapter(...) })のように構成。 - InMemory を起点に、LibSQL / PostgreSQL / Supabase へ移行可能。
- 取得・保存・検索（ベクター検索含む）の責務をアダプタに切り出し、本番移行やスケールが容易。
Observability / VoltOps の更新点（実機所感つき）
1.x では Observability が OpenTelemetry（OTel） ベースに整理され、ログ/トレースの扱いが標準化。以下は実機使用で感じた改善点です。
1. 新しい Overview / Execution 画面
-
DAG 形式の実行ビューで、
Input → Agent → Tool(s) → Outputの流れを直感的に把握。 - ノード単位で実行状態や成否が分かり、Auto-zoom や Snapshot で視点固定も可能。
- 右側の Timeline に span が並び、「First / Play / Last」切替でトレース時点を移動できる。
画像1（新 UI 概要）: DAG + Timeline + 下部に AI Playground のレイアウト。
プロンプト/実行の前後関係が視覚的に追いやすく、「トレースが容易に」 なりました。
2. ツール/ステップ単位の詳細ログ
- 各ツール呼び出しが step/span として記録され、名前・開始/終了・所要時間・ステータスが追跡可能。
- ログに
component: agent、agentId、modelName、Trace/Span IDなどのメタ情報が付与。 - 「Reasoning generated」「Calling tool」「Tool completed」など、思考/呼び出し/完了フェーズがはっきり分かる。
画像2（詳細ログ）: ツール名（例:
get_this_week_dates）、モデル名、Trace/Span が DEBUG ログで一覧でき、
「各ツールの詳細ログが見られる」 体験に直結しています。
3. OTel 準拠による拡張性
- OpenTelemetry 準拠のスパン/ログ構造のため、OTel のプロセッサ/エクスポータ連携が取りやすい。
- ローカル観測から本番の可観測性スタックまで、段階的に強化しやすい設計。
![Observability の新 UI（Execution View + Timeline + Playground）]
![ツール実行の詳細ログ（DEBUG レベルで step/span が確認可能）]
最小構成サンプル（1.x）
import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";
const agent = new Agent({
name: "demo",
instructions: "Be helpful",
model: openai("gpt-4o-mini"),
memory: new Memory(), // InMemory（まずはここから）
});
new VoltAgent({
agents: { agent },
server: honoServer(), // デフォルト: 3141
});
参考
- 公式移行ガイド: Migration guide: 0.1.x → 1.x
Discussion