How to use AI Agents on Supra!

Blockchain offers powerful capabilities, but for many developers and users, interacting with it still involves complex tooling, manual commands, and a steep learning curve. This complexity often slows down experimentation and limits accessibility.

That’s where AI Agents come in.

AI Agents are designed to simplify how we interact with the blockchain. By combining automation with intelligent behavior, they can take over routine tasks, retrieve data, and execute actions across the network, without requiring users to manually write or run every command themselves.

Supra is building AI tools to support these use cases from the ground up. Supra enables AI Agents to operate directly on-chain or through trusted interfaces with the network.

In this guide, you’ll learn how to create and run your first AI Agent on Supra. 
This agent will be able to:

• Create a new account on the Supra Network
• Fetch the current balance of any account
• Request test tokens via the faucet
• Retrieve transaction details using a transaction hash
• Display your transaction history
• Query on-chain resource data tied to your account

By the end, you’ll have a fully functioning AI Agent that can communicate with the network and perform key actions, giving you a foundation to build more advanced, intelligent blockchain workflows.

Prerequisite

Here’s what you’ll need:

• Node.js installed.
• git bash installed.
• nvm installed.
  • For Windows
  • For MacOS
• For Linux

Step 1: Clone Repo

Start by cloning the AI Agent example repository to your local machine. This will give you all the files you need to run and explore the agent’s functionality.
Use the following command:

git clone https://github.com/Supra-Labs/Supra-agents-hub.git

Step 2: Navigate to the Correct Directory

Use your terminal to move into the folder where your project was created. 
Use the following command:

cd Supra-agents-hub
cd Agents
cd SurpaOnChainAgent

Step 3: Install Dependencies

After navigating to the project directory, install all required packages to ensure the AI Agent runs properly.
Use the following command:

npm install

Step 4: Run Your Agent

Now that everything is set up, you can launch the AI Agent.
Use the following command:

npx tsx agent.ts

A dashboard will pop up in your git bash terminal:

$ npx tsx agent.ts

*** Welcome to SupraOnChainAgent ***

Initializing Supra Client...

Connected to network with chain ID: _ChainId { value: 6 }

Loaded existing account from account.json

Your Supra Account Address: 0x26b58df6a3716bc16de96d6aa5fa60c1cf12e0854e8983b4a6d0a4a9548c218d

Available commands:

- 'what is the balance of my account'     : Fetch account info & balance

- 'please fund my account'                 : Fund account via faucet

- 'show me transaction details for <TX_HASH>': Fetch transaction details

- 'what is my transaction history'         : Retrieve transaction history

- 'show my account resources'              : Fetch resource data

- 'help'                                   : Show this help message

- 'exit'                                   : Quit the agent

SupraOnChainAgent>

Step 5: Interact with the Agent

With the agent running, you can now interact with it directly through the terminal.

Try entering natural-language commands like:

please fund my account

You’ll receive a confirmation with a status: success once your account has been funded.

status: 'Success'

Then, check your balance by typing:

what is the balance of my account

You’ll see your updated balance returned from the network.

Feel free to explore other supported commands; the agent is built to handle various on-chain tasks. That’s how you can start using Supra’s AI Agent to simplify blockchain interactions.