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 的“包映射”一节，版本范围请参阅“版本管理”一节。简要说明：

• 移除：hedera-agent-kit、@hashgraph/sdk。仅当代码从未直接导入以下包时，才移除 @langchain/core、langchain、@langchain/langgraph、ai——它们是工具包的传递依赖，因此使用严格解析的包管理器（bun、pnpm）不会为直接导入提供依赖，除非你保留这些包。如不确定，请将它们保留为 devDependencies。
• 添加：@hashgraph/hedera-agent-kit（使用 ^4.0.0）和 @hiero-ledger/sdk（使用 ^2.81.0），并为所用框架添加且仅添加一个工具包包。工具包包的版本号不使用 ^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 生态系统升级”一节。

步骤 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 中，空数组表示零个工具。 这不会抛出错误——Agent 将悄无声息地没有可调用的工具。检查每处工具包实例化：

// 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 },
  },
});

使用 allCorePlugins 保留 v3 的“全部”默认行为。如果用户需要较小的工具范围，优先使用显式列表；无论哪种方式，打包工具都会进行摇树优化。

第 5 步 —— 处理 RETURN_BYTES 的使用方

如果任何代码读取 ResponseParserService 中的 parsedData.raw.bytes 并对其进行转换（例如 Buffer.isBuffer(...)、Buffer.from(obj.data)），请删除转换。v4 统一将 raw.bytes 标准化为 Uint8Array；在 Node 和浏览器中，直接传递给 Transaction.fromBytes() 均可正常工作。请参阅 references/breaking-changes.md § "RETURN_BYTES"。

第 6 步 —— 将每个自定义插件工具迁移到 BaseTool

在 v4 中，BaseTool 是受支持的工具形式。每个自定义工具都必须迁移——v3 的函数式模式（包含 execute 函数的对象字面量）不再是受支持的编写方式，而且会绕过钩子/策略系统（HcsAuditTrailHook、MaxRecipientsPolicy、RejectToolPolicy 以及 AbstractHook/AbstractPolicy 的任何子类）。迁移插件导出的每个工具；不要混用新旧两种风格的工具。

包含注释的完整分步迁移指南（迁移前/后对照）：references/basetool-migration.md。

机械迁移概要：

1. 将 import type { Tool } 替换为从 @hashgraph/hedera-agent-kit 导入 import { BaseTool }。
2. 重写工厂：将 (context: Context): Tool => ({ ... execute }) 改为一个继承 BaseTool 的类，以及一行工厂函数 (context) => new MyTool(context)。
3. 将旧 execute 函数的主体拆分到：
   • normalizeParams（解析默认值、验证格式）
   • coreAction（为变更操作构建 Transaction，为查询操作获取数据）
   • secondaryAction（为变更操作调用 handleTransaction(...)；查询操作则直接透传）
4. 对于仅查询的工具，重写 shouldSecondaryAction 并使其返回 false，同时提供一个空操作的 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" 错误；工具包依赖的版本范围是 ^1，而不是 ^4。
2. tsc --noEmit（或 npm run build）——检查缺失的导入和类型不一致问题（例如，因未声明标准化类型而导致 setTreasuryAccountId 报错，或因 handleError / secondaryAction 缺少 override 关键字而触发 noImplicitOverride 报错）。
3. 对于 LangChain 使用方，如果类型错误提到了两个不同的 @langchain/core 路径（一个嵌套在提供方包下，另一个嵌套在工具包下），则表示存在双包问题——提供方包仍使用 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. 对 Agent 进行冒烟测试：实例化工具包、列出工具（toolkit.getTools().length 必须大于 0），并端到端调用一个工具。构建通过并不能证明迁移成功——空插件数组这个陷阱在类型检查时不会报错，而且是静默的。

此技能不涵盖的内容

• 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，但重写 Agent 设置属于 LangChain 方面的问题。references/breaking-changes.md §“LangChain 生态系统升级”概述了变更的大致方向；详情请参阅 LangChain 自己的迁移指南。

参考索引

• references/breaking-changes.md — 所有破坏性变更、软件包映射、安装命令和版本升级说明。
• references/import-cheatsheet.md — 扁平的查找替换表；批量处理文件时请加载此文件。
• references/basetool-migration.md — 将一个工具从 Tool 对象字面量转换为 BaseTool 子类的注释版前后对比，其中包括仅查询变体。
• examples/transfer-hbar-migration/ — 同一工具的 before-v3.ts 和 after-v4.ts 并排对比，并附有 README.md，逐项说明所有变更。