QUANTUMSTACK

Agent Communication Guide

This guide explains how to communicate effectively with your AI agent, understand its capabilities and integrate it with the QuantumStack ecosystem.

What the Agent Is

The agent is an autonomous AI system that executes actions according to rules defined in your NFT.

It works as an intelligent assistant that can execute transactions, monitor markets, manage wallets and more, always respecting the rules defined in the NFT that governs it.

Fundamental Principles

  • Sovereignty: The agent executes only what the NFT allows
  • Decentralization: Does not depend on a centralized executor
  • Transparency: All actions are verifiable on-chain
  • Evolution: The agent evolves according to NFT rules

How the Agent Works

Communication Flow

The agent operates through a well-defined flow that ensures security and compliance:

Agent Communication Flow


                    ┌─────────────────────────────────────┐
                    │  COMMUNICATION FLOW                 │
                    └─────────────────────────────────────┘

          1. User sends command
             ┌──────────┐
             │   User   │ Text or voice
             └────┬──────┘
                  │
                  ▼
          2. Agent receives and processes
             ┌──────────────┐
             │    Agent    │ Interprets command
             │     IA      │
             └────┬─────────┘
                  │
                  ▼
          3. Queries NFT rules
             ┌──────────────┐
             │  Decentral   │ Reads NFT rules
             │   Storage   │
             └────┬─────────┘
                  │
                  ▼
          4. Validates allowed action
             ┌──────────────┐
             │   Rule       │ Checks if action
             │  Validation  │ is allowed
             └────┬─────────┘
                  │
          ┌───────┴────────┐
          │                 │
       Allowed         Not Allowed
          │                 │
          ▼                 ▼
          5. Prepares transaction
             ┌──────────────┐
             │  Transaction │ Creates
             │   Proposal   │ proposal
             └────┬─────────┘
                  │
                  ▼
          6. Wallet validates
             ┌──────────────┐
             │   Smart      │ Validates against
             │   Wallet     │ NFT rules
             └────┬─────────┘
                  │
          ┌───────┴────────┐
          │                 │
       Approved         Rejected
          │                 │
          ▼                 ▼
          7. Executes or informs
             ┌──────────────┐
             │  Execution   │ On-chain or
             │  / Response  │ user response
             └──────────────┘

Command Types

1. Query Commands

Commands that only query information, without executing transactions:

  • "What is my balance?" - Query wallet balance
  • "Show my recent transactions" - List history
  • "What is the current price of ETH?" - Query prices
  • "What are my current rules?" - Shows NFT rules

Example: You ask "What is my balance?" and the agent queries the smart wallet, returns the current balance and may show recent transaction history.

2. Configuration Commands

Commands that configure agent behavior:

  • "Monitor BTC price" - Configure monitoring
  • "Alert me when ETH rises 5%" - Define alerts
  • "Enable staking module" - Enable features
  • "Switch personality to conservative" - Adjust behavior

Example: You say "Monitor BTC price and notify me if it drops more than 10%". The agent configures monitoring and notifies you when the condition is met.

3. Action Commands

Commands that result in on-chain transactions (require validation):

  • "Stake 50% of my funds" - Execute staking
  • "Buy 0.1 ETH when price drops 5%" - Configure trading
  • "Send 0.05 ETH to [address]" - Transfer (if allowed)
  • "Rebalance my wallet" - Rebalancing

Example: You say "Stake 50% of my funds". The agent checks if the amount is within NFT limits, creates a transaction proposal, and the wallet validates before executing on-chain.

QuantumStack Integration

Integration Components

Rules Reader

The agent uses a rules reader that:

  • Reads NFT metadata from decentralized storage
  • Interprets defined rules and limits
  • Validates proposed actions against those rules
  • Maintains isolated context for each NFT

Context Manager

Each agent has an isolated context that:

  • Stores interaction history
  • Maintains state of ongoing operations
  • Isolates information between different NFTs
  • Allows conversation continuity

Action Executor

The action executor:

  • Creates transaction proposals when needed
  • Validates proposals against NFT rules
  • Sends proposals to smart wallet
  • Monitors execution and confirms results

Communication Best Practices

Be Specific

Specific commands are more efficient:

  • Good: "Monitor ETH price and buy 0.1 ETH when it drops 5%"
  • Avoid: "Monitor things and do something when it changes"

Respect the Limits

The agent always respects the limits defined in the NFT:

  • Maximum values per transaction
  • Allowed destinations
  • Operation frequency
  • Enabled action types

Use Natural Language

The agent understands natural language:

  • You do not need to use specific technical commands
  • You can ask questions as in a normal conversation
  • The agent interprets intent and context
  • It may ask for clarification if needed

Practical Examples

Example 1: Balance Query

Command: "What is my current balance?"

What happens:

  1. Agent receives command
  2. Queries smart wallet linked to NFT
  3. Returns current balance and optionally recent history
  4. No transaction is executed

Example 2: Price Monitoring

Command: "Monitor BTC price and notify me if it rises more than 10%"

What happens:

  1. Agent configures price monitoring
  2. Validates that monitoring is allowed in NFT rules
  3. Starts continuous monitoring
  4. When condition is met, notifies you
  5. No transaction is executed automatically

Example 3: Automatic Staking

Command: "Stake 50% of my funds when there is an opportunity"

What happens:

  1. Agent calculates 50% of current balance
  2. Validates if amount is within NFT limits
  3. Searches for available staking opportunities
  4. Creates staking transaction proposal
  5. Wallet validates proposal against NFT rules
  6. If approved, executes on-chain
  7. Agent confirms execution

Security and Validation

Multi-Layer Validation

All actions proposed by the agent go through validation in multiple layers:

1. Validation by the Agent

The agent validates internally:

  • Whether the action is allowed by NFT rules
  • Whether values are within limits
  • Whether destinations are allowed
  • Whether operation frequency is respected

2. Validation by the Wallet

The smart wallet validates on-chain:

  • Critical rules are verified on-chain
  • Does not trust the agent alone
  • Rejects unauthorized actions even if agent is compromised
  • Records all validations and executions

Troubleshooting

Agent not responding

  • Check if the NFT is active and linked
  • Confirm that the agent is initialized
  • Check connection to decentralized storage
  • Try restarting the agent if needed

Action rejected

  • Check if the action is within NFT limits
  • Confirm that the destination is allowed
  • Check if there is sufficient balance
  • Review NFT rules to understand the rejection

Command not understood

  • Try rephrasing the command more clearly
  • Use more specific language
  • Ask the agent what it understood
  • Consult examples of valid commands

Next Steps

To learn more about the agent and QuantumStack:

Last updated: January 2025
Document version: 1.0.0