Building AI Agents on Aptos

AI agents are autonomous programs that can interact with the blockchain on behalf of users. Aptos provides infrastructure for building AI agents that can manage digital assets, execute DeFi strategies, and participate in governance.

What is an On-Chain AI Agent?

An on-chain AI agent typically consists of:

An off-chain LLM that makes decisions based on on-chain data
A wallet/account that the agent controls for executing transactions
Smart contracts that define what the agent can do and enforce guardrails
An execution loop that reads state, decides on actions, and submits transactions

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                  │     │                  │     │                 │
│   LLM Engine    │────▶│  Agent Backend   │────▶│  Aptos Chain    │
│  (Decision)     │     │  (Execution)     │     │  (Settlement)   │
│                  │◀────│                  │◀────│                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘

Agent Architecture

1. Read On-Chain State

Use the Aptos SDK to read blockchain state:

import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

const aptos = new Aptos(new AptosConfig({ network: Network.MAINNET }));

// Read account balance
const balance = await aptos.getAccountAPTAmount({
  accountAddress: agentAddress,
});

// Read contract state via view function
const state = await aptos.view({
  payload: {
    function: "0x1::coin::balance",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [agentAddress],
  },
});

2. LLM Decision Making

Feed the on-chain state to an LLM for decision-making:

const prompt = `
You are an AI agent managing a DeFi portfolio on Aptos.

Current state:
- APT balance: ${balance}
- Current positions: ${JSON.stringify(positions)}
- Market conditions: ${JSON.stringify(marketData)}

Available actions:
1. swap(token_in, token_out, amount) - Swap tokens on a DEX
2. provide_liquidity(pool, amount) - Add liquidity to a pool
3. stake(amount) - Stake APT with a validator
4. hold() - Take no action

Decide the best action based on the current state.
Return your decision as JSON: { "action": "...", "params": {...}, "reasoning": "..." }
`;

const decision = await llm.complete(prompt);

3. Execute Transactions

Submit the decided transaction to the blockchain:

import { Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";

// Agent's account (secured in practice)
const agentAccount = Account.fromPrivateKey({
  privateKey: new Ed25519PrivateKey(agentPrivateKey),
});

// Build and submit the transaction
const transaction = await aptos.transaction.build.simple({
  sender: agentAccount.accountAddress,
  data: {
    function: "0x1::coin::transfer",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [recipientAddress, amount],
  },
});

const committedTxn = await aptos.signAndSubmitTransaction({
  signer: agentAccount,
  transaction,
});

await aptos.waitForTransaction({
  transactionHash: committedTxn.hash,
});

Smart Contract Guardrails

For safety, define on-chain guardrails that limit what an agent can do:

module my_addr::agent_vault {
    use std::signer;
    use aptos_framework::timestamp;

    /// Agent is not active
    const E_AGENT_INACTIVE: u64 = 1;
    /// Transfer exceeds per-transaction limit
    const E_TRANSFER_TOO_LARGE: u64 = 2;
    /// Transfer would exceed daily spending limit
    const E_DAILY_LIMIT_EXCEEDED: u64 = 3;

    /// Seconds in a day, used for daily spend reset
    const SECONDS_PER_DAY: u64 = 86400;

    struct AgentConfig has key {
        owner: address,
        daily_spent: u64,
        last_reset_timestamp: u64,
        max_transfer: u64,
        max_daily_spend: u64,
        is_active: bool,
    }

    /// Only the agent owner can configure the agent
    public entry fun configure_agent(
        owner: &signer,
        max_transfer: u64,
        max_daily_spend: u64,
    ) {
        let owner_addr = signer::address_of(owner);
        move_to(owner, AgentConfig {
            owner: owner_addr,
            daily_spent: 0,
            last_reset_timestamp: timestamp::now_seconds(),
            max_transfer,
            max_daily_spend,
            is_active: true,
        });
    }

    /// Reset daily spending if a new day has started
    fun maybe_reset_daily_spent(config: &mut AgentConfig) {
        let now = timestamp::now_seconds();
        if (now - config.last_reset_timestamp >= SECONDS_PER_DAY) {
            config.daily_spent = 0;
            config.last_reset_timestamp = now;
        };
    }

    /// The agent calls this -- guardrails enforce limits
    public entry fun agent_transfer(
        agent: &signer,
        to: address,
        amount: u64,
    ) acquires AgentConfig {
        let agent_addr = signer::address_of(agent);
        let config = &mut AgentConfig[agent_addr];

        assert!(config.is_active, E_AGENT_INACTIVE);
        assert!(amount <= config.max_transfer, E_TRANSFER_TOO_LARGE);

        // Reset daily spending if a new day has started
        maybe_reset_daily_spent(config);
        assert!(config.daily_spent + amount <= config.max_daily_spend, E_DAILY_LIMIT_EXCEEDED);

        config.daily_spent = config.daily_spent + amount;
        // Execute transfer...
    }

    /// Owner can pause the agent at any time
    public entry fun pause_agent(owner: &signer) acquires AgentConfig {
        let config = &mut AgentConfig[signer::address_of(owner)];
        config.is_active = false;
    }
}

Agent Frameworks on Aptos

Several frameworks simplify building AI agents on Aptos:

Move Agent Kit

The Move Agent Kit provides tools for building AI agents that interact with the Aptos blockchain. It integrates with popular LLM frameworks and provides pre-built tools for common on-chain actions.

Key features:

Pre-built Aptos transaction tools for LLM agents
Integration with LangChain, Eliza, and other agent frameworks
Token transfer, NFT minting, and DeFi interaction tools
Wallet management and transaction signing

Eliza Framework

The Eliza Framework is a multi-agent simulation framework that supports Aptos blockchain interactions. Agents can:

Manage Aptos wallets
Execute token transfers
Interact with DeFi protocols
Monitor on-chain events

Use Cases

Portfolio Manager

An AI agent that:

Monitors token prices and portfolio performance
Rebalances holdings based on predefined strategies
Executes swaps on DEXes for optimal pricing
Reports performance to the owner

NFT Trader

An AI agent that:

Monitors NFT marketplace listings
Evaluates NFT value using image analysis and market data
Places bids or buys undervalued NFTs
Lists overvalued NFTs for sale

Governance Participant

An AI agent that:

Reads governance proposals
Analyzes proposal impact using LLM reasoning
Votes according to predefined principles
Reports voting activity and reasoning

Security Considerations

Key management: Agent private keys must be securely stored (use HSMs or secure enclaves).
Spending limits: Always enforce on-chain guardrails for maximum transaction amounts.
Kill switch: Implement an owner-controlled pause mechanism.
Monitoring: Log all agent actions and set up alerts for unusual behavior.
Testing: Thoroughly test agent behavior on devnet before mainnet deployment.
Prompt injection: Protect against prompt injection attacks if the agent processes external data.

Best Practices

Start small: Begin with simple, low-risk actions and gradually increase agent capabilities.
Use guardrails: Always implement on-chain spending limits and pause mechanisms.
Monitor continuously: Watch agent behavior and be ready to intervene.
Test extensively: Run agents on devnet with simulated market conditions.
Separate concerns: Keep the LLM decision-making separate from transaction execution.
Audit agent contracts: The smart contracts that enforce guardrails are security-critical.

The Aptos Book