Skip to main content

​
Quickstart - Create a Hedera Agent

See the npm package: https://www.npmjs.com/package/hedera-agent-kit

​
1. Create your project directory

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

​
2. Install the agent kit and init the project

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 @hashgraph/sdk dotenv
Note: The Hedera Agent Kit supports both LangChain v1 (recommended) and LangChain classic (v0.3, legacy). The examples below use LangChain v1.

​
3. Install ONE of these AI provider packages

# Option 1: OpenAI (requires API key)
# for Langchain classic
npm install @langchain/openai@^0.6

# for LangChain v1
npm install @langchain/openai@^1npm install @langchain/openai@^0.6

# Option 2: Anthropic Claude (requires API key)
# for LangChain classic
npm install @langchain/anthropic@^0.3

# for LangChain v1
npm install @langchain/anthropic@^1

# Option 3: Groq (free tier available)
# for Langchain classic
npm install @langchain/groq@^0.2

# for LangChain v1
npm install @langchain/groq@^1

# Option 4: Ollama (100% free, runs locally)
# for Langchain classic
npm install @langchain/ollama@^0.2

# for LangChain v1
npm install @langchain/ollama@^1

​
4. 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)
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)

​
5. Create your agent

Once you have your project set up, create an index.js file: 
touch index.js
index.js
// 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 { ChatAnthropic } from '@langchain/anthropic';
// import { ChatGroq } from '@langchain/groq';
// import { ChatOllama } from '@langchain/ollama';
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 llm = new ChatAnthropic({
  //   model: 'claude-sonnet-4-5-20250929',
  //   apiKey: process.env.ANTHROPIC_API_KEY,
  // });

  // const llm = new ChatGroq({
  //   model: 'llama-3.3-70b-versatile',
  //   apiKey: process.env.GROQ_API_KEY,
  // });
  
  // const llm = new ChatOllama({
  //   model: 'llama3.1',
  //   baseUrl: process.env.OLLAMA_BASE_URL || 'http://127.0.0.1:11434',
  // });

  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);
Using a different AI provider? You can substitute ChatOpenAI with other LangChain chat models like ChatAnthropic, ChatGroq, or ChatOllama. Install the corresponding package (e.g., @langchain/anthropic) and update the import accordingly.

​
6. Run Your “Hello Hedera Agent Kit” Example

From the root directory, run your example agent: 
node index.js

​
Examples

Clone the repository and try out different example agents. Both LangChain v1 (recommended) and LangChain classic (v0.3) examples are available. See the full Developer Examples documentation for detailed setup instructions. Available Examples:

​
Agent Execution Modes

This tool has two execution modes with AI agents:
ModeDescription
AgentMode.AUTONOMOUSThe transaction is executed autonomously using the operator account
AgentMode.RETURN_BYTESThe transaction bytes are returned for the user to sign and execute

​
Resources