Build Hedera-powered AI agents in under a minute.
Upgrading from v3? See the v3 → v4 Migration Guide for all breaking changes.
- Key Features
- About the Agent Kit Functionality
- Third Party Plugins
- Hooks and Policies
- Developer Examples
- 🚀 60-Second Quick-Start
- Agent Execution Modes
- Hedera Plugins & Tools
- Creating Plugins & Contributing
- License
- Credits
The Hedera Agent Kit is an open-source toolkit that brings intelligent agent workflows to the Hedera network. It’s designed for developers who want to integrate Hedera account management and Hedera native functionality into agent applications. With the Hedera Agent Kit, developers can build agents that interact on-chain through a conversational interface. This means Hedera agents can do more than process information; they can also send tokens, manage accounts, store data on Hedera Consensus Service, and coordinate workflows directly on a public ledger.
As of v4, the Hedera Agent Kit is organized as a monorepo of @hashgraph-scoped packages. You install the core package plus only the toolkit for your framework (LangChain, Vercel AI SDK, ElizaOS, or MCP). See the v3 → v4 Migration Guide for details.
The Hedera Agent Kit is extensible with third party plugins by other projects.
The list of currently available Hedera plugins and functionality can be found in the Plugins & Tools section of this page
👉 See docs/HEDERAPLUGINS.md for the full catalogue & usage examples for Hedera Tools.
Want to add more functionality from Hedera Services? Open an issue!
The Hedera Agent Kit is extensible with third-party plugins developed by other projects. See how you can build and submit your own plugin to be listed as a Hedera Agent Kit plugin in Hedera Docs and in docs/PLUGINS.md.
The Hedera Agent Kit provides a flexible and powerful system for putting limits on tool usage and enforcing business logic, effectively enabling you to limit the functionality of AI agents through Hooks and Policies. These hooks and policies can be used to enforce security, compliance, and other business rules.
Features
- Hooks and policies can be called when parameters are passed, after parameter normalization, before tool execution when a transaction has been formed, and after tool execution when a transaction has been signed and submitted.
- Users can create their own hooks and policies on any available Hedera Agent Kit tool, simply fork this repo and create your own hooks and policies in the
typescript/src/hooksandtypescript/src/policiesdirectories. - We have provided examples:
- A hook to log actions to an HCS topic, creating an easy to track audit trail.
- A policy that sets the maximum number of recipients in a transfer or airdrop.
- A policy the blocks tool usage by an agent.
For more information on hooks and policies, see the Hooks and Policies documentation.
Try out an example Audit Hook Agent to see how hooks and policies work in practice.
You can try out examples of the different types of agents you can build by followin the instructions in the Developer Examples doc in this repo.
First follow instructions in the Developer Examples to clone and configure the example, then choose from one of the examples to run:
- Option A - Example Tool Calling Agent
- Option B - Example Structured Chat Agent
- Option C - Example Return Bytes Agent
- Option D - Example MCP Server
- Option E - Example ElizaOS Agent
- Option F - Example Preconfigured MCP Client Agent
- Option G - Example Google ADK Agent
See more info at https://www.npmjs.com/package/@hashgraph/hedera-agent-kit
- Ollama: 100% free, runs on your computer, no API key needed
- Groq: Offers generous free tier with API key
- Claude & OpenAI: Paid options for production use
Create a directory for your project and install dependencies:
mkdir hello-hedera-agent-kit
cd hello-hedera-agent-kitInit and install with npm
npm init -yOpen package.json and add "type": "module" to enable ES modules.
Install the core package, LangChain toolkit, your LLM provider, and the Hedera SDK:
npm install @hiero-ledger/sdk @hashgraph/hedera-agent-kit @hashgraph/hedera-agent-kit-langchain @langchain/openai dotenvUsing a different LLM? Replace
@langchain/openaiwith@langchain/anthropic,@langchain/groq, or@langchain/ollama.
Create an .env file in the root directory of your project:
touch .envIf you already have a testnet account, you can use it. Otherwise, you can create a new one at https://portal.hedera.com/dashboard
Add the following to the .env file:
# Required: Hedera credentials (get free testnet account at https://portal.hedera.com/dashboard)
ACCOUNT_ID="0.0.xxxxx"
PRIVATE_KEY="0x..." # ECDSA encoded private key
# Optional: Add the API key for your chosen AI provider
OPENAI_API_KEY="sk-proj-..." # For OpenAI (https://platform.openai.com/api-keys)
ANTHROPIC_API_KEY="sk-ant-..." # For Claude (https://console.anthropic.com)
GROQ_API_KEY="gsk_..." # For Groq free tier (https://console.groq.com/keys)
# Ollama doesn't need an API key (runs locally)Create a new file called index.ts in the hello-hedera-agent-kit folder.
touch index.tsOnce you have created the file and added the environment variables, you can run the following code:
// index.ts
import { Client, PrivateKey } from '@hiero-ledger/sdk';
import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';
import { HederaLangchainToolkit } from '@hashgraph/hedera-agent-kit-langchain';
import { ChatOpenAI } from '@langchain/openai';
import { createAgent } from 'langchain';
import * as dotenv from 'dotenv';
dotenv.config();
async function main() {
// Hedera client setup (Testnet by default)
const client = Client.forTestnet().setOperator(
process.env.ACCOUNT_ID!,
PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY!)
);
// Prepare Hedera toolkit with explicit plugin selection
const toolkit = new HederaLangchainToolkit({
client,
configuration: {
plugins: allCorePlugins,
context: { mode: AgentMode.AUTONOMOUS },
},
});
const agent = createAgent({
model: new ChatOpenAI({ model: 'gpt-4o-mini' }),
tools: toolkit.getTools(),
systemPrompt: 'You are a helpful assistant with access to Hedera blockchain tools',
});
const response = await agent.invoke({
messages: [{ role: 'user', content: "What's my HBAR balance?" }],
});
const lastMessage = response.messages[response.messages.length - 1];
console.log(lastMessage.content);
}
main().catch(console.error);From the root directory, run your example agent:
npx tsx index.tsTo see more examples, check out the examples/ directory in this repo.
This tool has two execution modes with AI agents; autonomous execution and return bytes. If you set:
mode: AgentMode.RETURN_BYTEthe transaction will be executed, and the bytes to execute the Hedera transaction will be returned.mode: AgentMode.AUTONOMOUSthe transaction will be executed autonomously, using the accountID set (the operator account can be set in the client with.setOperator(process.env.ACCOUNT_ID!)
The Hedera Agent Kit provides a set of tools, bundled into plugins, to interact with the Hedera network. See how to build your own plugins in docs/HEDERAPLUGINS.md
Currently, the following plugins are available:
- Transfer HBAR
- Create a Topic
- Submit a message to a Topic
- Create a Fungible Token
- Create a Non-Fungible Token
- Airdrop Fungible Tokens
- Account queries (balances, info)
- Token queries (info, airdrops)
- Consensus queries (topic info, messages)
- EVM queries (contract info)
- Misc queries (exchange rates)
- Transaction queries (transaction records)
See more in docs/PLUGINS.md
-
You can find a guide for creating plugins in docs/PLUGINS.md
-
This guide also has instructions for publishing and registering your plugin to help our community find and use it.
-
If you would like to contribute and suggest improvements for the cord SDK and MCP server, see CONTRIBUTING.md for details on how to contribute to the Hedera Agent Kit.
Apache 2.0
Special thanks to the developers of the Stripe Agent Toolkit who provided the inspiration for the architecture and patterns used in this project.