Hedera Agent Kit V4 – Policies, Modular Packages, and Plugin Updates

Announcing version 4 of the Hedera Agent Kit! The new structure of our JavaScript SDK enables users to pick and choose what they want to download and import from the Hedera Agent Kit, breaking up a large and complex package into modular options. In addition, this new release adds features that enable developers to build agent guardrails with a hook and policy system. This lets you build agents that ensure deterministic, hallucination-proof control over how agents behave when it matters most, for payments and audit trails.

Two themes define this release: modularity and control. Developers can now install only the packages they need rather than pulling in the entire monolithic code base, and they can insert their own logic at four distinct points in an agent’s execution lifecycle through a new policy and hooks system.

Updated plugins and tools

New tool implementation

The way tools are built inside the Hedera Agent Kit has been refactored in v4. Previously, a tool was a plain object literal – a set of properties and a single execute function. It worked, but it had no structure the kit could tap into. There was no way to intercept what the tool was doing, inspect parameters before they were used, or run logic after a transaction was submitted.

v4 introduces BaseTool, an abstract class that replaces the plain object pattern. Instead of one flat execute function, a tool built on BaseTool is broken into clearly named lifecycle stages that the kit can hook into automatically. You implement the stages that matter for your tool, and the kit handles everything else. See the plugin development guide for a full comparison and walkthrough.

Importantly, the v3 plain object pattern still works in v4 and won’t break existing code. But tools built that way are invisible to the hooks and policies system. If you want policies to actually govern a tool’s behavior, that tool needs to be built on BaseTool, and you can see a comparison in the docs on creating plugins in JavaScript.

Explicitly imported plugins

The v4 plugin system is fully explicit. In v3, the kit could silently load default tools even if you passed an empty plugins array. In v4, empty plugins means zero tools and your agent will have nothing to call. Every capability must be opted into intentionally. Built-in plugins have moved to the /plugins subpath. See the full list of available plugins.

import {
  coreAccountPlugin,
  coreTokenPlugin,
  coreConsensusPlugin,
  coreEVMPlugin,
  coreAccountQueryPlugin,
  coreTokenQueryPlugin,
  coreConsensusQueryPlugin,
  coreEVMQueryPlugin,
  coreMiscQueriesPlugin,
  coreTransactionQueryPlugin,
} from '@hashgraph/hedera-agent-kit/plugins';

Copy

Only pass in what your agent actually needs. An agent that only reads account balances has no business with token-minting tools.

A growing library of plugins

A growing ecosystem of third-party plugins extends the kit beyond core Hedera services. CoinCap enables easy USD/HBAR conversion. Chainlink and Pyth bring in live price feeds. Terminal 3 adds identity verification and selective disclosure for compliance-sensitive workflows. Any one of these drops straight into your plugins array alongside the built-in ones. You can experiment with the agent kit and some of the new plugins in the Hedera Agent Lab.

Hooks and policies

AI agents that interact with blockchain networks need guardrails. An agent that can freely spend HBAR, mint tokens, or submit consensus messages on your behalf is powerful, and that power needs to be bound by strict developer-defined rules. Version 4 of the Hedera Agent Kit introduces a first-class hooks and policies system that lets you do exactly that.

Lifecycle stage hooks

Every time an agent decides to call a Hedera tool, that tool invocation passes through four lifecycle stages. At each stage you can inspect state, modify behavior, or halt execution entirely.

Pre-Tool Execution: At tool execution, used for early validation or logging. This is the right place to enforce high-level policies: block certain categories of action based on the time of day, the agent’s role, or the user’s authorization level. You can choose whether or not you want your agent to be able to create accounts, mint NFTs, or transfer funds.

Post-Parameter Normalization: The agent has selected a tool and assembled its parameters, but execution hasn’t started yet. Here you can validate or rewrite the input. This stage normalizes the parameters and enables you to put limits on, for example, the HBAR amount in a transfer, or check that the recipient address for a transaction is on an allowlist before the transaction bytes are ever formed.

Post-Core Action: The tool has run and returned a result, and the transaction has been formed, waiting to be submitted on-chain. This hook lets you inspect what will be sent on-chain, and do a final check to conditionally block the result before it executes.

Post-Tool Execution: The agent has produced its final response, and the transaction has executed on-chain. This is the place to log and summarize what has happened. You can use it for spend tracking, session-level spend summaries, or triggering downstream notifications.

Together these four stages give you a complete picture of (and control over) what your agent does on Hedera. Policies are plain TypeScript objects that you compose and pass into the configuration, so they live alongside your application code and can be version-controlled, reviewed, and tested like any other business logic. Any user can create their own policies – and contribute them back – to the Hedera Agent Kit. For a full code example, see the docs.

Policies are composable – stack as many as you need and the kit runs them automatically in sequence. One for spend limits, one for address allowlists, one for audit logging.

