Skip to content

hashgraph/hedera-agent-kit

BranchesTags

Repository files navigation

Hedera Agent Kit

npm version license build

Build Hedera-powered AI agents in under a minute.

📋 Contents

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

🆓 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

This command initializes a CommonJS project by default.

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

Then install ONE of these AI provider packages:

# Option 1: OpenAI (requires API key)
npm install @langchain/openai

# Option 2: Anthropic Claude (requires API key)
npm install @langchain/anthropic

# Option 3: Groq (free tier available)
npm install @langchain/groq

# Option 4: Ollama (100% free, runs locally)
npm install @langchain/ollama

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)
HEDERA_ACCOUNT_ID="0.0.xxxxx"
HEDERA_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 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
const dotenv = require('dotenv');
dotenv.config();

const { ChatPromptTemplate } = require('@langchain/core/prompts');
const { AgentExecutor, createToolCallingAgent } = require('langchain/agents');
const { Client, PrivateKey } = require('@hashgraph/sdk');
const { HederaLangchainToolkit, coreQueriesPlugin } = require('hedera-agent-kit');

// Choose your AI provider (install the one you want to use)
function createLLM() {
  // Option 1: OpenAI (requires OPENAI_API_KEY in .env)
  if (process.env.OPENAI_API_KEY) {
    const { ChatOpenAI } = require('@langchain/openai');
    return new ChatOpenAI({ model: 'gpt-4o-mini' });
  }
  
  // Option 2: Anthropic Claude (requires ANTHROPIC_API_KEY in .env)
  if (process.env.ANTHROPIC_API_KEY) {
    const { ChatAnthropic } = require('@langchain/anthropic');
    return new ChatAnthropic({ model: 'claude-3-haiku-20240307' });
  }
  
  // Option 3: Groq (requires GROQ_API_KEY in .env)
  if (process.env.GROQ_API_KEY) {
    const { ChatGroq } = require('@langchain/groq');
    return new ChatGroq({ model: 'llama3-8b-8192' });
  }
  
  // Option 4: Ollama (free, local - requires Ollama installed and running)
  try {
    const { ChatOllama } = require('@langchain/ollama');
    return new ChatOllama({ 
      model: 'llama3.2',
      baseUrl: 'http://localhost:11434'
    });
  } catch (e) {
    console.error('No AI provider configured. Please either:');
    console.error('1. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GROQ_API_KEY in .env');
    console.error('2. Install and run Ollama locally (https://ollama.com)');
    process.exit(1);
  }
}

async function main() {
  // Initialize AI model
  const llm = createLLM();

  // Hedera client setup (Testnet by default)
  const client = Client.forTestnet().setOperator(
    process.env.HEDERA_ACCOUNT_ID,
    PrivateKey.fromStringECDSA(process.env.HEDERA_PRIVATE_KEY),
  );

  const hederaAgentToolkit = new HederaLangchainToolkit({
    client,
    configuration: {
      plugins: [coreQueriesPlugin] // all our core plugins here https://github.com/hedera-dev/hedera-agent-kit/tree/main/typescript/src/plugins
    },
  });
  
  // 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

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
  1. Then, run the example
npm run langchain:tool-calling-agent
  1. 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
  1. 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
  1. 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
  1. 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..."
  1. Build and Run the MCP Server. From the modelcontextprotocol directory, install dependencies and build:
npm install
npm run build
  1. 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
  1. 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.

  1. 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...."
        }
      }
  }
}

7 - Option E: Try out the Hedera Agent Kit with ElizaOS

ElizaOS is a powerful framework for building autonomous AI agents. The Hedera plugin for ElizaOS enables seamless integration with Hedera's blockchain services, allowing you to create sophisticated AI agents that can interact with the Hedera network.

⚠️ Development Status: The ElizaOS plugin is currently in active development. Features and APIs may change as the plugin evolves.

  1. Clone the Hedera ElizaOS Plugin Repository
  2. Install ElizaOS CLI
  3. Follow the Hedera ElizaOS Plugin Docs

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 Plugins & Tools

The Hedera Agent Kit provides a set of tools, bundled into plugins, to interact with the Hedera network.

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

To request more functionality in the toolkit for:

Please open an issue.

See a more thorough description and how to implement the plugins in docs/HEDERAPLUGINS.md

Third Party Plugins

Coming Soon

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.

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

35 stars

Watchers

3 watching

Forks

33 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 15

Languages