diff --git a/docs.json b/docs.json index 520535ae..6c60830e 100644 --- a/docs.json +++ b/docs.json @@ -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" + } + ] }, { diff --git a/hedera/networks/release-notes/mirror-node.mdx b/hedera/networks/release-notes/mirror-node.mdx index fd101722..a62c5b3e 100644 --- a/hedera/networks/release-notes/mirror-node.mdx +++ b/hedera/networks/release-notes/mirror-node.mdx @@ -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. diff --git a/hedera/open-source-solutions/ai-studio-on-hedera.mdx b/hedera/open-source-solutions/ai-studio-on-hedera.mdx index aac236f9..ea7f4a67 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera.mdx @@ -25,16 +25,10 @@ AI Studio enables developers build AI agents that run transparently and verifiab - - - + diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx index 752b9f6a..9e57e160 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx @@ -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 + + + Build with TypeScript/JavaScript using npm + + + Build with Python using pip + + --- -## 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. diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/elizaos-plugin-for-hedera.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/elizaos-plugin.mdx similarity index 73% rename from hedera/open-source-solutions/ai-studio-on-hedera/elizaos-plugin-for-hedera.mdx rename to hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/elizaos-plugin.mdx index 9b53abdd..82f75b95 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera/elizaos-plugin-for-hedera.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/elizaos-plugin.mdx @@ -1,64 +1,76 @@ ---- -title: "ElizaOS Plugin for Hedera" -description: "A plugin built for the ElizaOS framework to enable developers creating ElizaOS Agents to seamlessly integrate Hedera Network Functionality" ---- - - -## Overview - -ElizaOS is an open‑source agent runtime for building autonomous, tool‑using AI agents that can plan and take actions. ElizaOS is an easy to use framework created to make it easy to build web3-native agents. - -The [**Hedera Plugin for Eliza**](https://github.com/elizaos-plugins/plugin-hedera) integrates Hedera functionality into ElizaOS, making it easy to interact with the network directly from the ElizaOS platform. With this plugin, users can execute a variety of blockchain operations, including: - -* **HBAR and HTS Token Management**: Check balances and execute transfers with ease.​ -* **Token Operations**: Create, mint, and manage tokens efficiently.​ -* **Consensus Service Interaction**: Engage with Hedera Consensus Service (HCS) topics for streamlined consensus mechanisms.​ -* **Token Distribution**: Airdrop tokens and manage associations seamlessly. - -This plugin provides an efficient way to work with Hedera Services and transactions, while staying within the ElizaOS environment. It connects ElizaOS directly to Hedera via the Hedera Agent Kit, exposing safe, typed tools for transfers, tokens, and mirror node queries. - -*** - -## ElizaOS + the Hedera Agent Kit - -At its core, the plugin is powered by the [hedera-agent-kit,](https://github.com/hashgraph/hedera-agent-kit/) which streamlines network interactions and automates common tasks. It supports: - -* Real-time HBAR balance updates for the connected wallet. -* Automated on-chain queries without requiring manual actions. -* Context-aware responses, allowing users to ask questions like: - - User: *What’s my HBAR balance?*\ - Response: *Your current HBAR balance is 999.81 HBAR.* - -This ensures a smooth and intuitive user experience, reducing friction when working with the Hedera network. - -Building on Hedera means users have all the avantages of the Hedera network: - -* Fast finality and low, predictable fees—ideal for iterative agent behavior. -* Native tokenization (HTS) with rich controls and compliance features. -* Ordered, verifiable messaging via Hedera Consensus Service (HCS). -* Carbon‑negative network with high throughput and stable costs. - -*** - -## Try It Out - -This plugin simplifies Hedera blockchain development and interaction within ElizaOS. - -ElizaOS provides the runtime for AI agents (planning, memory, tools, messaging), while the Hedera Agent Kit plugin provides strongly‑typed, batteries‑included functions for common Hedera actions (HBAR transfers, HTS token ops, HCS messages, queries). This plugin bridges the two, so an Eliza agent can call Hedera actions safely via tools agent-kit defined tools. - -### How It Works - -* At startup the plugin registers the Hedera Agent Kit toolkit with ElizaOS. -* It validates your Hedera credentials, creates a Hedera client (testnet by default), and registers a set of blockchain tools (actions) with the agent runtime. -* Agent prompts/plans then invokes these tools to perform on‑chain operations and returns results back into the conversation. - -\ -For full documentation and setup instructions, visit the [**GitHub Repository**](https://github.com/elizaos-plugins/plugin-hedera). - - +--- +title: "ElizaOS Plugin for Hedera" +description: "A plugin built for the ElizaOS framework to enable developers creating ElizaOS Agents to seamlessly integrate Hedera Network Functionality" +--- + + +## Overview + +ElizaOS is an open‑source agent runtime for building autonomous, tool‑using AI agents that can plan and take actions. ElizaOS is an easy-to-use framework created to make it easy to build web3-native agents. + +The [**Hedera Plugin for Eliza**](https://github.com/elizaos-plugins/plugin-hedera) integrates Hedera functionality into ElizaOS, making it easy to interact with the network directly from the ElizaOS platform. With this plugin, users can execute a variety of blockchain operations, including: + +* **HBAR and HTS Token Management**: Check balances and execute transfers with ease. +* **Token Operations**: Create, mint, and manage tokens efficiently. +* **Consensus Service Interaction**: Engage with Hedera Consensus Service (HCS) topics for streamlined consensus mechanisms. +* **Token Distribution**: Airdrop tokens and manage associations seamlessly. + +This plugin provides an efficient way to work with Hedera Services and transactions while staying within the ElizaOS environment. It connects ElizaOS directly to Hedera via the Hedera Agent Kit, exposing safe, typed tools for transfers, tokens, and mirror node queries. + +*** + +## ElizaOS + the Hedera Agent Kit + +At its core, the plugin is powered by the [hedera-agent-kit](https://github.com/hashgraph/hedera-agent-kit-js), which streamlines network interactions and automates common tasks. It supports: + +* Real-time HBAR balance updates for the connected wallet. +* Automated on-chain queries without requiring manual actions. +* Context-aware responses, allowing users to ask questions like: + + User: *What’s my HBAR balance?*\ + Response: *Your current HBAR balance is 999.81 HBAR.* + +This ensures a smooth and intuitive user experience, reducing friction when working with the Hedera network. + +> ⚠️ **Breaking Change: hedera-agent-kit v3.5.0 Import Update** +> +> If you are using `hedera-aagentgent-kit` version `3.5.0` or higher, the `HederaElizaOSToolkit` import path has changed: +> +> ```typescript +> // ❌ Deprecated (Will fail in v3.5.0+) +> import { HederaElizaOSToolkit } from 'hedera-agent-kit'; +> +> // ✅ Correct +> import { HederaElizaOSToolkit } from 'hedera-agent-kit/elizaos'; +> ``` + +Building on Hedera means users have all the advantages of the Hedera network: + +* Fast finality and low, predictable fees—ideal for iterative agent behavior. +* Native tokenization (HTS) with rich controls and compliance features. +* Ordered, verifiable messaging via Hedera Consensus Service (HCS). +* Carbon‑negative network with high throughput and stable costs. + +*** + +## Try It Out + +This plugin simplifies Hedera blockchain development and interaction within ElizaOS. + +ElizaOS provides the runtime for AI agents (planning, memory, tools, messaging), while the Hedera Agent Kit plugin provides strongly‑typed, batteries‑included functions for common Hedera actions (HBAR transfers, HTS token ops, HCS messages, queries). This plugin bridges the two, so an Eliza agent can call Hedera actions safely via tools agent-kit defined tools. + +### How It Works + +* At startup the plugin registers the Hedera Agent Kit toolkit with ElizaOS. +* It validates your Hedera credentials, creates a Hedera client (testnet by default), and registers a set of blockchain tools (actions) with the agent runtime. +* Agent prompts/plans then invokes these tools to perform on‑chain operations and returns results back into the conversation. + +\ +For full documentation and setup instructions, visit the [**GitHub Repository**](https://github.com/elizaos-plugins/plugin-hedera). + + diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/plugins/how-to-publish-and-register-your-plugin.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/how-to-publish-plugin.mdx similarity index 74% rename from hedera/open-source-solutions/ai-studio-on-hedera/plugins/how-to-publish-and-register-your-plugin.mdx rename to hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/how-to-publish-plugin.mdx index f12f5ddf..6139c32b 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera/plugins/how-to-publish-and-register-your-plugin.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/how-to-publish-plugin.mdx @@ -1,63 +1,64 @@ ---- -title: "How To: Publish & Register Your Plugin" -description: "Instructions for Creating, Publishing and Registering your Hedera Agent Kit Plugin" ---- - - -### Publish and Register Your Plugin - -To create a plugin to be use with the Hedera Agent Kit, you will need to create a plugin in your own repository, publish an npm package, and provide a description of the functionality included in that plugin, as well as the required and optional parameters. - -Once you have a repository, published npm package, and a README with a description of the functionality included in that plugin in your plugin's repo, as well as the required and optional parameters, you can add it to the Hedera Agent Kit by forking and opening a Pull Request to: - -1. Include the plugin as a bullet point under the **Third Party Plugin** section in the [README.md in the hedera-agent-kit](https://github.com/hashgraph/hedera-agent-kit/blob/main/README.md#third-party-plugins). Include the name, a brief description, and a link to the repository with the README, as well the URL linked to the published npm package. -2. Include the same information in [docs/PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit/blob/main/docs/PLUGINS.md#available-third-party-plugins) of the hedera-agent-kit repository under the **Available Third Party Plugins** section. -3. If you would like to include your plugin functionality in the Hedera plugin built for ElizaOS simply make a PR to [add your plugin name to the `plugins` array in the Hedera ElizaOS plugin](https://github.com/elizaos-plugins/plugin-hedera/blob/1.x/src/adapter-plugin/plugin.ts#L72) where the configuration is initiated. The hedera-agent-kit adaptor architecture means your plugin functionality will be usable with no additional configuration needed. - -Feel free to also [reach out to the Hedera Agent Kit maintainers on Discord](https://hedera.com/discord) or another channel so we can test out your plugin, include it in our docs, and let our community know thorough marketing and community channels. - -Please also reach out in the Hedera Discord in the Support > developer-help-desk channelor create an Issue in this repository for help building, publishing, and promoting your plugin. - -### Plugin README Template - -```` -## Plugin Name -This plugin was built by for the . It was built to enable to - -_Feel free to include a description of your project and how it can be used with the Hedera Agent Kit. - -### Installation - -```bash -npm install -``` - -### Usage - -```javascript -import { myPlugin } from ''; -``` - -```javascript - const hederaAgentToolkit = new HederaLangchainToolkit({ - client, - configuration: { - context: { - mode: AgentMode.AUTONOMOUS, - }, - plugins: [coreHTSPlugin, coreAccountPlugin, coreConsensusPlugin, coreQueriesPlugin, myPlugin], - }, - }); -``` - -### Functionality -Describe the different tools or individual pieces of functionality included in this plugin, and how to use them. - -**Plugin Name** -_High level description of the plugin_ - -| Tool Name | Description |Usage | -| ----------------------------------------------- | -------------------------------------------------- |--------------------------------------------------------- | -| `YOUR_PLUGIN_TOOL_NAME`| What it does | How to use. Include a list of parameters and their descriptions| - -```` +--- +title: "How To: Publish & Register Your Plugin (JavaScript)" +description: "Instructions for Creating, Publishing and Registering your Hedera Agent Kit Plugin" +--- + + +### Publish and Register Your Plugin + +To create a plugin to be use with the Hedera Agent Kit, you will need to create a plugin in your own repository, publish an npm package, and provide a description of the functionality included in that plugin, as well as the required and optional parameters. + +Once you have a repository, published npm package, and a README with a description of the functionality included in that plugin in your plugin's repo, as well as the required and optional parameters, you can add it to the Hedera Agent Kit by forking and opening a Pull Request to: + +1. Include the plugin as a bullet point under the **Third Party Plugin** section in the [README.md in the hedera-agent-kit-js](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/README.md#third-party-plugins). Include the name, a brief description, and a link to the repository with the README, as well the URL linked to the published npm package. +2. Include the same information in [docs/PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/PLUGINS.md#available-third-party-plugins) of the hedera-agent-kit-js repository under the **Available Third Party Plugins** section. +3. If you would like to include your plugin functionality in the Hedera plugin built for ElizaOS simply make a PR to [add your plugin name to the `plugins` array in the Hedera ElizaOS plugin](https://github.com/elizaos-plugins/plugin-hedera/blob/1.x/src/adapter-plugin/plugin.ts#L72) where the configuration is initiated. The hedera-agent-kit adaptor architecture means your plugin functionality will be usable with no additional configuration needed. + +Feel free to also [reach out to the Hedera Agent Kit maintainers on Discord](https://hedera.com/discord) or another channel so we can test out your plugin, include it in our docs, and let our community know through marketing and community channels. + +Please also reach out in the Hedera Discord in the **Support > developer-help-desk** channel or create an Issue in this repository for help building, publishing, and promoting your plugin. + +### Plugin README Template + +```` +## Plugin Name +This plugin was built by for the . It was built to enable to + +_Feel free to include a description of your project and how it can be used with the Hedera Agent Kit. + +### Installation + +```bash +npm install +``` + +### Usage + +```javascript +import { myPlugin } from ''; +``` + +```javascript + const hederaAgentToolkit = new HederaLangchainToolkit({ + client, + configuration: { + context: { + mode: AgentMode.AUTONOMOUS, + }, + plugins: [coreTokenPlugin, coreAccountPlugin, coreConsensusPlugin, coreQueriesPlugin, myPlugin], + }, + }); +``` + +### Functionality +Describe the different tools or individual pieces of functionality included in this plugin, and how to use them. + +**Plugin Name** +_High level description of the plugin_ + +| Tool Name | Description |Usage | +| ----------------------------------------------- | -------------------------------------------------- |--------------------------------------------------------- | +| `YOUR_PLUGIN_TOOL_NAME`| What it does | How to use. Include a list of parameters and their descriptions| + +```` + \ No newline at end of file diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/plugins.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/plugins.mdx similarity index 54% rename from hedera/open-source-solutions/ai-studio-on-hedera/plugins.mdx rename to hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/plugins.mdx index 5000f52f..59911cd9 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera/plugins.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/plugins.mdx @@ -1,27 +1,29 @@ --- -title: Plugins +title: Plugins (JavaScript) description: The Hedera Agent Kit implements a plugin architecture to include features and functionality for both Hedera Network functions and Services, as well as third party apps and projects. -sidebarTitle: Overview --- + ## Summary -The Hedera Agent Kit provides a comprehensive set of tools organized into **plugins**, which can be installed alongside the Hedera Agent Kit and used to extend the core functionality of the Hedera Agent Kit SDK. These tools can be used both by the conversational agent, and when you are building with the SDK. +The Hedera Agent Kit provides a comprehensive set of tools organized into **plugins**, which can be installed alongside the Hedera Agent Kit and used to extend the core functionality of the Hedera Agent Kit SDK. These tools can be used both by the conversational agent and when you are building with the SDK. -The Hedera services and functionality built into this agent toolkit are also implemented as plugins, you can see a description of each plugin in the [HEDERAPLUGINS.md](https://github.com/hashgraph/hedera-agent-kit/blob/main/docs/HEDERAPLUGINS.md) file, as well as list of the individual tools for each Hedera service that are included in each plugin. +The Hedera services built into this agent toolkit are also implemented as plugins. You can see a description of each plugin in the [HEDERAPLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/HEDERAPLUGINS.md) file, as well as a list of the individual tools for each Hedera service that are included in each plugin. ### Available Third-Party Plugins -* [Memejob Plugin](https://www.npmjs.com/package/@buidlerlabs/hak-memejob-plugin) provides a streamlined interface to the [**memejob**](https://memejob.fun/) protocol, exposing the core actions (`create`, `buy`, `sell`) for interacting with meme tokens on Hedera. See the[ **Github repository** ](https://github.com/buidler-labs/hak-memejob-plugin)for more information.\\ +* [Memejob Plugin](https://www.npmjs.com/package/@buidlerlabs/hak-memejob-plugin) provides a streamlined interface to the [**memejob**](https://memejob.fun/) protocol, exposing the core actions (`create`, `buy`, `sell`) for interacting with meme tokens on Hedera. See the [**GitHub repository**](https://github.com/buidler-labs/hak-memejob-plugin) for more information. -*** +--- ## Plugin Architecture +The tools are organized into plugins, each containing a set of functionality related to the Hedera service or project they are created for. + ### Plugin Interface Every plugin must implement the Plugin interface: -```javascript +```typescript export interface Plugin { name: string; version?: string; @@ -34,23 +36,27 @@ export interface Plugin { Each tool must implement the Tool interface: -```javascript +```typescript export type Tool = { method: string; name: string; description: string; parameters: z.ZodObject; execute: (client: Client, context: Context, params: any) => Promise; + // transactionToolOutputParser and untypedQueryOutputParser can be used. If required, define a custom parser + outputParser?: (rawOutput: string) => { raw: any; humanMessage: string }; }; ``` -#### Examples +> **Note:** The `outputParser` is important for **LangChain v1** tools. It extracts tool output into `{ raw, humanMessage }` format. Two built-in parsers are available: +> - `transactionToolOutputParser` - For transaction tools (handles RETURN_BYTES and EXECUTE_TRANSACTION modes) +> - `untypedQueryOutputParser` - For query tools (generic parser) +> +> If not defined, a default parser is used. -See an example of how to create your own plugin in [hedera-agent-kit/typescript/examples/plugin/example-plugin.ts](https://github.com/hashgraph/hedera-agent-kit/blob/main/typescript/examples/plugin/example-plugin.ts) +See [typescript/src/shared/tools.ts](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/typescript/src/shared/tools.ts) for the full definition. -See an example application using Hedera plugins and tools and a custom plugin at [hedera-agent-kit/typescript/examples/langchain/plugin-tool-calling-agent.ts](https://github.com/hashgraph/hedera-agent-kit/blob/main/typescript/examples/langchain/plugin-tool-calling-agent.ts) - -*** +--- ## Step-by-Step Guide @@ -66,7 +72,7 @@ See an example application using Hedera plugins and tools and a custom plugin at ### **Step 2: Implement Your Tool** -Create your tool file (e.g., tools/my-service/my-tool.ts): +Create your tool file (e.g., `tools/my-service/my-tool.ts`): ```typescript import { z } from 'zod'; @@ -151,10 +157,9 @@ export const myCustomPluginToolNames = { export default { myCustomPlugin, myCustomPluginToolNames }; ``` - ### Step 4: Register Your Plugin -Add your plugin to the main plugins index (src/plugins/index.ts): +Add your plugin to the main plugins index (`src/plugins/index.ts`): ```typescript import { myCustomPlugin, myCustomPluginToolNames } from './my-custom-plugin'; @@ -183,17 +188,44 @@ export { **Transaction Handling** * Use handleTransaction() to facilitate human-in-the-loop and autonomous execution flows -* Respect the AgentMode (AUTONOMOUS vs RETURN\_BYTES) +* Respect the AgentMode (AUTONOMOUS vs. RETURN\_BYTES) * Implement proper transaction building patterns *** ## Using Your Custom Plugin +### LangChain v0.3 (Classic) + +```typescript +import { HederaLangchainToolkit } from "hedera-agent-kit"; +import { + myCustomPlugin, + myCustomPluginToolNames, +} from "./plugins/my-custom-plugin"; + +const toolkit = new HederaLangchainToolkit({ + client, + configuration: { + tools: [myCustomPluginToolNames.MY_TOOL], + plugins: [myCustomPlugin], + context: { + mode: AgentMode.AUTONOMOUS, + }, + }, +}); +``` + +### LangChain v1 (New) + ```typescript -import { HederaLangchainToolkit } from 'hedera-agent-kit'; -import { myCustomPlugin, myCustomPluginToolNames } from './plugins/my-custom-plugin'; +import { HederaLangchainToolkit, ResponseParserService } from "hedera-agent-kit"; +import { + myCustomPlugin, + myCustomPluginToolNames, +} from "./plugins/my-custom-plugin"; +// Initialize toolkit const toolkit = new HederaLangchainToolkit({ client, configuration: { @@ -204,4 +236,34 @@ const toolkit = new HederaLangchainToolkit({ }, }, }); + +// Initialize response parser +const responseParsingService = new ResponseParserService(toolkit.getTools()); + +// ... inside your agent loop ... +const response = await agent.invoke({ messages: [/* ... */] }); + +// Parse tool outputs +const parsedToolData = responseParsingService.parseNewToolMessages(response); +const toolCall = parsedToolData[0]; // assuming only one tool was called + +if (toolCall) { + console.log('Human Message:', toolCall.parsedData.humanMessage); + console.log('Raw Data:', toolCall.parsedData.raw); +} ``` + +--- + +## Publish and Register Your Plugin + +See [How To: Publish & Register Your Plugin](./plugins/how-to-publish-and-register-your-plugin) for instructions on creating, publishing, and registering your plugin with the Hedera Agent Kit ecosystem. + +--- + +## Examples and References + +* See existing core plugins in [typescript/src/plugins/core-*-plugin/](https://github.com/hashgraph/hedera-agent-kit-js/tree/main/typescript/src/plugins) +* Follow the patterns established in tools like [transfer-hbar.ts](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/typescript/src/plugins/core-account-plugin/tools/account/transfer-hbar.ts) +* See [plugin-tool-calling-agent.ts](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/typescript/examples/langchain-v1/plugin-tool-calling-agent.ts) for usage examples + diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/quickstart.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/quickstart.mdx new file mode 100644 index 00000000..1f1ab5b6 --- /dev/null +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-js/quickstart.mdx @@ -0,0 +1,217 @@ +--- +title: "Quickstart (JavaScript)" +description: "Get started with the Hedera Agent Kit using JavaScript/TypeScript" +--- + +## Quickstart - Create a Hedera Agent + +See the npm package: https://www.npmjs.com/package/hedera-agent-kit + +### 1. Create your project directory + +```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 +``` + +Open `package.json` and add `"type": "module"` to enable ES modules. + +```bash +npm install hedera-agent-kit @langchain/core langchain @langchain/langgraph @hashgraph/sdk dotenv +``` + +> **Note**: The Hedera Agent Kit supports both **LangChain v1** (recommended) and **LangChain classic** (v0.3, legacy). The examples below use LangChain v1. + +### 3. Install ONE of these AI provider packages + +```bash +# Option 1: OpenAI (requires API key) +# for Langchain classic +npm install @langchain/openai@^0.6 + +# for LangChain v1 +npm install @langchain/openai@^1npm install @langchain/openai@^0.6 + +# Option 2: Anthropic Claude (requires API key) +# for LangChain classic +npm install @langchain/anthropic@^0.3 + +# for LangChain v1 +npm install @langchain/anthropic@^1 + +# Option 3: Groq (free tier available) +# for Langchain classic +npm install @langchain/groq@^0.2 + +# for LangChain v1 +npm install @langchain/groq@^1 + +# Option 4: Ollama (100% free, runs locally) +# for Langchain classic +npm install @langchain/ollama@^0.2 + +# for LangChain v1 +npm install @langchain/ollama@^1 +``` + +### 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) +ACCOUNT_ID="0.0.xxxxx" +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 +// index.js +import { Client, PrivateKey } from '@hashgraph/sdk'; +import { HederaLangchainToolkit, AgentMode } from 'hedera-agent-kit'; +import { createAgent } from 'langchain'; +import { MemorySaver } from '@langchain/langgraph'; +import { ChatOpenAI } from '@langchain/openai'; +// import { ChatAnthropic } from '@langchain/anthropic'; +// import { ChatGroq } from '@langchain/groq'; +// import { ChatOllama } from '@langchain/ollama'; +import dotenv from 'dotenv'; + +dotenv.config(); + +async function main() { + // Hedera client setup (Testnet by default) + const client = Client.forTestnet().setOperator( + process.env.ACCOUNT_ID, + PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY) + ); + + // Prepare Hedera toolkit + const hederaAgentToolkit = new HederaLangchainToolkit({ + client, + configuration: { + tools: [], // Add specific tools here if needed, or leave empty for defaults/plugins + plugins: [], // Add plugins here + context: { + mode: AgentMode.AUTONOMOUS, + }, + }, + }); + + // Fetch tools from a toolkit + const tools = hederaAgentToolkit.getTools(); + + const llm = new ChatOpenAI({ + model: 'gpt-4o-mini', + apiKey: process.env.OPENAI_API_KEY, + }); + + // const llm = new ChatAnthropic({ + // model: 'claude-sonnet-4-5-20250929', + // apiKey: process.env.ANTHROPIC_API_KEY, + // }); + + // const llm = new ChatGroq({ + // model: 'llama-3.3-70b-versatile', + // apiKey: process.env.GROQ_API_KEY, + // }); + + // const llm = new ChatOllama({ + // model: 'llama3.1', + // baseUrl: process.env.OLLAMA_BASE_URL || 'http://127.0.0.1:11434', + // }); + + const agent = createAgent({ + model: llm, + tools: tools, + systemPrompt: 'You are a helpful assistant with access to Hedera blockchain tools', + checkpointer: new MemorySaver(), + }); + + console.log('Sending a message to the agent...'); + + const response = await agent.invoke( + { messages: [{ role: 'user', content: "what's my balance?" }] }, + { configurable: { thread_id: '1' } } + ); + + console.log(response.messages[response.messages.length - 1].content); +} + +main().catch(console.error); +``` + +> **Using a different AI provider?** You can substitute `ChatOpenAI` with other LangChain chat models like `ChatAnthropic`, `ChatGroq`, or `ChatOllama`. Install the corresponding package (e.g., `@langchain/anthropic`) and update the import accordingly. + +### 6. Run Your "Hello Hedera Agent Kit" Example + +From the root directory, run your example agent: + +```bash +node index.js +``` + +--- + +## Examples + +Clone the repository and try out different example agents. Both **LangChain v1** (recommended) and **LangChain classic** (v0.3) examples are available. + +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** - [Tool Calling Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-a-run-the-example-tool-calling-agent): Simple tasks with Hedera tools in autonomous mode +- **Option B** - [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): Complex multistep tasks (LangChain v0.3 only) +- **Option C** - [Human in the Loop Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-c-try-the-human-in-the-loop-chat-agent): Controlled workflow with RETURN_BYTES mode +- **Option D** - [MCP Server](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-d-try-out-the-mcp-server): Interact with Hedera via Claude Desktop or IDEs like Cursor +- **Option E** - [ElizaOS Agent](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/docs/DEVEXAMPLES.md#option-e-try-out-the-hedera-agent-kit-with-elizaos): Build autonomous AI agents with ElizaOS framework + +--- + +## 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 +- **npm**: [hedera-agent-kit](https://www.npmjs.com/package/hedera-agent-kit) +- **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) diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/how-to-publish-plugin.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/how-to-publish-plugin.mdx new file mode 100644 index 00000000..8639589d --- /dev/null +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/how-to-publish-plugin.mdx @@ -0,0 +1,172 @@ +--- +title: "How To: Publish & Register Your Plugin (Python)" +description: "Instructions for creating, publishing, and registering your Python Hedera Agent Kit Plugin" +--- + +## Publish and Register Your Plugin + +To create a plugin for the Python Hedera Agent Kit, you will need to create a plugin in your own repository, publish a PyPI package, and provide a description of the functionality included. + +Once you have a repository, published PyPI package, and documentation, you can add it to the Hedera Agent Kit by: + +1. Include the plugin in the [README.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/README.md) under the **Third Party Plugins** section +2. Include the same information in [docs/PLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/PLUGINS.md) + +Feel free to [reach out to the Hedera Agent Kit maintainers on Discord](https://hedera.com/discord) so we can test your plugin and promote it through our channels. + +--- + +## Plugin Interface + +Every plugin must implement the Plugin interface: + +```python +from typing import Callable, List, Optional +from hedera_agent_kit.shared.types import Tool, Context + +class Plugin: + name: str + version: Optional[str] + description: Optional[str] + tools: Callable[[Context], List[Tool]] +``` + +--- + +## Creating a Plugin + +### Step 1: Create Plugin Structure + +``` +my_custom_plugin/ +├── __init__.py # Plugin exports +├── plugin.py # Plugin definition +└── tools/ + └── my_tool.py # Individual tool implementation +``` + +### Step 2: Implement Your Tool + +```python +# tools/my_tool.py +from pydantic import BaseModel, Field +from hedera_agent_kit.shared.types import Tool, Context + +class MyToolParams(BaseModel): + required_param: str = Field(..., description="Description of required parameter") + optional_param: str = Field(None, description="Description of optional parameter") + +def my_tool_prompt(context: Context = None) -> str: + return """ + This tool performs a specific operation. + + Parameters: + - required_param (string, required): Description + - optional_param (string, optional): Description + """ + +async def my_tool_execute(client, context: Context, params: MyToolParams): + try: + # Your implementation here + result = await some_hedera_operation(params) + return result + except Exception as e: + return str(e) + +MY_TOOL = "my_tool" + +def tool(context: Context) -> Tool: + return Tool( + method=MY_TOOL, + name="My Custom Tool", + description=my_tool_prompt(context), + parameters=MyToolParams, + execute=my_tool_execute, + ) +``` + +### Step 3: Create Plugin Definition + +```python +# plugin.py +from hedera_agent_kit.shared.types import Plugin, Context +from .tools.my_tool import tool as my_tool, MY_TOOL + +my_custom_plugin = Plugin( + name="my-custom-plugin", + version="1.0.0", + description="A plugin for custom functionality", + tools=lambda context: [my_tool(context)], +) + +my_custom_plugin_tool_names = { + "MY_TOOL": MY_TOOL, +} +``` + +--- + +## Using Your Plugin + +```python +from hedera_agent_kit.langchain.toolkit import HederaLangchainToolkit +from hedera_agent_kit.shared.configuration import Configuration, Context, AgentMode +from my_custom_plugin import my_custom_plugin + +configuration = Configuration( + tools=[], + plugins=[ + my_custom_plugin, + ], + context=Context( + mode=AgentMode.AUTONOMOUS, + account_id=str(operator_id), + ), +) + +hedera_toolkit = HederaLangchainToolkit( + client=client, + configuration=configuration, +) + +tools = hedera_toolkit.get_tools() +``` + +--- + +## Plugin README Template + +```markdown +## Plugin Name + +This plugin was built by for the . It enables to + +### Installation + +'''bash +pip install +''' + +### Usage + +'''python +from my_plugin import my_custom_plugin + +configuration = Configuration( + plugins=[my_custom_plugin], + context=Context(mode=AgentMode.AUTONOMOUS), +) +''' + + +| Tool Name | Description | Usage | +|-----------|-------------|-------| +| `MY_TOOL` | What it does | How to use with parameters | +``` + +--- + +## Resources + +- **GitHub**: https://github.com/hashgraph/hedera-agent-kit-py +- **Discord**: https://hedera.com/discord diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/plugins.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/plugins.mdx new file mode 100644 index 00000000..20a7f65e --- /dev/null +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/plugins.mdx @@ -0,0 +1,169 @@ +--- +title: Plugins (Python) +description: "Plugin architecture and available tools for the Python SDK" +--- + +## Summary + +The Hedera Agent Kit provides a comprehensive set of tools organized into **plugins**, which extend the functionality of the Hedera Agent Kit SDK. These tools can be used both by the conversational agent and when you are building with the SDK. + +See the full plugin documentation: [HEDERAPLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/HEDERAPLUGINS.md) + +--- + +## Plugin Architecture + +The tools are organized into plugins, each containing related functionality: + +* **core_account_plugin**: Tools for Hedera Account Service operations +* **core_account_query_plugin**: Tools for querying Hedera Account Service data +* **core_consensus_plugin**: Tools for Hedera Consensus Service (HCS) operations +* **core_consensus_query_plugin**: Tools for querying HCS data +* **core_token_plugin**: Tools for Hedera Token Service (HTS) operations +* **core_token_query_plugin**: Tools for querying HTS data +* **core_evm_plugin**: Tools for interacting with EVM smart contracts (ERC-20, ERC-721) +* **core_misc_query_plugin**: Tools for miscellaneous queries +* **core_transaction_query_plugin**: Tools for transaction-related queries + +--- + +## Available Plugins and Tools + +### Core Account Plugin (`core_account_plugin`) + +Tools for Hedera **Account Service operations**: + +| Tool Name | Description | +|-----------------------------------------|------------------------------------| +| `TRANSFER_HBAR_TOOL` | Transfer HBAR between accounts | +| `APPROVE_HBAR_ALLOWANCE_TOOL` | Approve an HBAR spending allowance | +| `DELETE_HBAR_ALLOWANCE_TOOL` | Delete an HBAR allowance | +| `TRANSFER_HBAR_WITH_ALLOWANCE_TOOL` | Transfer HBAR using an allowance | +| `CREATE_ACCOUNT_TOOL` | Create a new Hedera account | +| `UPDATE_ACCOUNT_TOOL` | Update an account's metadata | +| `DELETE_ACCOUNT_TOOL` | Delete an account | +| `SCHEDULE_DELETE_TOOL` | Delete a scheduled transaction | +| `APPROVE_FUNGIBLE_TOKEN_ALLOWANCE_TOOL` | Approve token spending allowances | +| `APPROVE_NFT_ALLOWANCE_TOOL` | Approve NFT allowances | + +--- + +### Core Account Query Plugin (`core_account_query_plugin`) + +Tools for querying **Account Service** data: + +| Tool Name | Description | +|-----------|-------------| +| `GET_ACCOUNT_QUERY_TOOL` | Returns comprehensive account information | +| `GET_HBAR_BALANCE_QUERY_TOOL` | Returns the HBAR balance for an account | +| `GET_ACCOUNT_TOKEN_BALANCES_QUERY_TOOL` | Returns token balances for an account | + +--- + +### Core Consensus Plugin (`core_consensus_plugin`) + +Tools for **Consensus Service (HCS)** operations: + +| Tool Name | Description | +|-----------|-------------| +| `CREATE_TOPIC_TOOL` | Create a new topic | +| `SUBMIT_TOPIC_MESSAGE_TOOL` | Submit a message to a topic | +| `DELETE_TOPIC_TOOL` | Delete a topic | +| `UPDATE_TOPIC_TOOL` | Update a topic | + +--- + +### Core Token Plugin (`core_token_plugin`) + +Tools for **Token Service (HTS)** operations: + +| Tool Name | Description | +|-----------|-------------| +| `CREATE_FUNGIBLE_TOKEN_TOOL` | Creates a fungible token | +| `CREATE_NON_FUNGIBLE_TOKEN_TOOL` | Creates an NFT collection | +| `MINT_FUNGIBLE_TOKEN_TOOL` | Mints additional fungible tokens | +| `MINT_NON_FUNGIBLE_TOKEN_TOOL` | Mints NFTs with metadata | +| `ASSOCIATE_TOKEN_TOOL` | Associates tokens with an account | +| `DISSOCIATE_TOKEN_TOOL` | Dissociates tokens from an account | +| `AIRDROP_FUNGIBLE_TOKEN_TOOL` | Airdrops tokens to recipients | +| `TRANSFER_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL` | Transfers tokens using allowance | + +--- + +### Core EVM Plugin (`core_evm_plugin`) + +Tools for **EVM smart contract** operations: + +| Tool Name | Description | +|-----------|-------------| +| `CREATE_ERC20_TOOL` | Deploys an ERC-20 token | +| `TRANSFER_ERC20_TOOL` | Transfers an ERC-20 token | +| `CREATE_ERC721_TOOL` | Deploys an ERC-721 token | +| `MINT_ERC721_TOOL` | Mints an ERC-721 token | +| `TRANSFER_ERC721_TOOL` | Transfers an ERC-721 token | + +--- + +## Using Hedera Plugins in Python + +First, import the plugins you need: + +```python +from hedera_agent_kit.plugins import ( + core_account_plugin, + core_account_query_plugin, + core_consensus_plugin, + core_token_plugin, + core_evm_plugin, +) +from hedera_agent_kit.shared.configuration import AgentMode, Context, Configuration +``` + +Then instantiate the toolkit with your configuration: + +```python +from hedera_agent_kit.langchain.toolkit import HederaLangchainToolkit + +configuration = Configuration( + tools=[], # Empty = load all tools from plugins + context=Context( + mode=AgentMode.AUTONOMOUS, + account_id=str(operator_id), + ), + plugins=[ + core_account_plugin, + core_account_query_plugin, + core_consensus_plugin, + core_token_plugin, + core_evm_plugin, + ], +) + +hedera_toolkit = HederaLangchainToolkit( + client=client, + configuration=configuration, +) + +# Get the tools for use with LangChain +tools = hedera_toolkit.get_tools() +``` + +--- + +## Agent Modes + +The Python SDK currently supports one agent mode: + +| Mode | Description | +|------------------------|----------------------------------------------------------------| +| `AgentMode.AUTONOMOUS` | The agent executes transactions directly on the Hedera network | + +> **Coming Soon:** `AgentMode.RETURN_BYTES` - In this mode, the agent creates the transaction and returns the bytes for the user to execute. + +--- + +## Resources + +- **GitHub**: https://github.com/hashgraph/hedera-agent-kit-py +- **Plugins Documentation**: [HEDERAPLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/HEDERAPLUGINS.md) +- **Tools Documentation**: [HEDERATOOLS.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/HEDERATOOLS.md) diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/quickstart.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/quickstart.mdx new file mode 100644 index 00000000..92606c29 --- /dev/null +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/hedera-agent-kit-py/quickstart.mdx @@ -0,0 +1,274 @@ +--- +title: "Quickstart (Python)" +description: "Get started with the Hedera Agent Kit using Python" +--- + +## Overview + +Build LLM-powered applications that interact with the Hedera Network using Python. 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. + +This is the **Python edition** of the [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit-py), providing a flexible and extensible framework for building AI-powered Hedera agents. + +> **Note**: See also the [JavaScript SDK documentation](/hedera/open-source-solutions/ai-studio-on-hedera/hedera-agent-kit-js) for the JS/TypeScript version. + +The Hedera Agent Kit (Python) provides: + +- **Plugin Architecture**: Extensible design for easy customization +- **LangChain Integration**: Support for LangChain v1 and LangChain Classic +- **Comprehensive Hedera Tools**: Token creation (HTS), smart contracts (EVM), account operations, topics (HCS), and more +- **Autonomous Execution**: Direct transaction execution on the Hedera network + +--- + +## Quickstart — Create a Hedera Agent + +See the PyPI package at: https://pypi.org/project/hedera-agent-kit/ + +### 1. Create your project directory + +```bash +mkdir hello-hedera-agent-kit +cd hello-hedera-agent-kit +``` + +### 2. Set up virtual environment and install dependencies + +Create and activate a virtual environment: + +```bash +python3 -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate +``` + +Install dependencies: + +```bash +pip install hedera-agent-kit langchain langchain-openai python-dotenv +``` + +### 3. Install ONE of these AI provider packages + +```bash +# Option 1: OpenAI (requires API key) +# for Langchain classic +pip install langchain-classic langchain-openai + +# for LangChain v1 +pip install langchain langchain-openai + +# Option 2: Anthropic Claude (requires API key) +# for LangChain classic +pip install langchain-classic langchain-anthropic + +# for LangChain v1 +pip install langchain langchain-anthropic + +# Option 3: Groq (free tier available) +# for Langchain classic +pip install langchain-classic langchain-groq + +# for LangChain v1 +pip install langchain langchain-groq + +# Option 4: Ollama (100% free, runs locally) +# for Langchain classic +pip install langchain-classic langchain-ollama + +# for LangChain v1 +pip install langchain langchain-ollama +``` + + + The example below uses OpenAI and is written for LangChain V1 (Python). It does not use the older LangChain “classic” API. If you want to use a different model provider (Anthropic, Groq, Ollama, etc.), check the LangChain Python integrations docs [here](https://docs.langchain.com/oss/python/integrations/chat). + + For the LangChain classic example code, refer to the example in the [Hedera Agent Kit (Python) repo](https://github.com/hashgraph/hedera-agent-kit-py/tree/main/python/examples/langchain-classic). + + +### 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) +ACCOUNT_ID="0.0.xxxxx" +PRIVATE_KEY="303..." # 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 + +Create a `main.py` file: + +```bash +touch main.py +``` + +```python main.py +# main.py +import asyncio +import os + +from dotenv import load_dotenv +from hedera_agent_kit.langchain.toolkit import HederaLangchainToolkit +from hedera_agent_kit.plugins import ( + core_account_plugin, + core_account_query_plugin, + core_token_plugin, + core_consensus_plugin, +) +from hedera_agent_kit.shared.configuration import Configuration, Context, AgentMode +from hiero_sdk_python import Client, Network, AccountId, PrivateKey +from langchain.agents import create_agent +from langchain_openai import ChatOpenAI +from langgraph.checkpoint.memory import MemorySaver + +load_dotenv() + + +async def main(): + # Hedera client setup (Testnet by default) + import asyncio + account_id = AccountId.from_string(os.getenv("ACCOUNT_ID")) + private_key = PrivateKey.from_string(os.getenv("PRIVATE_KEY")) + client = Client(Network(network="testnet")) + client.set_operator(account_id, private_key) + + # Prepare Hedera toolkit + hedera_toolkit = HederaLangchainToolkit( + client=client, + configuration=Configuration( + tools=[], # Empty = load all tools from plugins + plugins=[ + core_account_plugin, + core_account_query_plugin, + core_token_plugin, + core_consensus_plugin, + ], + context=Context( + mode=AgentMode.AUTONOMOUS, + account_id=str(account_id), + ), + ), + ) + + tools = hedera_toolkit.get_tools() + + llm = ChatOpenAI( + model="gpt-4o-mini", + api_key=os.getenv("OPENAI_API_KEY"), + ) + + agent = create_agent( + model=llm, + tools=tools, + checkpointer=MemorySaver(), + system_prompt="You are a helpful assistant with access to Hedera blockchain tools and plugin tools", + ) + + print("Sending a message to the agent...") + + response = await agent.ainvoke( + {"messages": [{"role": "user", "content": "what's my balance?"}]}, + config={"configurable": {"thread_id": "1"}}, + ) + + final_message_content = response["messages"][-1].content + print("\n--- Agent Response ---") + print(final_message_content) + print("----------------------") + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +> **Using a different AI provider?** You can substitute `ChatOpenAI` with other LangChain chat models like `ChatAnthropic`, `ChatGroq`, or `ChatOllama`. Install the corresponding package and update the import accordingly. + +### 6. Run Your "Hello Hedera Agent Kit" Example + +From the root directory, run your example agent: + +```bash +python3 main.py +``` + +--- + +## Examples + +Clone the repository and try out different example agents. Both **LangChain v1** (recommended) and **LangChain Classic** (v0.3) examples are available. + +See the full [Developer Examples](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/DEVEXAMPLES.md) documentation for detailed setup instructions. + +**Available Examples:** + +- **Option A** - [Plugin Tool Calling Agent (LangChain v1)](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/DEVEXAMPLES.md#option-a-run-the-plugin-tool-calling-agent-langchain-v1): Uses LangGraph with plugin-based tool management +- **Option B** - [Tool Calling Agent (LangChain Classic)](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/DEVEXAMPLES.md#option-b-run-the-tool-calling-agent-langchain-classic): Basic tool-calling with LangChain Classic +- **Option C** - [Plugin Tool Calling Agent (LangChain Classic)](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/DEVEXAMPLES.md#option-c-run-the-plugin-tool-calling-agent-langchain-classic): Plugin-based agent with LangChain Classic +- **Option D** - [Structured Chat Agent (LangChain Classic)](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/DEVEXAMPLES.md#option-d-run-the-structured-chat-agent-langchain-classic): Structured chat with LangChain Classic + +--- + +## About the Agent Kit + +### Agent Execution Modes + +The Python SDK currently supports one execution mode: + +| Mode | Status | Description | +|--------------------------|----------------|-----------------------------------------------------------------| +| `AgentMode.AUTONOMOUS` | ✅ Supported | Transactions are executed directly using the operator account | +| `AgentMode.RETURN_BYTES` | 🔜 Coming Soon | Transaction bytes returned for user signing (human-in-the-loop) | + +--- + +## Agent Kit Plugins + +The Hedera Agent Kit provides tools organized into **plugins** by the type of Hedera service they interact with. + +**Available Plugins** + +| Plugin | Description | +|-----------------------------------|---------------------------------------------------------------------------------------------------------------| +| **core_account_plugin** | Tools for Hedera Account Service operations (transfer HBAR, create/update/delete accounts, manage allowances) | +| **core_account_query_plugin** | Tools for querying account data (balances, account info, token balances) | +| **core_consensus_plugin** | Tools for Hedera Consensus Service (HCS) operations (create/update/delete topics, submit messages) | +| **core_consensus_query_plugin** | Tools for querying HCS data (topic messages, topic info) | +| **core_token_plugin** | Tools for Hedera Token Service (HTS) operations (create/mint/transfer tokens, manage allowances) | +| **core_token_query_plugin** | Tools for querying HTS data (token info, pending airdrops) | +| **core_evm_plugin** | Tools for interacting with EVM smart contracts (ERC-20, ERC-721 tokens) | +| **core_misc_query_plugin** | Tools for miscellaneous queries (exchange rates) | +| **core_transaction_query_plugin** | Tools for transaction-related queries (get transaction records) | + +See the full plugin documentation: [HEDERAPLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/HEDERAPLUGINS.md) + +--- + +## Requests and Contributions + +**To request additional functionality**, please [open an issue](https://github.com/hashgraph/hedera-agent-kit-py/issues). + +**To contribute** to the Hedera Agent Kit (Python), see the repository's contributing guidelines. + +--- + +## Resources + +- **GitHub**: https://github.com/hashgraph/hedera-agent-kit-py +- **PyPI**: [hedera-agent-kit](https://pypi.org/project/hedera-agent-kit/) +- **Issues**: https://github.com/hashgraph/hedera-agent-kit-py/issues +- **Developer Examples**: [DEVEXAMPLES.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/DEVEXAMPLES.md) +- **Plugins Documentation**: [HEDERAPLUGINS.md](https://github.com/hashgraph/hedera-agent-kit-py/blob/main/docs/HEDERAPLUGINS.md)