The Agent Lab interface provides a way for you to experiment with these policies as visual controls in a no-code panel, so less technical users can set tool limits and other guardrails without touching TypeScript. But for developers building production agents, the policies are fully programmable and live entirely in your agent codebase.

Modular npm packages in a new namespace

Pick what you need, not what you don’t. Previously, version 3 shipped as a single hedera-agent-kit package. All dependencies came along for the ride whether you needed them or not, and those extra megabytes added up quickly.

Version 4 breaks the kit into a family of @hashgraph-scoped packages. The core package contains only the shared types, the plugin system, and the Hedera builder utilities. Framework integrations live in their own packages, each of which bundles only the dependencies it needs. All you need is the core package, one toolkit package, and its LLM provider, ElizaOS and MCP are only included if you want to use them.

New namespace for the SDK

Previously the JS SDK was housed under the /hashgraph Github org and npm namespace, but is now officially being maintained by Hiero, and has since moved to the Hiero open source (Github) organization & npm namespace, and needs to be imported from @hiero-ledger/sdk as opposed to @hashgraph/sdk.

One important note: @hiero-ledger/sdk is now a peer dependency across all packages. You install it once yourself at the version your project requires (>=2.80.0), and the kit doesn’t silently override it.

Install your AI framework

A typical production app needs the core package, one toolkit package, and its LLM provider. That’s it. Don’t waste time (and disk space) managing dependencies you don’t need – simply pick the set of functionality you would like to use from the Hedera Agent Kit and install those packages. You will need to install and import the LangChain, Vercel AI SDK, or Google ADK framework, and the LLM provider(s) such as Anthropic, OpenAI, Ollama, or other local agent-running framework or harness.

You can also install the preconfigured MCP server available from the Hedera Agent Kit, or, alternatively, use the ElizaOS runtime in place of using other frameworks.

MCP in two flavors. The @hashgraph/hedera-agent-kit-mcp package ships a standalone MCP server that any MCP-compatible client can connect to, including Claude Desktop, Cursor, and other AI IDEs. Run it directly with node or configure the MCP settings in your IDE or agent app.

Google’s ADK support

Hedera Agent Kit now supports Google’s Agent Development Kit (ADK), making it possible to build Hedera-powered AI agents using Google’s agent framework and Gemini models. The integration includes a plugin tool-calling agent example, along with support for the native ADK Web GUI for interactive testing and development.

The ADK example lives under examples/adk/ and can be launched either through a custom CLI runner or directly with the native ADK tooling using npx adk run agent.ts and npx adk web. Developers simply configure their Hedera credentials and Gemini API key in a local .env file, install dependencies, and start building agents that can interact with Hedera services through the Hedera Agent Kit plugin system. Documentation and setup instructions are available here: Google ADK Example Docs

A Hedera x402 facilitator

Last but certainly not least, the Hedera exact payment scheme has been accepted into x402, with a reference implementation available for anyone who would like to host their own Hedera network-compatible x402 facilitator.

The TypeScript reference implementation, built on the Hiero SDK, follows the exact payment scheme. In this implementation, a facilitator lets a client pay for an API request by transferring native HBAR or any HTS fungible token (such as USDC) to a resource server, while the third-party facilitator sponsors the network fees and broadcasts the transaction on the client’s behalf. The package ships three role-specific entry points: client, server, and facilitator, so each participant only imports what their role requires: clients get the payment-sending logic, servers get the request-verification logic, and facilitators get the fee-sponsorship and transaction-broadcasting logic.

The interesting piece is the facilitator: it accepts a partially-signed TransferTransaction from a client, runs the transaction through a strict verification pipeline, performs an optional on-chain preflight to check payer balance and token association, and only then countersigns as fee payer and submits to consensus. By awaiting a receipt from Hedera rather than just doing the pre-check, it reliably surfaces failures (insufficient balance, missing token association, bad signatures) instead of silently reporting success. The result is a drop-in Hedera “rail” that enables pay-per-request HTTP authorization, backed by HBAR or HTS tokens, with the gas-sponsorship and verification logic factored out into a reusable package.

Version 4 sets the foundation for a more capable and more controllable generation of Hedera-powered agents. We’re excited to see what you build with it – share your projects in the Hedera Discord and watch docs.hedera.com for updated guides across every supported framework.

Get involved with the Hedera AI Agent Bounty

The Hedera AI Agent Bounty is the fastest way to put everything above into practice – and earn HBAR while you do it. A new bounty drops every Monday from May 18 to June 21 – read the brief, pick the one that fits what you want to build, and ship it as a public GitHub repo using Hedera Agent Kit (JS or Python, with plugins, MCPs and other AI Studio tooling all fair game).

Submit your repo, a short demo, and the required Hedera tool feedback each week before the cut-off deadline on Sunday, with winners paid in HBAR at the end of the judging period.

Whether you want to try the new policies system, ship a third-party plugin, or stand up your own x402 facilitator, there’s a brief waiting for it. Check out this week’s bounties today!