Hedera Agent Kit

Build Hedera-powered AI agents in under a minute.

📋 Contents

• Key Features
• About the Agent Kit Functionality
• Third Party Plugins
• Developer Examples
• 🚀 60-Second Quick-Start
• Agent Execution Modes
• Hedera Plugins & Tools
• Creating Plugins & Contributing
• License
• Credits

---

Key Features

This version of the Hedera Agent Kit, known as v3, is a complete rewrite of the original version. It is designed to be more flexible and easier to use, with a focus on developer experience. It enables direct API execution through a simple HederaAgentAPI class, with an individual LangChain tools call for each example.

The Hedera Agent Kit is extensible with third party plugins by other projects.

---

Agent Kit Functionality

The list of currently available Hedera plugins and functionality can be found in the Plugins & Tools section of this page

👉 See docs/PLUGINS.md for the full catalogue & usage examples.

Want to add more functionality from Hedera Services? Open an issue!

---

Third Party Plugins

• Memejob Plugin provides a streamlined interface to the memejob protocol, exposing the core actions (create, buy, sell) for interacting with meme tokens on Hedera:

  Github repository: https://github.com/buidler-labs/hak-memejob-plugin

• Bonzo Plugin is a unified SDK to the Bonzo protocol, exposing the core actions (deposit, withdraw, repay, borrow) for decentralised lending and borrowing on Hedera:

  Github repository: https://github.com/Bonzo-Labs/bonzoPlugin

---

Developer Examples

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

---

🚀 60-Second Quick-Start

See more info at https://www.npmjs.com/package/hedera-agent-kit

🆓 Free AI Options Available!

• 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

1 – Project Setup

Create a directory for your project and install dependencies:

mkdir hello-hedera-agent-kit
cd hello-hedera-agent-kit

Init and install with npm

npm init -y

Open package.json and add "type": "module" to enable ES modules.

npm install hedera-agent-kit @langchain/core langchain @langchain/langgraph @langchain/openai @hashgraph/sdk dotenv

2 – Configure: Add Environment Variables

Create an .env file in the root directory of your project:

touch .env

If 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)

3 – Simple "Hello Hedera Agent Kit" Example

Create a new file called index.js in the hello-hedera-agent-kit folder.

touch index.js

Once you have created a new file index.js and added the environment variables, you can run the following code:

// index.js
import { Client, PrivateKey } from '@hashgraph/sdk';
import { HederaLangchainToolkit, AgentMode } from 'hedera-agent-kit';
import { createAgent } from 'langchain';
import { MemorySaver } from '@langchain/langgraph';
import { ChatOpenAI } from '@langchain/openai';
import 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
  const hederaAgentToolkit = new HederaLangchainToolkit({
    client,
    configuration: {
      tools: [], // Add specific tools here if needed, or leave empty for defaults/plugins
      plugins: [], // Add plugins here
      context: {
        mode: AgentMode.AUTONOMOUS,
      },
    },
  });

  // Fetch tools from a toolkit
  const tools = hederaAgentToolkit.getTools();

  const llm = new ChatOpenAI({
    model: 'gpt-4o-mini',
    apiKey: process.env.OPENAI_API_KEY,
  });

  const agent = createAgent({
    model: llm,
    tools: tools,
    systemPrompt: 'You are a helpful assistant with access to Hedera blockchain tools',
    checkpointer: new MemorySaver(),
  });

  console.log('Sending a message to the agent...');
  
  const response = await agent.invoke(
    { messages: [{ role: 'user', content: "what's my balance?" }] },
    { configurable: { thread_id: '1' } }
  );

  console.log(response.messages[response.messages.length - 1].content);
}

main().catch(console.error);

4 – Run Your "Hello Hedera Agent Kit" Example

From the root directory, run your example agent, and prompt it to give your hbar balance:

node index.js

If you would like, try adding in other prompts to the agent to see what it can do.

// ...
//original
  const response = await agent.invoke(
    { messages: [{ role: 'user', content: "what's my balance?" }] },
    { configurable: { thread_id: '1' } }
  );
// or
  const response = await agent.invoke(
    { messages: [{ role: 'user', content: "create a new token called 'TestToken' with symbol 'TEST'" }] },
    { configurable: { thread_id: '1' } }
  );
// or
  const response = await agent.invoke(
    { messages: [{ role: 'user', content: "transfer 5 HBAR to account 0.0.1234" }] },
    { configurable: { thread_id: '1' } }
  );
// or
  const response = await agent.invoke(
    { messages: [{ role: 'user', content: "create a new topic for project updates" }] },
    { configurable: { thread_id: '1' } }
  );
// ...
   console.log(response.messages[response.messages.length - 1].content);

To get other Hedera Agent Kit tools working, take a look at the example agent implementations at https://github.com/hedera-dev/hedera-agent-kit/tree/main/typescript/examples/langchain

---

About the Agent Kit

Agent Execution Modes

This tool has two execution modes with AI agents; autonomous execution and return bytes. If you set:

• mode: AgentMode.RETURN_BYTE the transaction will be executed, and the bytes to execute the Hedera transaction will be returned.
• mode: AgentMode.AUTONOMOUS the transaction will be executed autonomously, using the accountID set (the operator account can be set in the client with .setOperator(process.env.ACCOUNT_ID!)

Hedera Plugins & Tools

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:

Available Plugins & Tools

Core Account Plugin: Tools for Hedera Account Service operations

• Transfer HBAR

Core Consensus Plugin: Tools for Hedera Consensus Service (HCS) operations

• Create a Topic
• Submit a message to a Topic

Core HTS Plugin: Tools for Hedera Token Service operations

• Create a Fungible Token
• Create a Non-Fungible Token
• Airdrop Fungible Tokens

Core Queries Plugin: Tools for querying Hedera network data

• Get Account Query
• Get HBAR Balance Query
• Get Account Token Balances Query
• Get Topic Messages Query

See more in docs/PLUGINS.md

---

Creating Plugins & Contributing

• 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.

License

Apache 2.0

Credits

Special thanks to the developers of the Stripe Agent Toolkit who provided the inspiration for the architecture and patterns used in this project.