Hedera Agent Kit v4 Migration

Hedera Agent Kit v3 → v4 への移行

このスキルは、v3 → v4 への完全な移行を実行します。v4 が現在のメジャーバージョンであり、v3([email protected])は更新を受け取りません。hedera-agent-kit(スコープなし)または @hashgraph/sdk からインポートしているコードを見つけたら、いつでもこのスキルを使用してください。

クイックトリアージ — これはどの種類の v3 コードですか?

何かを編集する前に、移行対象のファイルを分類してください。移行手順は種類によって異なります。

ファイルが…	これは…	適用するもの
Plugin を定義し、execute 関数を持つオブジェクトリテラルを返すツールファクトリをエクスポートしている	カスタムプラグイン	プラグイン移行 + BaseTool 移行
new HederaLangchainToolkit / HederaAIToolkit / HederaElizaOSToolkit / HederaMCPToolkit を呼び出している	ツールキットの利用側	ツールキット移行
coreTokenPlugin、coreAccountPlugin、coreHTSPlugin などのプラグインをインポートしている	ツールキットの利用側(組み込みプラグインを使用)	ツールキット移行 + エイリアス名の変更
hedera-agent-kit から ResponseParserService または HederaMCPServer をインポートしている	ツールキットの利用側	ツールキット移行(これらはツールキットパッケージに移動しました)
両方	まずツールキット移行を実行し、その後、各ツールに対してプラグイン移行を実行します

移行ワークフロー

ステップ 1 — すべての v3 エントリポイントを見つける

何かを編集する前に、プロジェクトルートでこれらの検索を実行してください。これにより、移行対象の範囲を一度に把握できます:

# Old package name in source and dependency manifests
grep -rn "from ['\"]hedera-agent-kit" .
grep -n '"hedera-agent-kit"' package.json

# Old SDK package
grep -rn "from ['\"]@hashgraph/sdk" .
grep -n '"@hashgraph/sdk"' package.json

# Deprecated plugin aliases
grep -rn "coreHTSPlugin\|coreSCSPlugin\|coreQueriesPlugin" .

# Old subpath import
grep -rn "from ['\"]hedera-agent-kit/elizaos" .

# v3 functional Tool pattern (object literal with execute)
grep -rn "execute: " . --include="*.ts" | grep -i "tool"

編集するファイルのリストを作成してください。まだ変更を開始しないでください。

ステップ 2 — package.json を更新する

依存関係を置き換えてから、インストールを実行します。完全な表については references/breaking-changes.md の「Package mapping」セクションを、バージョン範囲については「Versioning」セクションを参照してください。簡易版は次のとおりです:

• 削除: hedera-agent-kit、@hashgraph/sdk。@langchain/core、langchain、@langchain/langgraph、ai は、コードがそれらから直接インポートしていない場合に限り削除してください。これらはツールキットの推移的依存関係であるため、厳密な解決を行うパッケージマネージャー(bun、pnpm)では、これらを保持しない限り直接インポートを満たせません。迷った場合は devDeps として保持してください。
• 追加: @hashgraph/hedera-agent-kit(^4.0.0 を使用)と @hiero-ledger/sdk(^2.81.0 を使用)、さらに使用するフレームワーク用のツールキットパッケージをちょうど 1 つ追加します。ツールキットパッケージは ^4 ではありません — このリリースで 1.0.0 に再ベースライン化されました。@hashgraph/hedera-agent-kit-langchain / -ai-sdk / -elizaos / -mcp には ^1.0.0 を使用してください。固定する前に npm view <pkg> version を実行して確認してください。
• 保持: LLM プロバイダー(@langchain/openai、@ai-sdk/openai、@langchain/anthropic など) — ツールキットがプロバイダーをバンドルすることはありません。LangChain の利用側は、プロバイダーパッケージもその 1.x 系に上げる必要があります(例: @langchain/openai@^1)。0.x 系は @langchain/core@^0.3 に依存しており、ツールキットの @langchain/core@^1 に対してデュアルパッケージの型エラーを引き起こします。references/breaking-changes.md の「LangChain ecosystem bump」を参照してください。

ステップ 3 — インポートを書き換える

