Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 23 additions & 6 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -462,15 +462,32 @@
"group": "AI Studio on Hedera",
"pages": [
"hedera/open-source-solutions/ai-studio-on-hedera",
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit",
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/elizaos-plugin",
{
"group": "Plugins",
"group": "Hedera AI Agent Kit",
"pages": [
"hedera/open-source-solutions/ai-studio-on-hedera/plugins",
"hedera/open-source-solutions/ai-studio-on-hedera/plugins/how-to-publish-and-register-your-plugin"
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit",

{
"group": "JavaScript SDK",
"pages": [
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/quickstart",
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/plugins",
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/how-to-publish-plugin"

]
},
{
"group": "Python SDK",
"pages": [
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/quickstart",
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/plugins",
"hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/how-to-publish-plugin"
]
}
]
},
"hedera/open-source-solutions/ai-studio-on-hedera/elizaos-plugin-for-hedera"
}

]
},
{
Expand Down
2 changes: 1 addition & 1 deletion hedera/networks/release-notes/mirror-node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -315,7 +315,7 @@ This release fixes a critical bug with the handling of claimed token airdrops. N

## [v0.118.0](https://github.com/hashgraph/hedera-mirror-node/releases/tag/v0.118.0)

A new developer quick start [guide](https://github.com/hashgraph/hedera-mirror-node/blob/main/docs/development.md) was added by a community member. This document is intended to help new contributors quickly setup their local development environment for the mirror node. Please try it out and hopefully make your first contribution!
A new developer quickstart [guide](https://github.com/hashgraph/hedera-mirror-node/blob/main/docs/development.md) was added by a community member. This document is intended to help new contributors quickly setup their local development environment for the mirror node. Please try it out and hopefully make your first contribution!

This release includes a new Redis-based distributed cache for the REST API. When enabled, API responses will be retrieved from the cache instead of querying the slower distributed database. This will protect the API against attacks and improve its scalability. For now, this functionality is disabled by default as we work towards stabilizing it.

Expand Down
10 changes: 2 additions & 8 deletions hedera/open-source-solutions/ai-studio-on-hedera.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,10 @@ AI Studio enables developers build AI agents that run transparently and verifiab
</Card>
<Card
title="ElizaOS Plugin"
href="/hedera/open-source-solutions/ai-studio-on-hedera/elizaos-plugin-for-hedera"
arrow
>

</Card>
<Card
title="Hedera Plugins"
href="/hedera/open-source-solutions/ai-studio-on-hedera/plugins"
href="/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/elizaos-plugin"
arrow
>


</Card>
</Columns>
Expand Down
294 changes: 79 additions & 215 deletions hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx
Original file line number Diff line number Diff line change
@@ -1,252 +1,116 @@
---
title: "Hedera AI Agent Kit"
description: "Features and Functionality in the Hedera Agent Kit SDK at https://github.com/hashgraph/hedera-agent-kit"
description: "Build LLM-powered applications that interact with the Hedera Network"
sidebarTitle: Overview
---

## Overview

Build LLM-powered applications that interact with the Hedera Network. Create conversational agents that can understand user requests in natural language and execute Hedera transactions, or build backend systems that leverage AI for on-chain operations.
The **Hedera Agent Kit** is an open-source framework for building AI-powered applications that interact with the Hedera Network.
Create conversational agents that understand natural language and execute Hedera transactions,
or build backend systems that leverage AI for on-chain operations.

The Hedera Agent Kit provides:
The Agent Kit is available in two languages:

- **Conversational AI**: LangChain-based agents that understand natural language
- **Adaptors for Framework Tools**: Pre-built tools covering Hedera services (and third party plugins), automatically adapted into popular frameworks like LangChain, Vercel ai-sdk, and MCP
- **Flexible Transaction Handling**: Direct execution or provide transaction bytes for user signing
- **Autonomous and Human-in-the-Loop** mode for executing transactions on Hedera
- **A Plugin Architecture** - For using both Hedera network capabilities and services, as well as third-party features and functionality
<CardGroup cols={2}>
<Card title="JavaScript SDK" icon="js" href="/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/quickstart">
Build with TypeScript/JavaScript using npm
</Card>
<Card title="Python SDK" icon="python" href="/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/quickstart">
Build with Python using pip
</Card>
</CardGroup>

---

## Quick Start - Create a Hedera Agent

See the npm package for the Hedera Agent Kit can be found at: https://www.npmjs.com/package/hedera-agent-kit
## Key Features

### 1. Create your project directory
Both SDKs provide:

```bash
mkdir hello-hedera-agent-kit
cd hello-hedera-agent-kit
```

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

Init and install with npm

```bash
npm init -y
```

> This command initializes a CommonJS project by default.

```bash
npm install hedera-agent-kit @langchain/core@^0.3 langchain@^0.3 @hashgraph/sdk dotenv
# NOTE: currently Hedera Agent Kit's Langchain toolkit is only compatible with langchain v0.3 We have v1 support coming very soon!
```

### 3. Install ONE of these AI provider packages:

```bash
# Option 1: OpenAI (requires API key)
npm install @langchain/openai@^0.6

# Option 2: Anthropic Claude (requires API key)
npm install @langchain/anthropic@^0.3

# Option 3: Groq (free tier available)
npm install @langchain/groq@^0.2

# Option 4: Ollama (100% free, runs locally)
npm install @langchain/ollama@^0.2
```

### 4. Add Environment Variables

Create a .env file in your directory

```bash
touch .env
```

If you don't already have a Hedera account, create a testnet account at https://portal.hedera.com/dashboard

Add the following to the .env file:

```env
# Required: Hedera credentials (get free testnet account at https://portal.hedera.com/dashboard)
HEDERA_ACCOUNT_ID="0.0.xxxxx"
HEDERA_PRIVATE_KEY="0x..." # ECDSA encoded private key

# Optional: Add the API key for your chosen AI provider
OPENAI_API_KEY="sk-proj-..." # For OpenAI (https://platform.openai.com/api-keys)
ANTHROPIC_API_KEY="sk-ant-..." # For Claude (https://console.anthropic.com)
GROQ_API_KEY="gsk_..." # For Groq free tier (https://console.groq.com/keys)
# Ollama doesn't need an API key (runs locally)
```

### 5. Create your agent

Once you have your project set up, create an index.js file:

```bash
touch index.js
```

```javascript index.js
const dotenv = require('dotenv');
dotenv.config();

const { ChatPromptTemplate } = require('@langchain/core/prompts');
const { AgentExecutor, createToolCallingAgent } = require('langchain/agents');
const { Client, PrivateKey } = require('@hashgraph/sdk');
const { HederaLangchainToolkit, coreQueriesPlugin } = require('hedera-agent-kit');

// Choose your AI provider (install the one you want to use)
function createLLM() {
// Option 1: OpenAI (requires OPENAI_API_KEY in .env)
if (process.env.OPENAI_API_KEY) {
const { ChatOpenAI } = require('@langchain/openai');
return new ChatOpenAI({ model: 'gpt-4o-mini' });
}

// Option 2: Anthropic Claude (requires ANTHROPIC_API_KEY in .env)
if (process.env.ANTHROPIC_API_KEY) {
const { ChatAnthropic } = require('@langchain/anthropic');
return new ChatAnthropic({ model: 'claude-3-haiku-20240307' });
}

// Option 3: Groq (requires GROQ_API_KEY in .env)
if (process.env.GROQ_API_KEY) {
const { ChatGroq } = require('@langchain/groq');
return new ChatGroq({ model: 'llama3-8b-8192' });
}

// Option 4: Ollama (free, local - requires Ollama installed and running)
try {
const { ChatOllama } = require('@langchain/ollama');
return new ChatOllama({
model: 'llama3.2',
baseUrl: 'http://localhost:11434'
});
} catch (e) {
console.error('No AI provider configured. Please either:');
console.error('1. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GROQ_API_KEY in .env');
console.error('2. Install and run Ollama locally (https://ollama.com)');
process.exit(1);
}
}

async function main() {
// Initialize AI model
const llm = createLLM();

// Hedera client setup (Testnet by default)
const client = Client.forTestnet().setOperator(
process.env.HEDERA_ACCOUNT_ID,
PrivateKey.fromStringECDSA(process.env.HEDERA_PRIVATE_KEY),
);

const hederaAgentToolkit = new HederaLangchainToolkit({
client,
configuration: {
plugins: [coreQueriesPlugin] // all our core plugins here https://github.com/hedera-dev/hedera-agent-kit/tree/main/typescript/src/plugins
},
});

// Load the structured chat prompt template
const prompt = ChatPromptTemplate.fromMessages([
['system', 'You are a helpful assistant'],
['placeholder', '{chat_history}'],
['human', '{input}'],
['placeholder', '{agent_scratchpad}'],
]);

// Fetch tools from toolkit
const tools = hederaAgentToolkit.getTools();

// Create the underlying agent
const agent = createToolCallingAgent({
llm,
tools,
prompt,
});

// Wrap everything in an executor that will maintain memory
const agentExecutor = new AgentExecutor({
agent,
tools,
});

const response = await agentExecutor.invoke({ input: "what's my balance?" });
console.log(response);
}

main().catch(console.error);
```

### 6. Run Your "Hello Hedera Agent Kit" Example

From the root directory, run your example agent, and prompt it to give your HBAR balance:

```bash
node index.js
```
- **🔌 Plugin Architecture**: Extensible design for easy customization
- **🧠 LangChain Integration**: Support for LangChain v1 and LangChain Classic
- **🪙 Comprehensive Hedera Tools**:
- Token creation and management (HTS)
- Smart contract execution (EVM)
- Account operations
- Topic (HCS) creation and messaging
- Transaction scheduling
- Allowances and approvals

---

## Examples

See and try out the example NextJS Application built using the latest version of the AI Agent Kit to see

Clone and try out different examples in the toolkit:

- The example tool calling agent can carry out simple tasks with Hedera tools in 'autonomous mode'
- The structured chat agent can string together and complete more complex tasks, autonomously on Hedera
- The human in the loop agent shows you how you can create a more controlled workflow
- Try out the MCP server to enable interaction with Hedera in your favorite application such as Claude Desktop or an IDE like Cursor.
## SDK Comparison

| Feature | JavaScript SDK | Python SDK |
|-------------------------|--------------------|--------------------|
| **Package Manager** | npm | pip |
| **Package Name** | `hedera-agent-kit` | `hedera-agent-kit` |
| **Hedera SDK** | `@hashgraph/sdk` | `hiero_sdk_python` |
| **Google ADK** | 🔜 Coming Soon | 🔜 Coming Soon |
| **AUTONOMOUS Mode** | ✅ Supported | ✅ Supported |
| **LangChain v1** | ✅ Supported | ✅ Supported |
| **LangChain Classic** | ✅ Supported | ✅ Supported |
| **Vercel AI SDK** | ✅ Supported | ❌ Not Available |
| **RETURN_BYTES Mode** | ✅ Supported | 🔜 Coming Soon |
| **ElizaOS Integration** | ✅ Supported | ❌ Not Available |
| **MCP Server** | ✅ Supported | 🔜 Coming Soon |

---

## About the Agent Kit

### Agent Execution Modes
## Available Plugins

This tool has two execution modes with AI agents; autonomous excution and return bytes. If you set:
Both SDKs provide the same core functionality through plugins:

- `mode: AgentMode.RETURN_BYTE` the transaction will be executed, and the bytes to execute the Hedera transaction will be returned.
- `mode: AgentMode.AUTONOMOUS` the transaction will be executed autonomously, using the accountID set (the operator account can be set in the client with `.setOperator(process.env.ACCOUNT_ID!)`)
| Plugin | Description |
|-----------------------------------|-----------------------------------------------------------------|
| **Core Account Plugin** | Transfer HBAR, create/update/delete accounts, manage allowances |
| **Core Account Query Plugin** | Query account info, balances, token holdings |
| **Core Consensus Plugin** | Create topics, submit messages (HCS) |
| **Core Consensus Query Plugin** | Query topic info and messages |
| **Core Token Plugin** | Create/mint/transfer fungible and non-fungible tokens (HTS) |
| **Core Token Query Plugin** | Query token info and pending airdrops |
| **Core EVM Plugin** | Deploy and interact with ERC-20 and ERC-721 contracts |
| **Core Transaction Query Plugin** | Query transaction records |
| **Core Misc Query Plugin** | Exchange rates and other utilities |

---

## Agent Kit Plugins
## Choose Your SDK

The Hedera Agent Kit provides a basic set of tools in the form of Plugins, which group together sets of functionality and can easily be included in your instance of hederaAgentToolkit
### JavaScript/TypeScript

Need additional capabilities with the agent kit, that isn't currently included? Please [open an issue](https://github.com/hedera-dev/hedera-agent-kit/issues).
Best for:
- Web applications
- Node.js backends
- Full feature set including ElizaOS and MCP Server

**Available Plugins**
[Get Started with JavaScript →](./hedera-agent-kit-js/quick-start)

- **Core Account Plugin**: Tools for Hedera Account Service operations
- **Core Consensus Plugin**: Tools for Hedera Consensus Service (HCS) operations
- **Core HTS Plugin**: Tools for Hedera Token Service operations
- **Core Queries Plugin**: Tools for querying Hedera network data
### Python

See the available plugins, the included tools, examples, and instructions on how to use a in the Github docs: [PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit/blob/main/docs/PLUGINS.md)
Best for:
- Data science and ML workflows
- Python backend services
- Jupyter notebooks and scripting

---
[Get Started with Python →](./hedera-agent-kit-py/quick-start)

## Requests and Contributions
---

**To request additional functionality**, please [open an issue](https://github.com/hedera-dev/hedera-agent-kit/issues).
## Resources

**To contribute** to the Hedera Agent Kit see the [Contributing Guidelines](https://github.com/hashgraph/hedera-agent-kit/blob/main/CONTRIBUTING.md)
| Resource | JavaScript | Python |
|-------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------|
| **GitHub** | [hedera-agent-kit-js](https://github.com/hashgraph/hedera-agent-kit-js) | [hedera-agent-kit-py](https://github.com/hashgraph/hedera-agent-kit-py) |
| **Package** | [npm](https://www.npmjs.com/package/hedera-agent-kit) | [PyPI](https://pypi.org/project/hedera-agent-kit/) |
| **Issues** | [GitHub Issues](https://github.com/hashgraph/hedera-agent-kit-js/issues) | [GitHub Issues](https://github.com/hashgraph/hedera-agent-kit-py/issues) |

**To create your own plugin**, see the instructions in [PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit/blob/main/docs/PLUGINS.md)
---

**To officially register your plugin**, [follow the instructions here](https://github.com/hashgraph/hedera-agent-kit/blob/main/docs/PLUGINS.md#registering-your-plugin)
## Requests and Contributions

---
**To request additional functionality**, please open an issue in the respective GitHub repository.

## Resources
**To contribute**, see the contributing guidelines in each repository.

- **GitHub**: https://github.com/hashgraph/hedera-agent-kit
- **npm**: [hedera-agent-kit](https://www.npmjs.com/package/hedera-agent-kit)
- **Issues**: https://github.com/hedera-dev/hedera-agent-kit/issues
**Need help?** Reach out in the [Hedera Discord](https://hedera.com/discord) in the **Support > developer-help-desk** channel.
Loading