DEVEXAMPLES.md

July 16, 2026 · View on GitHub

📦 Clone & Test the SDK Examples

1 – Install

git clone https://github.com/hashgraph/hedera-agent-kit-js.git

Requirements

Node.js v20 or higher

Repo Dependencies

Hedera Hashgraph SDK and API
Langchain Tools
zod
dotenv

2 – Configure

For Agent Examples

LangChain classic Copy examples/langchain/.env.example to examples/langchain/.env:

cd examples/langchain
cp .env.example .env

LangChain v1 Copy examples/langchain-v1/.env.example to examples/langchain-v1/.env:

cd examples/langchain-v1
cp .env.example .env

Add in your Hedera API and OPENAPI Keys

ACCOUNT_ID= 0.0.xxxxx
PRIVATE_KEY= 3030...
OPENAI_API_KEY= sk-proj-...

About Private Keys

Hedera supports two key types: ECDSA (secp256k1) and ED25519. These examples default to ECDSA. To switch to ED25519, uncomment the appropriate line in the agent's .ts file:

PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY!)   // default
// PrivateKey.fromStringED25519(process.env.PRIVATE_KEY!)

Both constructors accept hex (0x...) and DER encoded keys. The untyped PrivateKey.fromString() is deprecated — use the typed constructors instead. For a DER-encoded key you can also use PrivateKey.fromStringDer(), which detects the key type automatically. For a raw hex key the type cannot be inferred from the string alone, so pick the constructor matching how the key was generated (the Hedera Portal shows the type). A mismatch is rejected by the network with INVALID_SIGNATURE.

See the Hedera docs on Keys and Signatures and Accounts and Keys (EVM).

Create similar .env files for each of the other framework examples

3 – Choose an Example

Try out one or more of the example agents:

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
Option K - Example Streaming Tool Calling Agent

Option A: Run the Example Tool Calling Agent

With the tool-calling-agent 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 individual tool call.

LangChain Classic

Found at examples/langchain/tool-calling-agent.ts.

First, go into the directory where the example is and run npm install

cd examples/langchain
npm install

Then, run the example

npm run langchain:tool-calling-agent

LangChain v1

Found at examples/langchain-v1/plugin-tool-calling-agent.ts.

First, go into the directory where the example is and run npm install

cd examples/langchain-v1
npm install

Then, run the example

npm run langchain:plugin-tool-calling-agent

interact with the agent. First, tell the agent who you are (your name) and try out some 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

Option B: Run the Structured Chat Agent (LangChain v0.3 only)

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.

First, go into the directory where the example is and run npm install

cd examples/langchain
npm install

Then, run the example

npm run langchain:structured-chat-agent

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.

LangChain v0.3

First, go into the directory where the example is and run npm install

cd examples/langchain
npm install

Then, run the 'human in the loop' or 'return bytes' example:

npm run langchain:return-bytes-tool-calling-agent

LangChain v1

First, go into the directory where the example is and run npm install

cd examples/langchain-v1
npm install

Then, run the 'human in the loop' or 'return bytes' example:

npm run langchain:return-bytes-tool-calling-agent

Note

Since v4.0.0, RETURN_BYTES standardizes raw.bytes to Uint8Array — see the migration guide if you previously parsed Node Buffer payloads. For the full non-custodial pattern built on this mode, see docs/MCP.md.

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

Option D: Try Out the MCP Server

Note

For the architecture behind this example (custodial vs. non-custodial, RETURN_BYTES, key custody), see docs/MCP.md.

Navigate to the MCP examples directory:

cd examples/modelcontextprotocol

Configure your environment: Create an .env file with HEDERA_OPERATOR_ID and HEDERA_OPERATOR_KEY.
Install dependencies and build:

cd ../../packages/mcp
npm install
npm run build
cd ../../examples/modelcontextprotocol
npm install
npm run build

Run the Stdio MCP Server:

npm run start:stdio

Or run the HTTP MCP Server in Return Bytes mode:

npm run start:http:return-bytes

Optional: connect Claude Desktop or your IDE to the running server — see docs/MCP.md for the client configuration.

Option E: Try Out the External MCP Agent

This example demonstrates how to integrate external MCP (Model Context Protocol) servers with the Hedera Agent Kit. The agent combines a single plugin from the local toolkit with tools from a remote MCP server. While this example uses the Hedera MCP server from this repository, you can easily integrate other MCP servers by modifying the configuration.

Found at:

examples/langchain-v1/external-mcp-agent.ts
examples/ai-sdk/mcp-external-agent.ts

Prerequisites

Set up the Hedera MCP server following the instructions in Option D.

cd packages/mcp
npm install
npm run build
cd ../../examples/modelcontextprotocol
npm install
npm run build

Configure your environment variables in examples/langchain-v1/.env:

ACCOUNT_ID=0.0.xxxxx
PRIVATE_KEY=3030...
OPENAI_API_KEY=sk-proj-...

About Private Keys

Hedera supports two key types: ECDSA (secp256k1) and ED25519. These examples default to ECDSA. To switch to ED25519, uncomment the appropriate line in the agent's .ts file:

PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY!)   // default
// PrivateKey.fromStringED25519(process.env.PRIVATE_KEY!)