references/import-cheatsheet.md の検索と置換のマップを適用してください。主な変更点:

- from 'hedera-agent-kit'        → from '@hashgraph/hedera-agent-kit'
- from '@hashgraph/sdk'          → from '@hiero-ledger/sdk'
- from 'hedera-agent-kit/elizaos' → from '@hashgraph/hedera-agent-kit-elizaos'

プラグインは /plugins サブパスから取得する必要があります:

- import { coreTokenPlugin } from 'hedera-agent-kit'
+ import { coreTokenPlugin } from '@hashgraph/hedera-agent-kit/plugins'

非推奨のエイリアス名を変更する:

削除されたもの	置き換え
coreHTSPlugin	coreTokenPlugin
coreSCSPlugin	coreEVMPlugin
coreQueriesPlugin	個別のプラグイン: coreAccountQueryPlugin、coreTokenQueryPlugin、coreConsensusQueryPlugin、coreEVMQueryPlugin、coreMiscQueriesPlugin、coreTransactionQueryPlugin

ツールキットとそのヘルパーはそれぞれ専用のパッケージに移動しました:

- import { HederaLangchainToolkit, ResponseParserService } from 'hedera-agent-kit'
+ import { HederaLangchainToolkit, ResponseParserService } from '@hashgraph/hedera-agent-kit-langchain'

- import { HederaAIToolkit } from 'hedera-agent-kit'
+ import { HederaAIToolkit } from '@hashgraph/hedera-agent-kit-ai-sdk'

- import { HederaMCPToolkit } from 'hedera-agent-kit'
+ import { HederaMCPToolkit } from '@hashgraph/hedera-agent-kit-mcp'

AgentMode、Configuration、Context、Plugin、Tool、BaseTool、handleTransaction、出力パーサー、mirrornode 型 — これらはすべて @hashgraph/hedera-agent-kit に残ります。

ステップ 4 — ツールキット設定におけるサイレントな動作変更を修正する

v3 では、空の plugins: [] がデフォルトツールを読み込んでいた可能性があります。v4 では、空はツールゼロを意味します。 これは例外をスローしません — エージェントは呼び出せるものが何もない状態に静かになります。すべてのツールキット構築を監査してください:

// v4: pass plugins explicitly
import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';

