The convergence of artificial intelligence and blockchain technology has long been a subject of intense speculation and theoretical discussion, promising a future where autonomous agents could operate with unprecedented trust and efficiency on decentralized networks. Until recently, however, the practical tools needed to build these sophisticated systems have been fragmented and complex, leaving developers to bridge a significant gap between AI frameworks and distributed ledgers. The introduction of a dedicated Python SDK for the Hedera Agent Kit marks a pivotal shift, moving this concept from the realm of possibility into tangible reality. As Python is the undisputed lingua franca of AI and machine learning, its integration provides a natural and powerful pathway for a vast community of developers to create intelligent agents capable of executing crypto payments, managing digital assets, and interacting with smart contracts. This development is not merely an incremental update; it represents a foundational piece of infrastructure designed to unlock new paradigms in permissionless transactions and automated on-chain governance, powered by the synergy of AI’s decision-making prowess and blockchain’s immutable record-keeping. The SDK’s integration with established frameworks like LangChain further lowers the barrier to entry, ensuring that developers can leverage familiar tools while exploring this new frontier.
1. Understanding the Hedera Agent Kit Framework
The Hedera Agent Kit is an open-source framework meticulously engineered to serve as the essential bridge between artificial intelligence agents and the Hedera public network. Its fundamental purpose is to empower developers to build applications where AI can interact directly and autonomously with a distributed ledger, performing a wide range of on-chain actions that traditionally require human intervention. The framework achieves this through a sophisticated plugin system, which provides neatly packaged sets of Hedera functionalities. These functionalities are comprehensive, covering everything from basic account operations—such as creating accounts and transferring HBAR—to more advanced capabilities like token creation and management via the Hedera Token Service (HTS). Furthermore, the kit enables agents to work with the Hedera Consensus Service (HCS), allowing them to publish immutable, verifiable records in the form of topics, a feature critical for applications requiring tamper-proof logging or messaging. It also includes tools for smart contract execution within the Ethereum Virtual Machine (EVM) environment supported by Hedera, giving AI agents the ability to interact with the vast world of decentralized applications. By providing these tools, the Hedera Agent Kit allows developers to bestow their AI creations with the unique capabilities of the Hedera network, leveraging its high speed, low cost, and robust security to build a new generation of intelligent, decentralized systems.
At the core of the Hedera Agent Kit’s design is a modular and extensible plugin architecture that promotes both simplicity and customization. This architecture is designed to keep functionality compartmentalized, allowing developers to selectively include only the tools their agent requires for a specific task. This approach not only streamlines the development process but also results in more efficient and lightweight applications. Each plugin bundles a set of related tools, making it straightforward to integrate specific capabilities. For instance, the Core Account Plugin handles HBAR transfers and account management, while the Core Token Plugin manages the entire lifecycle of fungible and non-fungible tokens. Similarly, the Core Consensus Plugin is dedicated to topic creation and message submission, and the Core EVM Plugin facilitates interaction with ERC-20 and ERC-721 tokens. To round out these capabilities, Core Query Plugins provide agents with the ability to read on-chain data, such as account balances, token information, and transaction records. This granular control means developers are not burdened with unnecessary code and can even build their own custom plugins to address highly specialized use cases, making the framework a versatile foundation for a wide array of AI-powered blockchain applications.
2. Key Features and Capabilities of the Python Sdk
The release of the Python SDK brings a host of powerful features tailored to the needs of the AI development community, significantly enhancing the accessibility and utility of the Hedera Agent Kit. A standout feature is its seamless integration with LangChain v1.0, a move that unifies the LangChain and LangGraph libraries into a single, streamlined SDK. This integration ensures forward compatibility and provides a more cohesive and consistent development experience, allowing Python developers to build sophisticated AI agents on Hedera using a familiar and powerful framework. Another crucial aspect of the SDK is its flexibility regarding AI providers. Recognizing that different projects have varying requirements and budgets, the SDK supports a range of leading AI models. Developers can use Ollama to run models locally without the need for an API key, making it ideal for prototyping and development. For those needing more power, Groq offers a generous free tier with high-speed inference, while industry standards like OpenAI and Claude are available for production-level workloads that demand maximum performance and reliability. This provider-agnostic approach empowers developers to select the optimal AI engine for their specific application, whether they are building a small-scale proof-of-concept or a large-scale enterprise solution.
Further enhancing its versatility, the Python SDK supports distinct execution modes designed to accommodate different security and workflow requirements. The primary mode is Autonomous mode, in which the agent is granted the authority to execute transactions directly on the network using a pre-configured operator account. This mode is ideal for fully automated systems where the agent is trusted to perform actions like managing token distributions or executing transfers based on predefined rules without human oversight. In contrast, the SDK is set to introduce a Return Bytes mode. This forthcoming mode will function differently; instead of executing a transaction, the agent will return the raw, unsigned transaction bytes. This allows a user or an external system to review the transaction details, sign it, and then submit it to the network. The Return Bytes mode is invaluable for applications that demand an additional layer of approval or involve external signing workflows, such as multi-signature wallets or enterprise systems where financial controls and human verification are paramount. By offering both fully autonomous and supervised execution pathways, the SDK provides the necessary flexibility to build applications that are not only intelligent and efficient but also secure and compliant with diverse operational protocols.
3. Exploring Practical Applications and Use Cases
The Hedera Agent Kit opens a vast landscape of possibilities for creating innovative, AI-powered applications that leverage the unique strengths of a distributed ledger. One of the most compelling use cases lies in creating sophisticated treasury and payment agents. Imagine an AI agent tasked with managing a corporate or decentralized autonomous organization (DAO) treasury. This agent could monitor account balances in real-time, execute HBAR transfers to pay vendors or employees, and manage complex token distribution schedules based on predefined rules or even natural language instructions. For instance, a project manager could simply instruct the agent, “Airdrop 1,000 community tokens to all addresses that completed the beta testing quest,” and the agent would handle the entire process autonomously. Another powerful application is the development of advanced token management bots. These agents could automate the complete lifecycle of digital assets, from the creation and minting of fungible or non-fungible tokens to their distribution. An agent could be programmed to manage token allowances, respond to user requests for new asset issuance, or conduct airdrops to reward community engagement, all while ensuring every transaction is securely recorded on the Hedera network.
Beyond financial applications, the SDK enables the creation of robust on-chain messaging and data logging systems. By utilizing the Consensus Service plugins, developers can build agents that post immutable updates to public topics, log critical events for auditing purposes, or coordinate complex workflows between multiple decentralized systems. This could be applied to supply chain management, where an agent logs the provenance of goods at each step, or in decentralized identity systems, where an agent records verifiable credentials. Furthermore, the ability to interact with smart contracts opens another dimension of possibilities. An AI agent could serve as an intelligent interface for complex DeFi protocols, abstracting away the technical details of direct contract calls and allowing users to interact with decentralized exchanges or lending platforms through simple commands. This could significantly lower the barrier to entry for mainstream users. Finally, developers can build powerful monitoring and reporting tools. These agents could continuously query account balances, token holdings, and transaction histories, then summarize this data or trigger alerts based on specific conditions. For example, an agent could monitor a wallet for suspicious activity or generate real-time reports on the tokenomics of a project, providing valuable insights that would be difficult to obtain through manual processes.
4. A Quick Start Guide to Building Your First Agent
This walkthrough will guide you through the process of getting a Hedera-powered AI agent operational in approximately one minute, demonstrating the simplicity and power of the new Python SDK.
1. Project Setup
First, create a directory for your project and navigate into it. Then, establish and activate a virtual environment to manage your dependencies cleanly. mkdir hello-hedera-agent-kit cd hello-hedera-agent-kit python -m venv .venv source .venv/bin/activate
With the environment active, install the necessary libraries using pip. You will need the core agent kit, LangChain components, and a library to handle environment variables. pip install hedera-agent-kit langchain langchain-openai langgraph python-dotenv
Finally, install the specific package for your chosen AI provider. You only need to install one of the following. pip install langchain langchain-openai pip install langchain langchain-anthropic pip install langchain langchain-groq pip install langchain-classic langchain-ollama
2. Configure Environment Variables
Create a file named .env in the root of your project directory. This file will securely store your credentials. ACCOUNT_ID="0.0.xxxxx" PRIVATE_KEY="0x..." OPENAI_API_KEY="sk-proj-..." ANTHROPIC_API_KEY="sk-ant-..." GROQ_API_KEY="gsk_..."
You must provide your Hedera testnet ACCOUNT_ID and PRIVATE_KEY. If you do not have a testnet account, you can create one for free. Add the API key corresponding to the AI provider you installed in the previous step. Ollama does not require an API key as it runs locally.
3. Create Your Agent
Create a new file named main.py in your project directory. Add the following code, which sets up the Hedera client, prepares the toolkit with the core plugins, initializes the LLM with your API key, and creates an agent capable of using the Hedera tools. # 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_core.runnables import RunnableConfig from langchain_openai import ChatOpenAI from langgraph.checkpoint.memory import MemorySaver
load_dotenv()
async def main(): 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)
hedera_toolkit = HederaLangchainToolkit( client=client, configuration=Configuration( tools=[], 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())
4. Run Your Agent
Execute the script from your terminal. python main.py
5. Try Other Prompts
Once the agent is running and you have confirmed it can check your balance, experiment by changing the “content” of the user message in main.py to explore its other capabilities. response = await agent.ainvoke( {"messages": [{"role": "user", "content": "create a new token called 'TestToken' with symbol 'TEST'"}]}, config={"configurable": {"thread_id": "1"}}, )
response = await agent.ainvoke( {"messages": [{"role": "user", "content": "transfer 5 HBAR to account 0.0.1234"}]}, config={"configurable": {"thread_id": "1"}}, )
response = await agent.ainvoke( {"messages": [{"role": "user", "content": "create a new topic for project updates"}]}, config={"configurable": {"thread_id": "1"}}, )
5. The Path Forward for Decentralized Ai
The introduction of the Hedera Agent Kit for Python represented a significant milestone in the journey toward creating truly decentralized, intelligent systems. By providing a robust, open-source bridge between the world’s most popular AI development language and a high-performance distributed ledger, this toolkit equipped developers with the practical means to move beyond theoretical concepts and begin building functional applications. The modular plugin architecture proved to be a critical design choice, as it offered the flexibility needed to construct agents tailored for specific tasks, from simple payment automation to complex token management. This development effectively democratized access to a new frontier of technology, inviting a global community of innovators to contribute, experiment, and build upon a common foundation. The framework’s launch did not just provide a set of tools; it fostered an ecosystem where the cognitive abilities of AI could be securely and transparently anchored to the immutable trust of a blockchain. The collaborative nature of the project, encouraging contributions and the creation of new plugins, ensured that its capabilities would continue to evolve, addressing the ever-expanding needs of a rapidly advancing field and setting a new precedent for how autonomous on-chain entities could be developed and deployed.