Both constructors accept hex (0x...) and DER-encoded keys. DER-encoded ED25519 keys start with 302e...; DER-encoded ECDSA keys start with 3030.... The untyped PrivateKey.fromString() is deprecated — use the typed constructors instead. There is no reliable way to infer the key type from the string alone, so pick the constructor matching how the key was generated (the Hedera Portal shows the type). A mismatch is rejected by the network with INVALID_SIGNATURE. Note: the agent kit's built-in EVM/ERC tools currently require an ECDSA operator key; the Hedera EVM itself supports both key types.

See the Hedera docs on Keys and Signatures and Accounts and Keys (EVM).

Update the MCP server path in external-mcp-agent.ts in the args array with the absolute path to your built MCP server.

Running the Example

LangChain v1

Navigate to the example directory:

cd examples/langchain-v1
npm install

Run the external MCP agent:

npm run langchain:external-mcp-agent

The agent will start a CLI chatbot that combines the coreMiscQueriesPlugin from the local toolkit with tools from the external MCP server, allowing you to interact with the Hedera blockchain in natural language.

AI SDK

Navigate to the example directory:

cd examples/ai-sdk
npm install

Run the external MCP agent:

npm run ai-sdk:mcp-external-agent

The agent will start a CLI chatbot using the AI SDK to interact with the external MCP server.

Note: To integrate other types of MCP servers (HTTP, SSE, WebSocket, etc.), modify the mcpServers configuration in the example file. See the LangChain MCP Adapters documentation for configuration details.

Option F: 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.

v4 Import Update

As of v4, ElizaOS is a standalone package:

import { HederaElizaOSToolkit } from '@hashgraph/hedera-agent-kit-elizaos';

See the v3 to v4 Migration Guide for full details.

Clone the Hedera ElizaOS Plugin Repository
Install ElizaOS CLI
Follow the Hedera ElizaOS Plugin Docs

Option G: Try out the Preconfigured MCP Client Agent

This example demonstrates how to use the Hedera Agent Kit with preconfigured MCP servers (like Hederion or Hgraph) to access advanced tools without manual server setup.

Found at:

examples/langchain-v1/preconfigured-mcp-client-agent.ts
examples/ai-sdk/preconfigured-mcp-client-agent.ts

Prerequisites

Configure your environment variables as described in the "Configure" section above.

Running the Example

LangChain v1

cd examples/langchain-v1
npm install
npm run langchain:preconfigured-mcp-client-agent

AI SDK

cd examples/ai-sdk
npm install
npm run ai-sdk:preconfigured-mcp-client-agent

These agents connect to the configured MCP servers (defined in your code) and allow you to interact with the provided tools using natural language.

If using HederaMCPServer.HGRAPH_MCP_MAINNET, ensure you have set the HGRAPH_API_KEY in your .env file. See docs.hgraph.com for details.

Option H: Run the Policy Enforcement Agent

This example demonstrates how to use the MaxRecipientsPolicy to enforce rules on transactions. In this case, it restricts any HBAR transfer to a maximum of 2 recipients.

Found at:

examples/ai-sdk/policy-enforcement-agent.ts
examples/langchain-v1/policy-enforcement-agent.ts

Running the Example

AI SDK

cd examples/ai-sdk
npm install
npm run ai-sdk:policy-enforcement-agent

LangChain v1

cd examples/langchain-v1
npm install
npm run langchain:policy-enforcement-agent

Option I: Run the Audit Trail Agent

This example demonstrates how to use the HcsAuditTrailHook to automatically audit specific actions (like HBAR transfers or token creation) by submitting audit logs to a Hedera Consensus Service (HCS) topic.

Found at:

examples/ai-sdk/audit-trail-agent.ts
examples/langchain-v1/audit-trail-agent.ts

Important

This agent works only in mode: AgentMode.AUTONOMOUS.

Running the Example

AI SDK

cd examples/ai-sdk
npm install
npm run ai-sdk:audit-trail-agent

LangChain v1

cd examples/langchain-v1
npm install
npm run langchain:audit-trail-agent

Option J: Try out the Google ADK Agent

This example demonstrates how to use the Hedera Agent Kit with Google's Agent Development Kit (ADK). It includes a plugin tool calling agent and supports the ADK Web GUI for interactive testing.

Found at:

examples/adk/

Prerequisites

Configure your environment variables in examples/adk/.env. You will need your Hedera credentials and a Google AI API Key (Gemini).

ACCOUNT_ID=0.0.xxxxx
PRIVATE_KEY=3030...
GEMINI_API_KEY=your-gemini-api-key

Running the Example

Navigate to the example directory:

cd examples/adk
npm install

Run the CLI agent:

npm run adk:plugin-tool-calling-agent

Or run the ADK Web GUI:

npx adk web

This will start a local web server (by default at http://localhost:8000) where you can interact with the Hedera agent visually.

Note: It is strongly recommended to use the native ADK tools (npx adk run agent.ts and npx adk web) for interacting with ADK agents. The custom CLI implemented in plugin-tool-calling-agent.ts is provided solely as an example to demonstrate how building a custom CLI runner is possible.

Option K: Run the Streaming Tool Calling Agent

Same as the basic tool calling agent, but the agent's responses are streamed token by token instead of returned all at once — using agent.stream() instead of agent.invoke() in LangChain v1, and streamText instead of generateText in the AI SDK.

Found at:

examples/ai-sdk/streaming-tool-calling-agent.ts
examples/langchain-v1/streaming-tool-calling-agent.ts

Running the Example

AI SDK

cd examples/ai-sdk
npm install
npm run ai-sdk:streaming-tool-calling-agent

LangChain v1

cd examples/langchain-v1
npm install
npm run langchain:streaming-tool-calling-agent