Hedera Agent Kit (Python)

Build Hedera-powered AI agents in under a minute.

📋 Contents

• Key Features
• About the Agent Kit Functionality
• Third Party Plugins
• Framework Adapters
• Developer Examples
• 🚀 60-Second Quick-Start
• Agent Execution Modes
• Hedera Plugins & Tools
• Creating Plugins & Contributing
• License
• Credits

---

Key Features

This is the Python edition of the Hedera Agent Kit, providing a flexible and extensible framework for building AI-powered Hedera agents.

• 🔌 Plugin architecture for easy extensibility
• 🧩 Framework adapters for LangChain, Google ADK, and MCP (Model Context Protocol) — expose the same Hedera tools to any of them (see Framework Adapters)
• 🪙 Comprehensive Hedera tools, including:
  • Token creation and management (HTS)
  • Smart contract execution (EVM)
  • Account operations
  • Topic (HCS) creation and messaging
  • Transaction scheduling
  • Allowances and approvals

---

Agent Kit Functionality

The list of currently available Hedera plugins and functionality can be found in the Plugins & Tools section of this page.

👉 See docs/HEDERAPLUGINS.md for the full catalogue & usage examples.

Want to add more functionality from Hedera Services? Open an issue!

---

Third Party Plugins

The Hedera Agent Kit is extensible with third party plugins by other projects. See how you can build and submit your own plugin to listed as a Hedera Agent Kit plugin in Hedera Docs and README in docs/PLUGINS.md

---

Framework Adapters

The Hedera Agent Kit exposes the same set of Hedera tools and plugins through a dedicated adapter (toolkit) for each supported framework. Every toolkit takes the same (client, configuration) arguments, so you can switch frameworks — or run several at once — without changing your tool/plugin configuration.

Framework	Toolkit	Import
LangChain	HederaLangchainToolkit	from hedera_agent_kit.langchain.toolkit import HederaLangchainToolkit
Google ADK	HederaADKToolkit	from hedera_agent_kit.adk.toolkit import HederaADKToolkit
MCP (Model Context Protocol)	HederaMCPToolkit	from hedera_agent_kit.mcp import HederaMCPToolkit

LangChain Adapter

HederaLangchainToolkit exposes the Hedera tools as LangChain BaseTools via get_tools(), ready to pass to any LangChain agent. It supports both LangChain v1 and LangChain Classic:

from hedera_agent_kit.langchain.toolkit import HederaLangchainToolkit
# ... build `client` and `configuration` the same way as in the Quick-Start above ...

hedera_toolkit = HederaLangchainToolkit(client, configuration)
tools = hedera_toolkit.get_tools()  # plug into create_agent(...) / AgentExecutor

• Adapter source: python/hedera_agent_kit/langchain/toolkit.py
• Examples: LangChain v1 · LangChain Classic

Google ADK Adapter

HederaADKToolkit exposes the Hedera tools as Google ADK BaseTools via get_tools(), ready to pass to an ADK Agent:

from hedera_agent_kit.adk.toolkit import HederaADKToolkit
# ... build `client` and `configuration` the same way as in the Quick-Start above ...

hedera_toolkit = HederaADKToolkit(client, configuration)
tools = hedera_toolkit.get_tools()  # plug into google.adk.agents.Agent(tools=tools)

• Adapter source: python/hedera_agent_kit/adk/toolkit.py
• Examples: Google ADK

MCP (Model Context Protocol) Adapter

HederaMCPToolkit turns your configured Hedera tools into a fully functional MCP server, so any MCP-compatible client (Antigravity, VS Code, Claude Desktop, etc.) can call them as tools:

from hedera_agent_kit.mcp import HederaMCPToolkit
# ... build `client` and `configuration` the same way as in the Quick-Start above ...

server = HederaMCPToolkit(client, configuration)
server.run()  # serves the Hedera tools over stdio as an MCP server

• Ready-to-run server & MCP client configuration (Antigravity / VS Code): modelcontextprotocol/
• Adapter source: python/hedera_agent_kit/mcp/toolkit.py

Note: this MCP adapter exposes the Agent Kit's tools as an MCP server. If instead you want an agent that consumes external MCP servers, see the Preconfigured MCPs Agent example.

---

Developer Examples

You can try out examples of the different types of agents you can build by following the instructions in the Developer Examples doc in this repo.

First follow instructions in the Developer Examples to clone and configure the example, then choose from one of the examples to run:

