Introducing the Python SDK for the Hedera Agent Kit

Introducing the Python SDK for the Hedera Agent Kit, bringing extended programmability for a broader developer base looking to explore the intersection of AI and blockchain.

The Python SDK is a follow-up to the JavaScript SDK that enables developers to choose their AI framework: LangChain, Vercel, or MCP to build agents that can interact with Hedera Testnet. With this SDK, developers can build agents with the power to make crypto payments, enabling new types of permissionless and micro-transactions that would be difficult for an AI agent to do without blockchain. Since Python is the go-to language for AI development as it has many libraries and integration built especially for AI and Machine Learning, a Python SDK was the natural next step in the AI Studio set of tools.

The Python SDK also integrates with LangChain v1.0, which unifies LangChain and LangGraph into a single, streamlined SDK. This ensures forward compatibility and a more consistent developer experience for Python developers building AI agents on Hedera.

Let’s explore what’s new with the launch of this new SDK!

What is the Hedera Agent Kit?

The Hedera Agent Kit is an open-source framework for building AI agents that can interact directly with the Hedera network. It provides a plugins that enable developers to easily bring in sets of Hedera functionality such as basic account operations for creating accounts and doing transactions, token creation and management (HTS), work with the Consensus service where users can publish immutable records in the form of topics (HCS), and smart contract execution (EVM). Developers can use these tools to give their agents the ability to do everything on the Hedera network, taking advantage of the unique capabilities of Hedera.

Key features of the Python SDK

The Python SDK is built around a plugin architecture that keeps functionality modular and extensible. Each plugin bundles related tools together, making it straightforward to include only what you need or to build custom plugins for your specific use case.

Available Plugins

Core Account Plugin

• Transfer HBAR
• Create, update, and delete accounts
• Approve and delete allowances

Core Token Plugin (HTS)

• Create fungible and non-fungible tokens
• Mint, associate, and dissociate tokens
• Airdrop fungible tokens
• Transfer tokens using allowances

Core Consensus Plugin (HCS)

• Create, update, and delete topics
• Submit messages to topics

Core EVM Plugin

• Create and transfer ERC-20 tokens
• Create and transfer ERC-721 tokens

Core Query Plugins

• Get account info and HBAR balances
• Get token info and balances
• Get topic info
• Get transaction records
• Get exchange rates

AI Provider Flexibility

The SDK works with a range of AI providers, so developers can choose what fits their needs and budget. Ollama runs locally with no API key required. Groq offers a generous free tier. OpenAI and Claude are available for production workloads.

Execution Modes

Two modes are supported. In Autonomous mode, the agent executes transactions directly using the configured operator account. Return Bytes mode (coming soon) will return the raw transaction bytes, allowing users to review, sign, and submit transactions themselves — useful for applications that require additional approval steps or external signing workflows.

What Can You Build?

The Hedera Agent Kit opens up a range of possibilities for AI-powered applications. Here are a few examples of what developers can build:

Treasury and Payment Agents An agent that monitors balances, executes HBAR transfers, and manages token distributions based on predefined rules or natural language instructions.

Token Management Bots Automate the creation, minting, and distribution of fungible or non-fungible tokens. An agent could handle airdrops, manage allowances, or respond to user requests to issue new assets.

On-Chain Messaging Systems Use the Consensus Service plugins to build agents that post updates to topics, log events, or coordinate between systems using Hedera’s tamper-proof message ordering.

Smart Contract Interfaces Deploy ERC-20 or ERC-721 contracts and let an agent handle transfers, queries, and interactions — abstracting away the complexity of direct contract calls.

Monitoring and Reporting Tools Build agents that query account balances, token holdings, and transaction history, then summarize or act on that data in real time.

These are starting points. The plugin architecture means developers can combine tools, add custom logic, and extend the kit to fit more specialized workflows.

Getting started in under a minute

The following walkthrough will have you running a Hedera-powered AI agent in about 60 seconds.

1. Project Setup

Create a directory for your project and navigate into it:

mkdir hello-hedera-agent-kit
cd hello-hedera-agent-kit

# Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the required dependencies:
pip install hedera-agent-kit langchain langchain-openai langgraph python-dotenv

# Install ONE of these AI provider packages
# for OpenAI
pip install langchain langchain-openai

# for Claude
pip install langchain langchain-anthropic

# for Groq
pip install langchain langchain-groq

# for Ollama
pip install langchain-classic langchain-ollama

2. Configure Environment Variables

Create a .env file in your project’s root directory:

touch .env

If you already have a testnet account, you can use it. Otherwise, you can create a new one for free using the following link.

Add the following configuration, adding in the API Key for the LLM provider you will use:

# Required: Hedera credentials
ACCOUNT_ID="0.0.xxxxx"
PRIVATE_KEY="0x..."

# Optional: Add the API key for your chosen AI provider
OPENAI_API_KEY="sk-proj-..."     # For OpenAI
ANTHROPIC_API_KEY="sk-ant-..."   # For Claude
GROQ_API_KEY="gsk_..."           # For Groq (free tier)

# Ollama doesn't need an API key (runs locally)

If you don’t have a Hedera testnet account, you can create one for free at portal.hedera.com.

3. Create Your Agent

Create a new file called main.py:

touch main.py

Add the following code to create an Agent with Langchain v1.0:

# 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():
    # Hedera client setup (Testnet by default)
    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())

4. Run Your Agent

From the root directory, run:

python main.py

5. Try Other Prompts

Once your agent is running, experiment with different prompts to explore its 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"}},
)

For additional examples and more advanced chat-like agent implementations, visit the examples directory in the repository.

Get Involved

The Hedera Agent Kit for Python is open source and available now. Here’s how to get started:

• Try it out: Clone the repository at github.com/hashgraph/hedera-agent-kit-py
• Get a testnet account: Sign up for free at portal.hedera.com
• Contribute: Open an issue, submit a pull request, or build your own plugins
• Read the docs:

— See docs/HEDERAPLUGINS.md for the full plugin catalogue and usage examples

— See docs/HEDERATOOLS.md for detailed parameter specifications and example prompts for all tools in the Hedera Agent Kit.

Want to add more functionality from Hedera services? Open an issue and let us know what you’d like to see.

Resources

Hedera Agent Kit documentation: docs.hedera.com/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit

Hedera AI Studio: https://hedera.com/ai-studio

Introducing the Python SDK for the Hedera Agent Kit was originally published in Hedera Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.