Quickstart (JavaScript)

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

A Hedera testnet account - create one at https://portal.hedera.com/dashboard
An LLM API key:
- OpenAI (for LangChain or Vercel AI SDK) - https://platform.openai.com/api-keys
- Google AI (for the Google ADK example) - https://aistudio.google.com/apikey

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:

Mode	Description
`AgentMode.AUTONOMOUS`	The transaction is executed autonomously using the operator account
`AgentMode.RETURN_BYTES`	The transaction bytes are returned for the user to sign and execute

Resources

GitHub: https://github.com/hashgraph/hedera-agent-kit-js
Issues: https://github.com/hashgraph/hedera-agent-kit-js/issues
Developer Examples: DEVEXAMPLES.md

Examples

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

Option A - Example Tool Calling Agent
Option B - Example Structured Chat Agent
Option C - Example Return Bytes Agent
Option D - Example MCP Server
Option E - Example External MCP Agent
Option F - Example ElizaOS Agent
Option G - Example Preconfigured MCP Client Agent
Option H - Example Policy Enforcement Agent
Option I - Example Audit Trail Agent
Option J - Example Google ADK Agent

NPM packages:

@hashgraph/hedera-agent-kit - Hedera Agent Kit Core
@hashgraph/hedera-agent-kit-langchain - LangChain toolkit
@hashgraph/hedera-agent-kit-ai-sdk - Vercel AI SDK toolkit
@hashgraph/hedera-agent-kit-adk - Google ADK toolkit
@hashgraph/hedera-agent-kit-mcp - MCP toolkit
@hashgraph/hedera-agent-kit-elizaos - ElizaOS toolkit

​Prerequisites

​1. Create your project directory

​2. Install the agent kit and init the project

​3. Add environment variables

​4. Create your agent

​5. Run your example

​Agent Execution Modes

​Resources

​Examples