Hedera Agent Kit V4: Policy-Based Control, Modularity, and Enhanced Plugins

⚠️ HIGH PRIORITY — Important fixes. Upgrade soon.

Version: V4 | Released: unknown | Upgrade from: V3

The Hedera Agent Kit V4 has landed, bringing a significant overhaul to how developers build and manage AI agents interacting with the Hedera network. This major release focuses on enhancing control, improving developer experience through modularity, and expanding integration capabilities. For anyone leveraging AI agents for on-chain operations, this update is critical.

Release at a Glance

Hedera Agent Kit V4 introduces fundamental shifts that empower developers with greater control and flexibility. Here’s the TL;DR:

Policy-Based AI Agent Guardrails: Implement robust control over on-chain actions with a new guardrails system, allowing granular logic injection at multiple stages of an agent’s operation.
Modular JavaScript SDK: The JavaScript SDK is now modular, enabling developers to import only the necessary packages, reducing bundle sizes and improving efficiency.
Enhanced Plugin Architecture: Official support for Google’s Agent Development Kit (ADK) and a refined plugin standard opens doors for richer integrations and extensible agent functionalities.
Breaking Changes Require Attention: Key changes include the JavaScript SDK moving to the @hashgraph scope, framework integrations becoming separate packages, and a migration from Buffer to Uint8Array for data handling.

Headline New Features

Hedera Agent Kit V4 is defined by two core themes: robust control and enhanced modularity. These features are designed to make building secure, efficient, and extensible AI agents on Hedera more straightforward and powerful.

Policy-Based AI Agent Guardrails

The most impactful new feature is the introduction of a comprehensive AI agent guardrails system. As AI agents increasingly perform real on-chain actions, having explicit control over their behavior is paramount. This system allows developers to define policies that govern an agent’s interactions, ensuring operations adhere to predefined rules and security standards.

This control is implemented through granular logic injection points, allowing developers to intervene and validate at critical stages of an agent’s workflow:

Pre-execution: Intercept and validate agent intentions or inputs before any action is initiated.
Parameter Validation: Ensure that all parameters for a proposed transaction or action meet specified criteria.
Transaction Review: Implement human-in-the-loop or automated review processes for significant on-chain transactions.
Post-execution Logging: Capture detailed logs and audit trails after an action is completed, crucial for monitoring and compliance.

🧠 Important: This policy system is a game-changer for agent security and compliance, especially for agents managing significant assets or performing critical business logic on Hedera.

Modular JavaScript SDK

The JavaScript SDK has undergone a significant architectural shift towards modularity. Previously, developers might have downloaded a monolithic package, even if they only needed a subset of its functionalities. V4 refactors the SDK into a family of distinct packages.

This new structure offers several benefits:

Reduced Bundle Sizes: Developers can now selectively download and import only the packages they require, leading to smaller application footprints and faster load times.
Improved Performance: Less code to parse and execute contributes to overall performance improvements.
Enhanced Maintainability: Individual packages can be updated and maintained more independently, streamlining development workflows.

Enhanced Plugin Architecture and Google ADK Support

V4 significantly enhances the plugin architecture, making it easier to extend the Agent Kit’s capabilities. This includes updated standards for plugin development, ensuring greater compatibility and stability across the ecosystem.

A key highlight is the official support for Google’s Agent Development Kit (ADK). This integration opens up new avenues for developers already familiar with the Google ADK ecosystem, allowing them to seamlessly leverage Hedera’s decentralized network for their AI agents. This broadens the toolkit’s reach and fosters a more diverse developer community.

Breaking Changes and Migration Path

As a major release, Hedera Agent Kit V4 introduces several breaking changes. All developers currently using V3, especially those with JavaScript SDK or custom plugins, must review and implement these changes.

⚠️ What can go wrong: Failing to address these breaking changes will result in compilation errors or runtime failures. Prioritize reviewing the official v3 -> v4 Migration Guide to ensure a smooth transition.

JavaScript SDK Package Scope Moved

The JavaScript SDK package has been moved to the @hashgraph scope. This change aligns with the broader open-source Hiero ecosystem and requires updates to your import paths.

Before (V3):

import { AgentKit } from 'hedera-agent-kit';
// or
import { SomeModule } from 'hedera-agent-kit/some-module';

After (V4):

import { AgentKit } from '@hashgraph/hedera-agent-kit';
// or
import { SomeModule } from '@hashgraph/hedera-agent-kit/some-module';

Framework Integrations are Separate Packages

