Skip to main content
This guide walks you through scaffolding a minimal Node.js project that uses the Hedera Agent Kit to run an AI agent against the Hedera Testnet. Pick your framework (LangChain, Vercel AI SDK, or Google ADK), install the packages, configure credentials, and run a single-shot “what’s my balance?” call.

​
Prerequisites

​
1. Create your project directory

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

​
2. Install the agent kit and init the project

npm init -y
Open package.json and add "type": "module" to enable ES modules. Install the core package plus your chosen framework toolkit: 
npm install @hiero-ledger/sdk \
  @hashgraph/hedera-agent-kit \
  @hashgraph/hedera-agent-kit-langchain \
  @langchain/openai \
  dotenv

npm install @hiero-ledger/sdk \
  @hashgraph/hedera-agent-kit \
  @hashgraph/hedera-agent-kit-ai-sdk \
  @ai-sdk/openai \
  dotenv

npm install @hiero-ledger/sdk \
  @hashgraph/hedera-agent-kit \
  @hashgraph/hedera-agent-kit-adk \
  @google/adk \
  dotenv

​
3. Add environment variables

Create a .env file in your project directory: 
touch .env
Add your credentials. Use OPENAI_API_KEY for the LangChain / Vercel AI SDK examples, or GOOGLE_API_KEY for the Google ADK example: You can get a Hedera Testnet account on portal.hedera.com. 
ACCOUNT_ID="0.0.xxxxx"
PRIVATE_KEY="0x..."      # ECDSA private key
OPENAI_API_KEY="sk-proj-..."
GOOGLE_API_KEY="..."
ANTHROPIC_API_KEY="..."

​
4. Create your agent

Create an index.js file: 
touch index.js

// index.js
import { Client, PrivateKey } from '@hiero-ledger/sdk';
import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';
import { HederaLangchainToolkit } from '@hashgraph/hedera-agent-kit-langchain';
import { createAgent } from 'langchain';
import { ChatOpenAI } from '@langchain/openai';
import 'dotenv/config';

const client = Client.forTestnet().setOperator(
  process.env.ACCOUNT_ID,
  PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY),
  // PrivateKey.fromStringED25519(process.env.PRIVATE_KEY), // use this instead for ED25519 keys
);

const toolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    tools: [],
    plugins: allCorePlugins,
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

const agent = createAgent({
  model: new ChatOpenAI({ model: 'gpt-4o-mini' }),
  tools: toolkit.getTools(),
  systemPrompt: 'You are a helpful assistant with access to Hedera blockchain tools.',
});

const response = await agent.invoke({
  messages: [{ role: 'user', content: "what's my balance?" }],
});

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

// index.js
import { Client, PrivateKey } from '@hiero-ledger/sdk';
import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';
import { HederaAIToolkit } from '@hashgraph/hedera-agent-kit-ai-sdk';
import { openai } from '@ai-sdk/openai';
import { generateText, stepCountIs, wrapLanguageModel } from 'ai';
import 'dotenv/config';

const client = Client.forTestnet().setOperator(
  process.env.ACCOUNT_ID,
  PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY),
  // PrivateKey.fromStringED25519(process.env.PRIVATE_KEY), // use this instead for ED25519 keys
);

const toolkit = new HederaAIToolkit({
  client,
  configuration: {
    tools: [],
    plugins: allCorePlugins,
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

const model = wrapLanguageModel({
  model: openai('gpt-4o'),
  middleware: toolkit.middleware(),
});

const response = await generateText({
  model,
  messages: [{ role: 'user', content: "what's my balance?" }],
  tools: toolkit.getTools(),
  stopWhen: stepCountIs(2),
});

console.log(response.text);

// index.js
import { Client, PrivateKey } from '@hiero-ledger/sdk';
import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';
import { HederaADKToolkit } from '@hashgraph/hedera-agent-kit-adk';
import { LlmAgent, Runner, InMemorySessionService, isFinalResponse } from '@google/adk';
import 'dotenv/config';

const client = Client.forTestnet().setOperator(
  process.env.ACCOUNT_ID,
  PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY),
  // PrivateKey.fromStringED25519(process.env.PRIVATE_KEY), // use this instead for ED25519 keys
);

const toolkit = new HederaADKToolkit({
  client,
  configuration: {
    tools: [],
    plugins: allCorePlugins,
    context: {
      mode: AgentMode.AUTONOMOUS,
      accountId: process.env.ACCOUNT_ID,
    },
  },
});

const agent = new LlmAgent({
  name: 'hedera_agent',
  description: 'An AI agent that can interact with the Hedera blockchain.',
  model: 'gemini-3.1-flash-lite-preview',
  instruction: 'You are a helpful assistant with access to Hedera blockchain tools.',
  tools: toolkit.getTools(),
});

const APP_NAME = 'hedera_agent_app';
const USER_ID = 'hedera_user';
const SESSION_ID = 'session_1';

const sessionService = new InMemorySessionService();
await sessionService.createSession({ appName: APP_NAME, sessionId: SESSION_ID, userId: USER_ID });

const runner = new Runner({ appName: APP_NAME, agent, sessionService });

const events = runner.runAsync({
  userId: USER_ID,
  sessionId: SESSION_ID,
  newMessage: { role: 'user', parts: [{ text: "what's my balance?" }] },
});

for await (const event of events) {
  if (isFinalResponse(event)) {
    const text = event.content?.parts?.map((p) => p.text).filter(Boolean).join(' ');
    if (text) console.log(text);
  }
}

​
5. Run your example

From the project root: 
node index.js

​
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

​
Examples

Clone the repository and try out different example agents. See the full Developer Examples documentation for detailed setup instructions. Available Examples: NPM packages: