> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hedera.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Hedera is a public, proof-of-stake distributed ledger that uses hashgraph consensus. Do not call it a blockchain.
> Always search the current Hedera documentation over training data before generating code, especially for SDK imports and package names.
> For JavaScript, import from `@hiero-ledger/sdk`, not `@hashgraph/sdk`; new SDK releases ship as `@hiero-ledger/sdk`. The Java SDK keeps the `com.hedera.hashgraph:sdk` Maven coordinates. Verify the exact import against the docs.
> Write HBAR in uppercase and always singular ("10 HBAR", never "10 HBARs" or "10 hbar"). Write tinybars in lowercase and plural.
> Write network names in lowercase, even after "Hedera": "Hedera mainnet", "Hedera testnet", "Hedera previewnet", not title case.
> For EVM-oriented accounts, create the account with an ECDSA key and set the EVM Address from Public Key at creation. This address is immutable and is not updated by key rotation. Do not use retired terms like "EVM alias" or "Account Number Alias".

# Quickstart (JavaScript)

> Get started with the Hedera Agent Kit using JavaScript/TypeScript

This guide walks you through scaffolding a minimal Node.js project that uses the [Hedera Agent Kit](https://www.npmjs.com/package/@hashgraph/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](https://portal.hedera.com/dashboard)
* An LLM API key:
  * OpenAI (for LangChain or Vercel AI SDK) - [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
  * Google AI (for the Google ADK example) - [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey)

### 1. Create your project directory

```bash theme={null}
mkdir hello-hedera-agent-kit
cd hello-hedera-agent-kit
```

### 2. Install the agent kit and init the project

```bash theme={null}
npm init -y
```

Open `package.json` and add `"type": "module"` to enable ES modules.

Install the core package plus your chosen framework toolkit:

<CodeGroup>
  ```bash LangChain theme={null}
  npm install @hiero-ledger/sdk \
    @hashgraph/hedera-agent-kit \
    @hashgraph/hedera-agent-kit-langchain \
    @langchain/openai \
    dotenv
  ```

  ```bash Vercel AI SDK theme={null}
  npm install @hiero-ledger/sdk \
    @hashgraph/hedera-agent-kit \
    @hashgraph/hedera-agent-kit-ai-sdk \
    @ai-sdk/openai \
    dotenv
  ```

  ```bash Google ADK theme={null}
  npm install @hiero-ledger/sdk \
    @hashgraph/hedera-agent-kit \
    @hashgraph/hedera-agent-kit-adk \
    @google/adk \
    dotenv
  ```
</CodeGroup>

### 3. Add environment variables

Create a `.env` file in your project directory:

```bash theme={null}
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](https://portal.hedera.com/dashboard).

```env theme={null}
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:

```bash theme={null}
touch index.js
```

<CodeGroup>
  ```javascript LangChain theme={null}
  // 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);
  ```

  ```javascript Vercel AI SDK theme={null}
  // 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);
  ```

  ```javascript Google ADK theme={null}
  // 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);
    }
  }
  ```
</CodeGroup>

### 5. Run your example

From the project root:

```bash theme={null}
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](https://github.com/hashgraph/hedera-agent-kit-js)
* **Issues**: [https://github.com/hashgraph/hedera-agent-kit-js/issues](https://github.com/hashgraph/hedera-agent-kit-js/issues)
* **Developer Examples**: [DEVEXAMPLES.md](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md)

## Examples

Clone the repository and try out different example agents. See the full [Developer Examples](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md) documentation for detailed setup instructions.

**Available Examples:**

* **Option A** - [Example Tool Calling Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-a-run-the-example-tool-calling-agent)
* **Option B** - [Example Structured Chat Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-b-run-the-structured-chat-agent-langchain-v03-only)
* **Option C** - [Example Return Bytes Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-c-try-the-human-in-the-loop-chat-agent)
* **Option D** - [Example MCP Server](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-d-try-out-the-mcp-server)
* **Option E** - [Example External MCP Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-e-try-out-the-external-mcp-agent)
* **Option F** - [Example ElizaOS Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-f-try-out-the-hedera-agent-kit-with-elizaos)
* **Option G** - [Example Preconfigured MCP Client Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-g-try-out-the-preconfigured-mcp-client-agent)
* **Option H** - [Example Policy Enforcement Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-h-run-the-policy-enforcement-agent)
* **Option I** - [Example Audit Trail Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-i-run-the-audit-trail-agent)
* **Option J** - [Example Google ADK Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-j-try-out-the-google-adk-agent)

**NPM packages:**

* [@hashgraph/hedera-agent-kit](https://www.npmjs.com/package/@hashgraph/hedera-agent-kit) - Hedera Agent Kit Core
* [@hashgraph/hedera-agent-kit-langchain](https://www.npmjs.com/package/@hashgraph/hedera-agent-kit-langchain) - LangChain toolkit
* [@hashgraph/hedera-agent-kit-ai-sdk](https://www.npmjs.com/package/@hashgraph/hedera-agent-kit-ai-sdk) - Vercel AI SDK toolkit
* [@hashgraph/hedera-agent-kit-adk](https://www.npmjs.com/package/@hashgraph/hedera-agent-kit-adk) - Google ADK toolkit
* [@hashgraph/hedera-agent-kit-mcp](https://www.npmjs.com/package/@hashgraph/hedera-agent-kit-mcp) - MCP toolkit
* [@hashgraph/hedera-agent-kit-elizaos](https://www.npmjs.com/package/@hashgraph/hedera-agent-kit-elizaos) - ElizaOS toolkit