Existing framework integrations (e.g., for specific web frameworks or backend systems) are no longer bundled within the core SDK. They are now separate packages, reflecting the modular approach.

Developers will need to identify and install the specific integration packages relevant to their projects. For example, if you were using an integration that was previously part of the main hedera-agent-kit package, you will now need to install @hashgraph/hedera-agent-kit-your-framework (or similar) and update your imports accordingly.

Plugins Must Be Updated

With the new modular architecture and enhanced plugin standards, existing custom plugins will need to be updated. This involves aligning with the new API surfaces and potentially refactoring their structure to fit the V4 plugin guidelines. Developers should consult the migration guide for detailed instructions on updating their plugins.

Migration from `Buffer` to `Uint8Array` in JavaScript SDK

The JavaScript SDK has migrated from using Node.js Buffer objects to standard Uint8Array for binary data handling. This change improves compatibility across different JavaScript environments (browser, Node.js, edge runtimes) and aligns with modern web standards.

Before (V3):

// Assuming 'data' is a Buffer
const hash = crypto.createHash('sha256').update(data).digest();

After (V4):

// Assuming 'data' is a Uint8Array
const hash = await crypto.subtle.digest('SHA-256', data);
// Or for Node.js environments:
// const hash = Buffer.from(crypto.createHash('sha256').update(Buffer.from(data)).digest()).toString('hex');
// Note: Direct usage of Uint8Array with Node's crypto module may require conversion.
// For Hedera SDK methods, Uint8Array should be directly accepted.

This change primarily affects how binary data is passed to and received from SDK methods. Developers should ensure their application logic correctly handles Uint8Array instances where Buffer was previously used.

How to Upgrade

Upgrading to Hedera Agent Kit V4 is a multi-step process due to the breaking changes.

Update Package Dependencies: For JavaScript/TypeScript projects using npm or yarn:

# Using npm
npm install @hashgraph/hedera-agent-kit@latest
# Or for specific packages, e.g., if you only need certain modules
npm install @hashgraph/hedera-agent-kit-core @hashgraph/hedera-agent-kit-tools@latest

# Using yarn
yarn add @hashgraph/hedera-agent-kit@latest
# Or for specific packages
yarn add @hashgraph/hedera-agent-kit-core @hashgraph/hedera-agent-kit-tools@latest

Remember to remove the old hedera-agent-kit package if you’re not using it anymore.

Review the Migration Guide: Thoroughly read the official v3 -> v4 Migration Guide for detailed instructions on adapting your codebase to the new package scopes, modular structure, plugin standards, and Buffer to Uint8Array migration.
Update Import Paths: Adjust all import or require statements to reflect the new @hashgraph scope and modular package names.
Refactor Data Handling: Modify any code that interacts with binary data to use Uint8Array instead of Buffer where the SDK expects it.
Update Plugins and Integrations: If your project uses custom plugins or framework integrations, update them to comply with the V4 architecture. This may involve installing new, separate integration packages.

Ecosystem Impact

Hedera Agent Kit V4 represents a significant leap forward for AI agent development on Hedera, with broad implications for the ecosystem.

Enhanced Trust and Security: The new policy-based guardrails directly address a critical concern for on-chain AI agents: control and auditability. This feature will foster greater trust in autonomous agents, encouraging their adoption in more sensitive and high-value use cases within DeFi, supply chain, and enterprise solutions. Developers can now confidently deploy agents knowing they have robust mechanisms to prevent unintended or malicious actions.
Improved Developer Experience and Performance: The modular JavaScript SDK will lead to lighter, faster, and more focused applications. This reduces the barrier to entry for new developers and improves the efficiency for existing ones, allowing them to build more performant agents with less overhead.
Broader Integration Opportunities: Official support for Google’s ADK is a strategic move that expands Hedera’s reach into a wider developer community. This could lead to a surge in new AI agent projects on Hedera, leveraging existing ADK tools and expertise. The enhanced plugin architecture also makes the kit more extensible, encouraging community contributions and specialized tool development.
Migration Effort: While the benefits are substantial, the breaking changes will require a dedicated migration effort for existing V3 projects. This short-term investment is crucial for long-term stability, security, and access to the new features. The clear migration guide and separate package structure aim to streamline this process, but developers should allocate sufficient time for the upgrade.

In summary, Hedera Agent Kit V4 solidifies Hedera’s position as a robust platform for intelligent, on-chain AI agents. The focus on policy-driven control and modularity empowers developers to build more secure, efficient, and integrated AI solutions, paving the way for a new generation of decentralized applications.