> ## 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.

# 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