Hedera Agent Kit

Build Hedera-powered AI agents in under a minute.

📋 Contents

• Key Features
• About the Agent Kit Tools
• 🚀 60-Second Quick-Start
• 📦 Clone & Test the SDK Examples
• Agent Execution Modes
• Hedera Transaction Tools
• Hedera Mirror Node Query Tools
• Creating Tools
• 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.

---

About the Agent Kit Tools

The list of currently available tools can be found in the Tools section of this page

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

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

---

🚀 60-Second Quick-Start

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

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

npm install hedera-agent-kit @langchain/openai @langchain/core langchain @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:

ACCOUNT_ID="0.0.xxxxx" # your operator account ID from https://portal.hedera.com/dashboard
PRIVATE_KEY="0x..." # ECDSA encoded private key
OPENAI_API_KEY="sk-proj-..." # Create an OpenAPI Key at https://platform.openai.com/api-keys

3 – Simple "Hello Hedera Agent Kit" Example

Create a 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 dotenv from 'dotenv';
dotenv.config();

import { ChatOpenAI } from '@langchain/openai';
import { ChatPromptTemplate } from '@langchain/core/prompts';
import { AgentExecutor, createToolCallingAgent } from 'langchain/agents';
import { Client, PrivateKey } from '@hashgraph/sdk';
import { HederaLangchainToolkit } from 'hedera-agent-kit';


async function main() {
  // Initialise OpenAI LLM
  const llm = new ChatOpenAI({
    model: 'gpt-4o-mini',
  });

  // Hedera client setup (Testnet by default)
  const client = Client.forTestnet().setOperator(
    process.env.ACCOUNT_ID,
    PrivateKey.fromStringDer(process.env.PRIVATE_KEY),
  ); // get these from https://portal.hedera.com

  const hederaAgentToolkit = new HederaLangchainToolkit({
    client,
    configuration: {
      tools: [] // use an empty array if you want to load all tools
    },
  });
  
  // Load the structured chat prompt template
  const prompt = ChatPromptTemplate.fromMessages([
    ['system', 'You are a helpful assistant'],
    ['placeholder', '{chat_history}'],
    ['human', '{input}'],
    ['placeholder', '{agent_scratchpad}'],
  ]);

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

  // Create the underlying agent
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
  
  // Wrap everything in an executor that will maintain memory
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
  });
  
  const response = await agentExecutor.invoke({ input: "what's my balance?" });
  console.log(response);
}

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 agentExecutor.invoke({ input: "what's my balance?" });
// or
  const response = await agentExecutor.invoke({ input: "create a new token called 'TestToken' with symbol 'TEST'" });
// or
  const response = await agentExecutor.invoke({ input: "transfer 5 HBAR to account 0.0.1234" });
// or
  const response = await agentExecutor.invoke({ input: "create a new topic for project updates" });
...
   console.log(response);

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

---

📦 Clone & Test the SDK Examples

1 – Install

git clone https://github.com/hedera-dev/hedera-agent-kit.git 

Requirements

• Node.js v20 or higher

Repo Dependencies

• Hedera Hashgraph SDK and API
• Langchain Tools
• zod
• dotenv

2 – Configure: Add Environment Variables

For Agent Examples

Copy typescript/examples/langchain/.env.example to typescript/examples/langchain/.env:

cd typescript/examples/langchain
cp .env.example .env

Add in your Hedera API and OPENAPI Keys

ACCOUNT_ID= 0.0.xxxxx
PRIVATE_KEY= 302e...
OPENAI_API_KEY= sk-proj-...

3 – Option A: Run the Example Tool Calling Agent

With the tool-calling-agent (found at typescript/examples/langchain/tool-calling-agent.ts), you can experiment with and call the available tools in the Hedera Agent Kit for the operator account (the account you are using in the .env file). This example tool-calling-agent uses GPT 4-o-mini that is a simple template you can use with other LLMs. This agent is intended for use with simple tasks, such as an invididual tool call.

1. First, go into the directory where the example is and run npm install

cd typescript/examples/langchain
npm install

2. Then, run the example

npm run langchain:tool-calling-agent

3. interact with the agent. First, tell the agent who you are (your name) and try out some of the interactions by asking questions:

• What can you help me do with Hedera?
• What's my current HBAR balance?
• Create a new topic called 'Daily Updates
• Submit the message 'Hello World' to topic 0.0.12345
• Create a fungible token called 'MyToken' with symbol 'MTK'
• Check my balance and then create a topic for announcements
• Create a token with 1000 initial supply and then submit a message about it to topic 0.0.67890

4 – Option B: Run the Structured Chat Agent

The structured chat agent enables you to interact with the Hedera blockchain in the same way as the tool calling agent, using GPT-4.1 as the LLM. You can use tools in autonomous mode using pre-built prompts from the LangChain Hub.

