# SperaxOS AI Agents

> Specialized AI agents for DeFi, crypto, blockchain, Web3, DeFAI. Deep expertise in yield optimization, smart contracts, portfolio management. Multi-agent collaboration (Agent Teams), MCP (Model Context Protocol) integrations, universal JSON API. Open-source, no vendor lock-in, 18 languages.

- **Type:** MCP server
- **Install:** `agentstack add mcp-speraxos-speraxos-ai-agents`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [speraxos](https://agentstack.voostack.com/s/speraxos)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [speraxos](https://github.com/speraxos)
- **Source:** https://github.com/speraxos/SperaxOS-AI-Agents
- **Website:** https://sperax.io

## Install

```sh
agentstack add mcp-speraxos-speraxos-ai-agents
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SperaxOS Agent Ecosystem: Complete Overview

> **The Ultimate Guide to AI Agents, Agent Teams, and the SperaxOS Agent Index API**

---

## 📖 Table of Contents

- [Introduction](#introduction)
- [What Are AI Agents?](#what-are-ai-agents)
- [The SperaxOS Agent Architecture](#the-speraxos-agent-architecture)
- [Agent Index API](#agent-index-api)
- [Core Agent Features](#core-agent-features)
- [Advanced Capabilities](#advanced-capabilities)
- [Agent Collaboration](#agent-collaboration)
- [Extension Systems](#extension-systems)
- [Multimodal Features](#multimodal-features)
- [Infrastructure & Storage](#infrastructure--storage)
- [Developer Resources](#developer-resources)
- [Use Cases & Examples](#use-cases--examples)

---

## Introduction

**SperaxOS** AI agent index at its core is a sophisticated agent ecosystem that transforms traditional AI chat into a dynamic, collaborative, and highly specialized experience. Unlike conventional AI assistants that attempt to be generalists, SperaxOS leverages **specialized AI agents** that excel in specific domains—from DeFi analytics to smart contract development, from portfolio management to creative content generation.

### Why Agents Matter

Traditional AI interactions are linear and monolithic. SperaxOS breaks this paradigm by introducing:

- **Specialization**: Each agent is an expert in its domain
- **Collaboration**: Agents work together in teams for complex tasks
- **Extensibility**: Plugins and MCP servers expand agent capabilities
- **Personalization**: Custom agents tailored to your exact needs
- **Interoperability**: Universal agent format works across platforms

### The Vision

SperaxOS envisions a future where:
- Every task is handled by the optimal AI specialist
- Complex problems are solved through agent collaboration
- AI capabilities extend beyond conversation to real-world actions
- Users have complete control over their AI experience
- The agent ecosystem grows through community contributions

---

## What Are AI Agents?

### Definition

An **AI Agent** in SperaxOS is more than a chatbot—it's a specialized AI entity with:

1. **Identity**: Name, avatar, description, and role
2. **Expertise**: Domain-specific knowledge encoded in system prompts
3. **Tools**: Access to plugins, MCPs, and external services
4. **Memory**: Context retention across conversations
5. **Personality**: Consistent interaction style and approach
6. **Configuration**: Model selection, parameters, and behavior settings

### Agents vs. Traditional AI Chat

| Traditional AI Chat | SperaxOS Agents |
|---------------------|-----------------|
| One-size-fits-all responses | Specialized domain expertise |
| Generic conversation | Role-specific interactions |
| Limited tools | Extensible with plugins/MCPs |
| Stateless interactions | Persistent context & memory |
| Single AI model | Multi-model support |
| Text-only | Multimodal (vision, voice, images) |

### The Agent Lifecycle

```
Discovery → Selection → Customization → Interaction → Collaboration → Iteration
    ↓          ↓            ↓              ↓              ↓              ↓
  Browse    Add to       Configure      Chat &       Work in        Refine &
  Market    Favorites    Settings       Execute      Teams          Improve
```

---

## The SperaxOS Agent Architecture

### Components Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        SperaxOS Platform                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
│  │  Agent Core  │  │  Extensions  │  │  Integrations│           │
│  │              │  │              │  │              │           │
│  │ • System Role│  │ • Plugins    │  │ • LLM Models │           │
│  │ • Config     │  │ • MCP Servers│  │ • TTS/STT    │           │
│  │ • Memory     │  │ • Tools      │  │ • Vision API │           │
│  │ • Context    │  │ • Functions  │  │ • Image Gen  │           │
│  └──────────────┘  └──────────────┘  └──────────────┘           │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
│  │ Agent Market │  │ Agent Teams  │  │  Knowledge   │           │
│  │              │  │              │  │    Bases     │           │
│  │ • Agents     │  │ • Multi-Agent│  │              │           │
│  │ • Discovery  │  │ • Host/Guest │  │ • File Upload│           │
│  │ • Index API  │  │ • Private Msg│  │ • RAG/Search │           │
│  │ • 18 Langs   │  │ • Templates  │  │ • Embeddings │           │
│  └──────────────┘  └──────────────┘  └──────────────┘           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Agent Anatomy

Every SperaxOS agent follows a standardized schema:

```json
{
  "identifier": "unique-agent-id",
  "author": "creator-username",
  "schemaVersion": 1,
  "createAt": "2024-01-15",
  "meta": {
    "title": "Agent Display Name",
    "description": "Clear, concise description",
    "avatar": "🤖",
    "tags": ["defi", "analytics", "blockchain"],
    "category": "general",
    "systemRole": "agent"
  },
  "config": {
    "systemRole": "Detailed system prompt defining behavior...",
    "model": "gpt-4o",
    "provider": "openai",
    "plugins": ["plugin-id-1", "plugin-id-2"],
    "knowledgeBases": [...],
    "params": {
      "temperature": 0.7,
      "topP": 0.9,
      "maxTokens": 4096
    }
  }
}
```

#### Key Fields Explained

- **identifier**: Unique ID (URL-safe, lowercase, hyphens)
- **systemRole**: The "brain" of the agent—defines expertise, personality, behavior
- **plugins**: Array of plugin IDs that extend agent capabilities
- **knowledgeBases**: Document collections for RAG (Retrieval-Augmented Generation)
- **params**: LLM parameters (temperature, top_p, max_tokens, etc.)

---

## Agent Index API

### Overview

The **SperaxOS Agent Index API** is a decentralized, CDN-delivered JSON index of 505+ specialized AI agents. It enables:

- **Programmatic Access**: RESTful API via GitHub Pages
- **Universal Format**: Standard JSON schema works anywhere
- **Zero Vendor Lock-in**: Platform-agnostic agent definitions
- **Multi-language Support**: Automated i18n for 18 languages
- **Fast Delivery**: Global CDN with 80-120ms latency
- **Open Source**: MIT licensed, fully transparent

### Repositories

1. **[AI-Agents-Library](https://github.com/nirholas/AI-Agents-Library)**: Universal agent library (main branch)
2. **[SperaxOS-AI-Agents](https://github.com/speraxos/SperaxOS-AI-Agents)**: SperaxOS-specific deployment

### API Endpoints

#### Base URL
```
https://sperax.works/sperax-ai-agents/
```

#### Main Index
```
GET /index.json
```
Returns all 505+ agents with metadata.

**Response:**
```json
{
  "agents": [
    {
      "identifier": "defi-yield-optimizer",
      "author": "sperax",
      "meta": {
        "title": "DeFi Yield Optimizer",
        "description": "Analyzes yield farming opportunities...",
        "avatar": "🌾",
        "tags": ["defi", "yield", "analytics"]
      },
      "schemaVersion": 1,
      "createAt": "2024-01-15"
    }
  ]
}
```

#### Individual Agent (English)
```
GET /{agent-identifier}.json
```

#### Localized Agent
```
GET /{agent-identifier}.{locale}.json
```

**Supported Locales:**
- `en-US`, `zh-CN`, `zh-TW`, `ja-JP`, `ko-KR`, `de-DE`, `fr-FR`, `es-ES`, `ru-RU`, `ar`, `pt-BR`, `it-IT`, `nl-NL`, `pl-PL`, `tr-TR`, `vi-VN`, `fa-IR`, `bg-BG`

### Integration Examples

#### JavaScript/TypeScript
```javascript
// Fetch all agents
const response = await fetch('https://sperax.works/sperax-ai-agents/index.json');
const { agents } = await response.json();

// Filter by category
const defiAgents = agents.filter(a => a.meta.tags.includes('defi'));

// Load specific agent
const agent = await fetch('https://sperax.works/sperax-ai-agents/defi-yield-optimizer.json');
const config = await agent.json();
```

#### Python
```python
import requests

# Load agent index
response = requests.get('https://sperax.works/sperax-ai-agents/index.json')
agents = response.json()['agents']

# Search by tag
defi_agents = [a for a in agents if 'defi' in a['meta']['tags']]
```

#### React Component
```jsx
function AgentList({ tag }) {
  const [agents, setAgents] = useState([]);

  useEffect(() => {
    fetch('https://sperax.works/sperax-ai-agents/index.json')
      .then(r => r.json())
      .then(data => {
        const filtered = tag 
          ? data.agents.filter(a => a.meta.tags.includes(tag))
          : data.agents;
        setAgents(filtered);
      });
  }, [tag]);

  return (
    
      {agents.map(agent => (
        
      ))}
    
  );
}
```

### API Features

- **No Authentication**: Public access, no API keys required
- **CORS Enabled**: Use from any domain
- **Caching**: Set `Cache-Control` headers (1 hour recommended)
- **Rate Limits**: None (CDN-backed)
- **Versioning**: Schema version in each agent
- **Search**: Client-side filtering by title, description, tags

---

## Core Agent Features

### 1. Agent Market

The **Assistant Market** is the hub for discovering and deploying specialized agents.

#### Features

- **505+ Curated Agents**: Covering 50+ categories
- **Community Contributions**: Submit your own agents via GitHub
- **Search & Filter**: By tags, categories, or keywords
- **One-Click Install**: Add agents to your workspace instantly
- **Multi-language**: All agents available in 18 languages
- **Version Control**: Track agent updates and changes

#### Agent Categories

**🔐 Crypto & DeFi**
- DeFi Yield Optimizer, Portfolio Analyst, Risk Guardian
- Blockchain Developer, Smart Contract Auditor
- Bridge Navigator, Payment Executor, NFT Intelligence

**💼 Business & Finance**
- Financial Analyst, Business Strategy Consultant
- Market Research, SWOT Analysis, Investment Advisory

**💻 Development & Engineering**
- Frontend/Backend Developers, DevOps Engineers
- API Documentation, Code Review, Testing Specialists
- Database Administrators, Security Experts

**🎨 Creative & Design**
- UI/UX Designer, Graphic Designer, Logo Creator
- Content Writer, Copywriter, Social Media Manager
- Video Editor, Animation Specialist

**🎓 Education & Learning**
- Math Tutor, Language Learning Partner
- STEM Educator, Exam Prep Coach, Research Assistant

**📊 Data & Analytics**
- Data Analyst, Data Scientist, ML Engineer
- Business Intelligence, Reporting Specialist

#### Discovery Workflow

```
1. Browse → 2. Preview → 3. Add → 4. Configure → 5. Chat
    ↓          ↓          ↓         ↓            ↓
  Market    Read Meta   Install   Customize   Interact
  Search    & System    Agent     Settings    & Iterate
            Prompt
```

### 2. Custom Agent Creation

Build tailored agents for your specific needs.

#### Creation Methods

**A. From Scratch**
1. Click "Create Agent" button
2. Define identity (name, avatar, description)
3. Write system prompt (expertise, behavior, constraints)
4. Configure model & parameters
5. Add plugins/tools (optional)
6. Test and iterate

**B. From Template**
1. Select agent from market
2. Click "Duplicate" or "Customize"
3. Modify system prompt
4. Adjust settings
5. Save as new agent

**C. Import from JSON**
1. Load agent JSON file
2. Validate schema
3. Import and activate

#### System Prompt Best Practices

**Structure**:
```markdown
## Role & Identity
You are a [specific role] specializing in [domain].

## Core Capabilities
- Capability 1: Description
- Capability 2: Description
- Capability 3: Description

## Interaction Style
- Be [adjective]: Explanation
- Always [action]: Reasoning
- Never [action]: Reasoning

## Output Format
[Describe expected output structure]

## Constraints & Safety
- Guideline 1
- Guideline 2
```

**Example: DeFi Analyst**
```markdown
## Role & Identity
You are a DeFi Research Analyst specializing in protocol analysis, 
TVL tracking, and yield comparison.

## Core Capabilities
- Protocol Analysis: Deep dive into DeFi mechanisms, tokenomics
- TVL Tracking: Monitor total value locked across chains
- Security Assessment: Review audit reports, flag vulnerabilities
- Yield Comparison: Compare APY/APR across platforms

## Interaction Style
- Data-Driven: Every claim backed by on-chain data
- Comparative: Always show alternatives
- Risk-Aware: Highlight security concerns before promoting yields
- Transparent: Disclose data sources

## Output Format
Protocol Name | TVL | APY | Risk Level | Recommendation

## Constraints & Safety
⚠️ High yield = high risk
⚠️ Audit ≠ safety guarantee
⚠️ Always disclaim: "Not financial advice. DYOR."
```

### 3. Topics & Organization

#### The Agent-Topic Model

Unlike ChatGPT's flat "topic" structure, SperaxOS organizes conversations hierarchically:

```
Agent (Specialist) → Topics (Conversations)
    ↓                       ↓
Portfolio Analyst    [Topic 1: January Review]
                     [Topic 2: Rebalancing Strategy]
                     [Topic 3: Risk Assessment]
```

**Benefits**:
- **Quick Access**: Switch between related conversations
- **Context Preservation**: Each topic maintains its own history
- **Organization**: Group related discussions under specialists
- **Efficiency**: No need to re-establish context

#### Assistant Organization

**Favorites Bar**: Pin frequently used agents for instant access

**Categories**: Organize agents by:
- Function (DeFi, Trading, Development)
- Frequency (Daily, Weekly, Occasional)
- Projects (Project A, Project B, Personal)

**Search**: Quick find across all agents

### 4. Model Selection

#### Multi-Provider Support

SperaxOS supports 50+ AI providers:

**Major Providers**:
- OpenAI (GPT-4o, GPT-4 Turbo, o1)
- Anthropic (Claude 3.5 Sonnet, Claude 3 Opus)
- Google (Gemini 1.5 Pro, Gemini Ultra)
- DeepSeek (DeepSeek V2, DeepSeek R1)
- OpenRouter (100+ models)

**Specialized Providers**:
- Groq (Ultra-fast inference)
- Together AI (Open-source models)
- Ollama (Local models)
- AWS Bedrock (Enterprise)

#### Model Parameters

**Temperature** (0.0 - 2.0)
- **0.0-0.3**: Deterministic, factual (analytics, code)
- **0.7-0.9**: Balanced creativity (general chat)
- **1.2-2.0**: Highly creative (brainstorming, writing)

**Top P** (0.0 - 1.0)
- Controls diversity of token selection
- 0.9 recommended for most use cases

**Max Tokens**
- 4096: Standard responses
- 8192-16384: Long-form content
- 32768+: Document analysis, extensive reports

**Frequency/Presence Penalty**
- Reduce repetition in outputs

---

## Advanced Capabilities

### 1. Chain of Thought (CoT)

Experience AI reasoning transparency through step-by-step visualization.

#### What is CoT?

Chain of Thought visualization reveals the AI's problem-solving process:

```
User: "Analyze this DeFi protocol"

CoT Display:
├─ Step 1: Identify protocol type (AMM, Lending, etc.)
├─ Step 2: Retrieve TVL data from DeFi Llama
├─ Step 3: Check audit reports and security history
├─ Step 4: Calculate risk metrics
├─ Step 5: Compare with similar protocols
└─ Step 6: Generate recommendation

Final Answer: [Detailed analysis]
```

#### Benefits

- **Debugging**: Identify where reasoning went wrong
- **Learning**: Understand how AI approaches problems
- **Trust**: Verify logical progression
- **Validation**: Catch errors before they propagate

#### Supported Models

- OpenAI o1 Series (native CoT)
- Claude 3.5 Sonnet (with prompting)
- GPT-4 Turbo (with prompting)
- Custom agents with CoT prompts

### 2. Branching Conversations

Transform linear chats into dynamic, explorable conversation trees.

#### How It Works

```
Main Conversation
├─ Branch 1: Explore alternative A
│  └─ Sub-branch: Deep dive into A
└─ Branch 2: Explore alternative B
   ├─ Sub-branch: Variation B1
   └─ Sub-branch: Variation B2
```

#### Modes

**Continuation Mode**
- Maintains context from parent message
- Extends the convers

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [speraxos](https://github.com/speraxos)
- **Source:** [speraxos/SperaxOS-AI-Agents](https://github.com/speraxos/SperaxOS-AI-Agents)
- **License:** MIT
- **Homepage:** https://sperax.io

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-speraxos-speraxos-ai-agents
- Seller: https://agentstack.voostack.com/s/speraxos
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.