Hedera AI Agent Kit

Features and Functionality in the Hedera Agent Kit SDK at https://github.com/hashgraph/hedera-agent-kit

Overview

Build LLM-powered applications that interact with the Hedera Network. Create conversational agents that can understand user requests in natural language and execute Hedera transactions, or build backend systems that leverage AI for on-chain operations.

The Hedera Agent Kit provides:

Conversational AI: LangChain-based agents that understand natural language
Adaptors for Framework Tools: Pre-built tools covering Hedera services (and third party plugins), automatically adapted into popular frameworks like LangChain, Vercel ai-sdk, and MCP
Flexible Transaction Handling: Direct execution or provide transaction bytes for user signing
Autonomous and Human-in-the-Loop mode for executing transactions on Hedera
A Plugin Architecture - For using both Hedera network capabilities and services, as well as third-party features and functionality

Quick Start - Create a Hedera Agent

See the npm package for the Hedera Agent Kit can be found at: https://www.npmjs.com/package/hedera-agent-kit

Create your project directory

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

Install the agent kit, and init the project

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

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

Add Environment Variables

Create a .env file in your directory

touch .env

If you don't already have a Hedera account, create a testnet account 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)

Once you have your project set up, create an index.js file:

touch index.js

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

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

Examples

See and try out the example NextJS Application built using the latest version of the AI Agent Kit to see

Clone and try out different examples in the toolkit:

The example tool calling agent can carry out simple tasks with Hedera tools in 'autonomous mode'
The structured chat agent can string together and complete more complex tasks, autonomously on Hedera
The human in the loop agent shows you how you can create a more controlled workflow
Try out the MCP server to enable interaction with Hedera in your favorite application such as Claude Desktop or an IDE like Cursor.

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

Agent Kit Plugins

The Hedera Agent Kit provides a basic set of tools in the form of Plugins, which group together sets of functionality and can easily be included in your instance of hederaAgentToolkit

Need additional capabilities with the agent kit, that isn't currently included? Please open an issue.

Available Plugins

Core Account Plugin: Tools for Hedera Account Service operations
Core Consensus Plugin: Tools for Hedera Consensus Service (HCS) operations
Core HTS Plugin: Tools for Hedera Token Service operations
Core Queries Plugin: Tools for querying Hedera network data

See the available plugins, the included tools, examples, and instructions on how to use a in the Github docs: PLUGINS.md

Requests and Contributions

To request additional functionality, please open an issue. To contribute to the Hedera Agent Kit see the Contributing Guidelines To create your own plugin, see the instructions in PLUGINS.md To officially register your plugin, follow the instructions here

Resources

GitHub: https://github.com/hashgraph/hedera-agent-kit
npm: hedera-agent-kit
Issues: https://github.com/hedera-dev/hedera-agent-kit/issues

PreviousAI Studio on Hedera NextPlugins

Last updated 15 days ago

Was this helpful?