1. First, go into the directory where the example is and run npm install

cd typescript/examples/langchain
npm install

2. Then, run the example

npm run langchain:structured-chat-agent

5 - Option C: Try the Human in the Loop Chat Agent

The Human in the Loop Chat Agent enables you to interact with the Hedera blockchain in the same way as the tool calling agent, using GPT-4.1 as the LLM, except uses the RETURN_BYTES execution mode, instead of AgentMode.AUTONOMOUS.

This agent will create the transaction requested in natural language, and return the bytes the user to execute the transaction in another tool.

1. First, go into the directory where the example is and run npm install

cd typescript/examples/langchain
npm install

2. Then, run the 'human in the loop' or 'return bytes' example:

npm run langchain:return-bytes-tool-calling-agent

The agent will start a CLI chatbot that you can interact with. You can make requests in natural language, and this demo will demonstrate an app with a workflow that requires a human in the loop to approve actions and execute transactions.

You can modify the typescript/examples/langchain/return-bytes-tool-calling-agent.ts file to add define the available tools you would like to use with this agent:

const {
    CREATE_FUNGIBLE_TOKEN_TOOL,
    CREATE_TOPIC_TOOL,
    SUBMIT_TOPIC_MESSAGE_TOOL,
    GET_HBAR_BALANCE_QUERY_TOOL,
    TRANSFER_HBAR_TOOL,
    // CREATE_NON_FUNGIBLE_TOKEN_TOOL,
    // AIRDROP_FUNGIBLE_TOKEN_TOOL,
    // GET_ACCOUNT_QUERY_TOOL,
    // GET_ACCOUNT_TOKEN_BALANCES_QUERY_TOOL,
    // GET_TOPIC_MESSAGES_QUERY_TOOL,
  } = hederaTools;

And then add the tools to the toolkit:

const hederaAgentToolkit = new HederaLangchainToolkit({
    client: agentClient,
    configuration: {
      tools: [
        CREATE_TOPIC_TOOL,
        SUBMIT_TOPIC_MESSAGE_TOOL,
        CREATE_FUNGIBLE_TOKEN_TOOL,
        GET_HBAR_BALANCE_QUERY_TOOL,
        TRANSFER_HBAR_TOOL, 
      ], // use an empty array if you wantto load all tools
      context: {
        mode: AgentMode.RETURN_BYTES,
        accountId: operatorAccountId,
      },
    },
  });

6 - Option D: Try Out the MCP Server

1. First, navigate into the folder for the agent kit mcp server.

cd modelcontextprotocol

2. Export two environment variables, one for your Hedera testnet account, and one for your DER-encoded private key. You can also create an .env file in the modelcontextprotocol directory to store these variables.

export HEDERA_OPERATOR_ID="0.0.xxxxx"
export HEDERA_OPERATOR_KEY="0x2g3..."

2. Build and Run the MCP Server. From the modelcontextprotocol directory, install dependencies and build:

npm install
npm run build

3. Run and test the MCP server. The server accepts these command-line options:

• --ledger-id=testnet|mainnet (defaults to testnet)s
• --agent-mode, and --account-id for additional configuration

4. Run the server to verify it works:

node dist/index.js

Optional: Test out Claude Desktop or an IDE to operate the Hedera MCP server.

5. Create/edit Claude Desktop or your IDE MCP config file:

{
"mcpServers": {
  "hedera-mcp-server": {
        "command": "node",
        "args": [
          "<Path>/hedera-agent-kit/modelcontextprotocol/dist/index.js"
        ],
        "env": {
          "HEDERA_OPERATOR_ID": "0.0.xxxx",
          "HEDERA_OPERATOR_KEY": "302e...."
        }
      }
  }
}

---

About the Agent Kit

Agent Execution Modes

This tool has two execution modes with AI agents; autonomous excution 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 Transaction Tools

The Hedera Agent Kit provides a set of tools to execute transactions on the Hedera network, which we will be expanding in the future.

To request more functionality in the toolkit for:

• Token Service
• Consensus Service
• Smart Contract Servce

Please open an issue.

Available Tools

• Transfer HBAR
• Create a Topic
• Submit a message to a Topic
• Create a Fungible Token
• Create a Non-Fungible Token
• Airdrop Fungible Tokens
• Transfer Fungible Tokens

See the implementation details in docs/TOOLS.md

Hedera Mirror Node Query Tools

The Hedera network is made up of two types of nodes: consensus nodes and mirror nodes. Mirror nodes are free to query, and maintain a copy of the state of the network for users to query.

This toolkit provides a set of tools to query the state of the network, including accounts, tokens, and transactions. To request more functionality, please open an issue.

The Hedera Agent Kit provides a set of tools to execute query these nodes:

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

See the implementation details in docs/TOOLS.md

---

Creating Tools

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.