new HederaLangchainToolkit({
  client,
  configuration: {
    plugins: allCorePlugins,           // or list specific plugins
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

v3 の「すべて」というデフォルトを維持するには、allCorePlugins を使用してください。ユーザーがより小さなツールサーフェスを望む場合は、明示的なリストを優先してください。どちらの場合もバンドラーがツリーシェイクします。

ステップ 5 — RETURN_BYTES の利用側を処理する

ResponseParserService から parsedData.raw.bytes を読み取り、それを変換するコード (例: Buffer.isBuffer(...)、Buffer.from(obj.data)) がある場合は、その変換を削除してください。v4 では raw.bytes がどこでも Uint8Array に標準化されます。これを直接 Transaction.fromBytes() に渡すことは Node でもブラウザでも動作します。references/breaking-changes.md の § "RETURN_BYTES" を参照してください。

ステップ 6 — すべてのカスタムプラグインツールを BaseTool に移行する

BaseTool は v4 におけるツールのサポートされた形式です。すべてのカスタムツールを移行する必要があります — v3 の関数型パターン (execute 関数を持つオブジェクトリテラル) はもはやサポートされた作成スタイルではなく、フック/ポリシーシステム (HcsAuditTrailHook、MaxRecipientsPolicy、RejectToolPolicy、および AbstractHook/AbstractPolicy の任意のサブクラス) をバイパスします。プラグインがエクスポートするすべてのツールを移行してください。旧スタイルと新スタイルのツールを混在させないでください。

注釈付きの before/after を含む完全なステップバイステップのレシピ: references/basetool-migration.md。

機械的な要約:

1. import type { Tool } を @hashgraph/hedera-agent-kit からの import { BaseTool } に置き換えます。
2. ファクトリを書き換えます: (context: Context): Tool => ({ ... execute }) は、BaseTool を拡張するクラスと、1 行のファクトリ (context) => new MyTool(context) になります。
3. 古い execute 関数の本体を次のように分割します:
   • normalizeParams (デフォルトの解決、形式の検証)
   • coreAction (ミューテーションの場合は Transaction を構築し、クエリの場合はデータを取得)
   • secondaryAction (ミューテーションの場合は handleTransaction(...) を呼び出し、クエリの場合はパススルー)
4. クエリ専用ツールの場合は、shouldSecondaryAction をオーバーライドして false を返し、no-op の secondaryAction を提供します。
5. try/catch の本体を handleError(error, context) のオーバーライドに移動します (BaseTool は失敗したいずれかのステージからこれを呼び出します)。
6. ファクトリの戻り値の型を BaseTool のままにします — Plugin.tools() はそれを直接受け入れます。

examples/transfer-hbar-migration/ の例は、標準的な transfer_hbar ツールに対する完全な変換を示しています。

ステップ 7 — 検証する

ファイルを変更した後、次の順序で実行します:

1. npm install (または bun install / pnpm install) — package.json が解決されることを確認します。「no version matching X」エラーに注意してください。ツールキットパッケージは ^4 ではなく ^1 です。
2. tsc --noEmit (または npm run build) — 不足しているインポートと型のずれを検出します (例: 正規化された型が宣言されていないために setTreasuryAccountId が文句を言う、または handleError / secondaryAction の override キーワードの欠落について noImplicitOverride が文句を言う)。
3. LangChain の利用者の場合、2 つの異なる @langchain/core パス (1 つはプロバイダーパッケージの下にネストされ、もう 1 つはツールキットの下にネストされている) に言及する型エラーは、デュアルパッケージの状況を示しています — プロバイダーパッケージは依然として 0.x です。ステップ 2 に従って 1.x に上げてください。
4. LangChain の利用者の場合、Cannot find module 'langchain/agents' や 'langchain/memory' のようなエラーは、レガシーな AgentExecutor/BufferMemory パターンを示しています — これらのサブパスは [email protected] で削除されました。修正は、@langchain/langgraph/prebuilt からの createReactAgent への別のフレームワーク移行です。references/breaking-changes.md の § "LangChain ecosystem bump" を参照してください。
5. エージェントをスモークテストします: ツールキットをインスタンス化し、ツールをリストし (toolkit.getTools().length は 0 より大きい必要があります)、1 つのツールをエンドツーエンドで呼び出します。ビルドが通ることは移行が成功したことを証明しません — 空のプラグイン配列の落とし穴は型安全でサイレントです。

このスキルが対象としないもの

• Solidity / システムコントラクトの移行 — system-contracts プラグインを参照してください。
• @hiero-ledger/sdk 自体の内部におけるネイティブ JS SDK の変更 — 変更されるのはインポートパスのみで、API サーフェスはリネームを通じて安定したままでした。
• ゼロからのプラグイン作成パターン — agent-kit-plugin スキルを参照してください。
• 新しいフック / ポリシーの作成 — agent-kit-hook および agent-kit-policy スキルを参照してください。BaseTool への移行は、これらの機能の前提条件です。
• LangChain フレームワークの移行(AgentExecutor → createReactAgent、BufferMemory → messages ベースの履歴)。v4 の LangChain ツールキットは [email protected] へのバージョンアップを強制し、これによりこれらの API が削除されますが、エージェントのセットアップを書き直すのは LangChain 側の関心事です。references/breaking-changes.md の「LangChain ecosystem bump」の節で変更の概要を示しています。詳細は LangChain 自身の移行ガイドを参照してください。

リファレンス索引

• references/breaking-changes.md — すべての破壊的変更、パッケージのマッピング、インストールコマンド、バージョンアップに関する注意事項。
• references/import-cheatsheet.md — 単純な検索置換表。ファイルを一括で書き換えるときにこれを読み込んでください。
• references/basetool-migration.md — あるツールを Tool オブジェクトリテラルから BaseTool サブクラスへ変換する際の注釈付きの before/after。クエリ専用のバリアントも含みます。
• examples/transfer-hbar-migration/ — 同じツールの before-v3.ts と after-v4.ts を並べて示し、すべての変更を説明する README.md を添えています。