Skip to content

Home

Jump to bottom
AGI Corp edited this page Mar 20, 2026 · 6 revisions

Sapient OS

Sapient OS - Intelligent Web4 Management System

🌐 Overview

Sapient OS is a comprehensive AI-powered virtual layer for autonomous agent-based parcel management, trading, and optimization. The system integrates advanced AI models, blockchain protocols, and Model Context Protocol (MCP) to enable intelligent autonomous operations across spatial parcels.

🎯 Core Features

1. Autonomous Parcel Agents

  • Individual Parcel Intelligence: Each parcel has its own AI agent powered by Sentient Foundation models
  • LangGraph Integration: Multi-step reasoning and workflow orchestration
  • Real-time Updates: Continuous monitoring and optimization of parcel states
  • Context-Aware Decision Making: Agents use MCP for enhanced contextual understanding

2. Agent Trading & Smart Contracts

  • x402 Protocol Integration: Decentralized wallet management for each parcel agent
  • Autonomous Trading: Agents can trade resources, services, and data
  • Smart Contract Signing: Cryptographically signed agreements between agents
  • Stablecoin Payments: USDC/USDT integration for scalable transactions

3. Route.X MCP Integration

  • Universal Plugin Architecture: All parcels connect via MCP from Route.X
  • Cross-Agent Communication: Seamless data exchange between parcel agents
  • API Gateway: Centralized routing at https://x402.org/api/v1
  • Local Development: Support for localhost:8001 testing environments

4. Stikk.space Virtual Layer

  • 3D Spatial Mapping: Visual representation of parcel locations
  • AI Agent Visualization: See agent activities and decision-making in real-time
  • Tools/Places/AI Integration: Hackathon track implementations

🏗️ Architecture

System Components

┌─────────────────────────────────────────┐
│         Frontend Layer                   │
│  (Next.js + React + 3D Visualization)   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         API Gateway Layer                │
│      (Route.X + x402 Protocol)          │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│       Agent Management Layer             │
│  (LangGraph + Sentient Foundation)      │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│        Blockchain Layer                  │
│     (x402 Wallets + Smart Contracts)    │
└─────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

# Node.js 18+
node --version

# Python 3.10+
python --version

# Docker (optional)
docker --version

Installation

# Clone the repository
git clone https://github.com/AGI-Corporation/Web4AGI.git
cd Web4AGI

# Install dependencies
npm install
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env

Environment Configuration

# API Keys
OPENAI_API_KEY=your_openai_key_here
SENTIENT_API_KEY=your_sentient_key_here
SENTIENT_BASE_URL=https://api.sentientfoundation.ai/v1
SENTIENT_MODEL=sentient-70b

# x402 Protocol
X402_PRIVATE_KEY=your_x402_wallet_key
X402_GATEWAY=https://x402.org/api/v1

# Route.X MCP
ROUTE_X_BASE=http://localhost:8001
MCP_SERVER_URL=https://mcp.route-x.io

# Stablecoin Settings
USDC_CONTRACT_ADDRESS=0x...
STABLECOIN_NETWORK=ethereum-mainnet

Running the System

# Start the backend services
python src/agent_manager.py

# In a new terminal, start the frontend
npm run dev

# Access the dashboard
open http://localhost:3000

📚 Documentation

Core Modules

  1. Agent System - Parcel agent architecture and AI models
  2. Trading Protocol - x402 wallet integration and smart contracts
  3. MCP Integration - Route.X plugin system
  4. API Reference - Complete API documentation
  5. Development Guide - Contributing and development workflows

🔧 Technology Stack

Frontend

  • Next.js 14: React framework with App Router
  • Three.js: 3D visualization for Stikk.space integration
  • TailwindCSS: Utility-first styling
  • Zustand: State management

Backend

  • FastAPI: High-performance Python API framework
  • LangGraph: Agent workflow orchestration
  • Sentient Foundation: Advanced AI reasoning models
  • PostgreSQL: Persistent data storage
  • Redis: Caching and real-time updates

Blockchain & Web3

  • x402 Protocol: Decentralized wallet management
  • Ethers.js: Ethereum interaction
  • Hardhat: Smart contract development
  • USDC/USDT: Stablecoin integration

Integration Layer

  • Model Context Protocol (MCP): Route.X plugin system
  • WebSocket: Real-time agent communication
  • gRPC: High-performance service communication

🎮 Use Cases

1. Virtual Real Estate Management

  • AI agents manage virtual land parcels
  • Autonomous trading of parcel resources
  • Dynamic pricing based on demand

2. Supply Chain Optimization

  • Each warehouse/location has an agent
  • Agents negotiate shipping routes and costs
  • Smart contracts for automated transactions

3. Decentralized Autonomous Organizations (DAOs)

  • Geographic parcels with governance agents
  • Community voting via agent consensus
  • Treasury management with stablecoins

4. Gaming & Metaverse

  • Player-owned parcels with AI assistants
  • In-game economy powered by x402 protocol
  • Cross-game asset trading

🧪 Testing

# Run unit tests
pytest tests/

# Run frontend tests
npm test

# Run integration tests
pytest tests/integration/

# Run end-to-end tests
npm run test:e2e

📊 Performance Metrics

  • Agent Response Time: < 500ms
  • Transaction Settlement: < 3 seconds
  • Concurrent Agents: 10,000+ per instance
  • MCP Message Throughput: 50,000 msg/sec

🤝 Contributing

See Contributing for guidelines.

📄 License

MIT © AGI Corporation 2026

🔗 Links

💬 Support

Join our community:

🌐 Sapient OS ~AGI Corp Wiki

📖 Getting Started

🤖 Core Systems

💰 Economy & Blockchain

📝 Reference

🔗 External Links

🚨 Open Issues

Clone this wiki locally