• Option A - Plugin Tool Calling Agent (LangChain v1)
• Option B - Tool Calling Agent (LangChain Classic)
• Option C - Plugin Tool Calling Agent (LangChain Classic)
• Option D - Structured Chat Agent (LangChain Classic)
• Option E - Preconfigured MCPs Agent (LangChain v1)
• Option F - Plugin Tool Calling Agent (Google ADK)
• Option G - Return Bytes Mode Agents (ADK & LangChain)

---

🚀 60-Second Quick-Start

See more info at https://pypi.org/project/hedera-agent-kit/

🆓 Free AI Options Available!

• Ollama: 100% free, runs on your computer, no API key needed
• Groq: Offers generous free tier with API key
• Claude & OpenAI: Paid options for production use

1 – Project Setup

Create a directory for your project:

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 dependencies:

pip install hedera-agent-kit langchain langchain-openai langgraph python-dotenv

2 – Configure: Add Environment Variables

Create an .env file in the root directory of your project:

touch .env

If you already have a testnet account, you can use it. Otherwise, you can create a new one at https://portal.hedera.com/dashboard

Add the following to the .env file:

# Required: Hedera credentials (get free testnet account at https://portal.hedera.com/dashboard)
ACCOUNT_ID="0.0.xxxxx"
PRIVATE_KEY="302..." # DER encoded private key (e.g. from Hedera Portal)

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

NOTE: Using Hex Encoded Keys (ECDSA/ED25519)? The PrivateKey.from_string() method used in the examples expects a DER encoded key string. If you are using a hex encoded private key (common in some wallets), you should update the code to use the specific factory method:

• PrivateKey.from_ed25519(bytes.fromhex(os.getenv("PRIVATE_KEY")))
• PrivateKey.from_ecdsa(bytes.fromhex(os.getenv("PRIVATE_KEY")))

3 – Simple "Hello Hedera Agent Kit" Example

Create a new file called main.py:

touch main.py

Add the following code:

# 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 "Hello Hedera Agent Kit" Example

From the root directory, run your example agent:

python main.py

If you would like, try adding in other prompts to the agent to see what it can do:

# original
response = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "what's my balance?"}]},
    config={"configurable": {"thread_id": "1"}},
)

# or
response = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "create a new token called 'TestToken' with symbol 'TEST'"}]},
    config={"configurable": {"thread_id": "1"}},
)

# or
response = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "transfer 5 HBAR to account 0.0.1234"}]},
    config={"configurable": {"thread_id": "1"}},
)

# or
response = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "create a new topic for project updates"}]},
    config={"configurable": {"thread_id": "1"}},
)

To get other Hedera Agent Kit tools working, take a look at the example agent implementations at https://github.com/hashgraph/hedera-agent-kit-py/tree/main/python/examples

---

About the Agent Kit

Agent Execution Modes

This tool has two execution modes with AI agents; autonomous execution and return bytes:

Mode	Description
AgentMode.AUTONOMOUS	The transaction will be executed autonomously using the operator account.
AgentMode.RETURN_BYTES	The transaction bytes will be returned for the user to sign and execute.

Hedera Plugins & Tools

The Hedera Agent Kit provides a set of tools, bundled into plugins, to interact with the Hedera network. See how to build your own plugins in docs/HEDERAPLUGINS.md

Currently, the following plugins are available:

Core Account Plugin: Tools for Hedera Account Service operations

• Transfer HBAR
• Create, Update, Delete Account
• Approve and Delete Allowances

Core Consensus Plugin: Tools for Hedera Consensus Service (HCS) operations

• Create, Update, Delete Topic
• Submit a message to a Topic

Core Token Plugin: Tools for Hedera Token Service operations

• Create Fungible and Non-Fungible Tokens
• Mint Tokens
• Associate and Dissociate Tokens
• Airdrop Fungible Tokens
• Transfer with Allowances

Core EVM Plugin: Tools for EVM smart contract operations

• Create and Transfer ERC-20 Tokens
• Create and Transfer ERC-721 Tokens

Core Query Plugins: Tools for querying Hedera network data

• Get Account Info and HBAR Balance
• Get Token Info and Balances
• Get Topic Info
• Get Transaction Records
• Get Exchange Rate

See more in docs/HEDERAPLUGINS.md and docs/HEDERATOOLS.md

---

Creating Plugins & Contributing

• You can find a guide for creating plugins in docs/PLUGINS.md

• If you would like to contribute and suggest improvements for the Python SDK, see CONTRIBUTING.md for details on how to contribute to the Hedera Agent Kit.

---

License

Apache 2.0

---

Credits

Special thanks to the developers of the Stripe Agent Toolkit who provided the inspiration for the architecture and patterns used in this project.