SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场Hedera Agent Kit v4 Migration

Hedera Agent Kit v4 Migration

编程与开发

查看项目

更新于 10-15 18:22

技能介绍

用途

该技能驱动 Hedera Agent Kit 从 v3 到 v4 的完整迁移。v4 是当前主版本，v3（hedera-agent-kit@3.x）不再接收更新。当代码中导入自 hedera-agent-kit（无作用域）或 @hashgraph/sdk，或用户要求迁移到 hedera-agent-kit v4、升级 hak v3 到 v4、将插件转换为 BaseTool、迁移 Tool 时，应使用该技能。

迁移前分类

在编辑任何内容之前，需先对要迁移的文件分类，不同类别的迁移步骤不同：

  • 定义 Plugin 并导出返回带 execute 函数的对象字面量的工具工厂：属于自定义插件，应用插件迁移 + BaseTool 迁移。
  • 调用 new HederaLangchainToolkit / HederaAIToolkit / HederaElizaOSToolkit / HederaMCPToolkit：属于 toolkit 消费者，应用 toolkit 迁移。
  • 导入 coreTokenPlugin、coreAccountPlugin、coreHTSPlugin 等插件：属于 toolkit 消费者（使用内置插件），应用 toolkit 迁移 + 别名重命名。
  • 从 hedera-agent-kit 导入 ResponseParserService 或 HederaMCPServer：属于 toolkit 消费者，应用 toolkit 迁移（这些已移至 toolkit 包）。
  • 两者兼有：先运行 toolkit 迁移，再对每个工具运行插件迁移。

迁移工作流

第 1 步 — 查找所有 v3 入口点

在编辑前于项目根目录运行以下搜索：查找源码与依赖清单中的旧包名、旧 SDK 包、废弃插件别名、旧子路径导入、v3 函数式 Tool 模式（带 execute 的对象字面量）。整理出待编辑文件列表，暂不修改。

第 2 步 — 更新 package.json

替换依赖后运行安装。

移除：hedera-agent-kit、@hashgraph/sdk。仅当代码从不直接导入时，才可移除 @langchain/core、langchain、@langchain/langgraph、ai —— 它们是 toolkit 的传递依赖，使用严格解析的包管理器（bun、pnpm）时若不保留它们，将无法满足直接导入。存疑时保留为 devDeps。

新增：@hashgraph/hedera-agent-kit（使用 ^4.0.0）与 @hiero-ledger/sdk（使用 ^2.81.0），并针对你的框架添加恰好一个 toolkit 包。toolkit 包不在 ^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 等）—— toolkit 从不捆绑提供方。LangChain 消费者还必须将提供方包升级到 1.x 线（如 @langchain/openai@^1）；0.x 线依赖 @langchain/core@^0.3，会与 toolkit 的 @langchain/core@^1 产生双包类型错误。

第 3 步 — 重写导入

应用查找替换映射，关键变更：

  • 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 子路径导入。废弃别名重命名：coreHTSPlugin → coreTokenPlugin；coreSCSPlugin → coreEVMPlugin；coreQueriesPlugin → 拆分为多个独立插件（coreAccountQueryPlugin、coreTokenQueryPlugin、coreConsensusQueryPlugin、coreEVMQueryPlugin、coreMiscQueriesPlugin、coreTransactionQueryPlugin）。

toolkit 及其辅助类各自移至专门的包：HederaLangchainToolkit 与 ResponseParserService 来自 @hashgraph/hedera-agent-kit-langchain；HederaAIToolkit 来自 @hashgraph/hedera-agent-kit-ai-sdk；HederaMCPToolkit 来自 @hashgraph/hedera-agent-kit-mcp。AgentMode、Configuration、Context、Plugin、Tool、BaseTool、handleTransaction、输出解析器、mirrornode 类型仍保留在 @hashgraph/hedera-agent-kit。

第 4 步 — 修复 toolkit 配置中的静默行为变更

在 v3 中，空的 plugins: [] 可能加载默认工具；在 v4 中，空意味着零工具，且不会抛错，智能体将静默地没有可调用工具。需审查每一处 toolkit 构造。使用 allCorePlugins 可保留 v3 的“全部”默认；当用户想要更小的工具面时，优先使用显式列表。

第 5 步 — 处理 RETURN_BYTES 消费者

若有代码读取 ResponseParserService 的 parsedData.raw.bytes 并进行转换（如 Buffer.isBuffer(...)、Buffer.from(obj.data)），删除该转换。v4 将 raw.bytes 统一为 Uint8Array，可直接传给 Transaction.fromBytes()。

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

BaseTool 是 v4 中受支持的工具形态。每个自定义工具都必须迁移 —— v3 函数式模式（带 execute 函数）不再是受支持的编写风格，且会绕过 hooks/policies 系统（HcsAuditTrailHook、MaxRecipientsPolicy、RejectToolPolicy 及任何 AbstractHook/AbstractPolicy 的子类）。迁移插件导出的每个工具，不要留下新旧风格混用。

机械式总结：用 import { BaseTool } 替换 import type { Tool }；将工厂 (context: Context): Tool => ({ ... execute }) 改写为继承 BaseTool 的类与一行工厂 (context) => new MyTool(context)；将旧 execute 函数体拆分为 normalizeParams、coreAction、secondaryAction；对仅查询工具覆盖 shouldSecondaryAction 返回 false 并提供空操作 secondaryAction；将 try/catch 体移入 handleError(error, context) 覆盖；工厂返回类型保持 BaseTool。

第 7 步 — 验证

按顺序运行：npm install（或 bun install / pnpm install）确认 package.json 可解析，注意 “no version matching X” 错误（toolkit 包在 ^1 而非 ^4）；tsc --noEmit（或 npm run build）捕捉缺失导入与类型漂移。LangChain 消费者若出现提及两个不同 @langchain/core 路径的类型错误，说明提供方包仍在 0.x，按第 2 步升级到 1.x；若出现 Cannot find module 'langchain/agents' 或 'langchain/memory'，说明使用了旧版 AgentExecutor/BufferMemory 模式（这些子路径在 langchain@1.x 中已移除），需单独进行框架迁移至 @langchain/langgraph/prebuilt 的 createReactAgent。最后冒烟测试智能体：实例化 toolkit、列出工具（toolkit.getTools().length 必须 > 0）、端到端调用一个工具。构建通过不能证明迁移成功 —— 空插件数组陷阱是类型安全且静默的。

该技能不覆盖的内容

  • Solidity / 系统合约迁移 —— 见 system-contracts 插件。
  • @hiero-ledger/sdk 自身的原生 JS SDK 变更 —— 仅导入路径变化，重命名后 API 表面保持稳定。
  • 从零开始的插件编写模式 —— 见 agent-kit-plugin 技能。
  • 编写新的 hooks/policies —— 见 agent-kit-hook 与 agent-kit-policy 技能；迁移到 BaseTool 是这些功能的前提。
  • LangChain 框架迁移（AgentExecutor → createReactAgent、BufferMemory → 基于消息的历史记录）—— v4 的 LangChain toolkit 强制升级到 langchain@1.x 会移除这些 API，但重写智能体设置属于 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。