SmartAgent v1.7.0 🚀

Enterprise Multi-Agent Swarm System with Real LLM Integration (Gemini, Claude, Kimi, OpenCode)

SmartAgent คือระบบจัดการ Multi-Agent Swarm ระดับ Enterprise ที่รองรับการทำงานร่วมกันของ Agent หลายตัว พร้อมระบบคิดแบบลำดับขั้นตอน (Sequential Thinking), การส่งต่องานอัตโนมัติ (Auto-Routing), และการประมวลผลแบบขนาน (Parallel Execution)

🌟 Key Features

• 🤖 Multi-LLM Provider Support - Gemini, Claude, Kimi K2.5, OpenCode
• 🧠 Sequential Thinking Engine - Thought chains with branching & revision
• 🛣️ Intelligent Auto-Routing - AI-powered intent classification & agent selection
• 🔄 Parallel Execution - Execute multiple tasks concurrently with real LLM calls
• 💾 Enterprise Persistence - SQLite-based context storage & handoff
• 📱 Cross-Platform - Works on servers, PCs, and Android (Termux)

📦 Installation

Quick Start (npx)

npx @gotza02/smartagent

Global Install

npm install -g @gotza02/smartagent
smartagent

Android (Termux)

curl -fsSL https://raw.githubusercontent.com/gotza02/smartagent/main/scripts/install-termux.sh | bash

🚀 Quick Start Guide

Step 1: Set API Key

# Option A: Gemini (default)
export GEMINI_API_KEY='your_gemini_api_key'

# Option B: Claude
export ANTHROPIC_API_KEY='your_claude_api_key'
export SWARM_LLM_PROVIDER='claude'

# Option C: Kimi
export KIMI_API_KEY='your_kimi_api_key'
export SWARM_LLM_PROVIDER='kimi'

Step 2: Start the Server

# Using npx (recommended)
npx @gotza02/smartagent

# Or if installed globally
smartagent

You should see:

🚀 SmartAgent MCP Server v1.7.0
📡 Transport: stdio
🤖 LLM Provider: gemini
✅ Server ready

Step 3: First Agent Creation

Once connected, create your first agent:

{
  "tool": "spawn_agent",
  "args": {
    "type": "engineer",
    "name": "my_first_agent",
    "provider": "gemini"
  }
}

Response:

{
  "id": "agent-uuid-here",
  "name": "my_first_agent",
  "type": "engineer",
  "status": "idle",
  "provider": "gemini"
}

📖 Usage Guide

Guide 1: Complete Development Workflow

Scenario: Build a web application with authentication

Step 1: Bootstrap Team

{
  "tool": "system_bootstrap",
  "args": {
    "teamSize": "full",
    "provider": "claude",
    "objective": "Build a React web app with JWT authentication",
    "confirm": true
  }
}

This creates:

• 1x Product Manager
• 1x Architect
• 2x Engineers
• 1x QA
• 1x Reviewer

Step 2: PM Creates Requirements

{
  "tool": "assign_task",
  "args": {
    "agentId": "pm-agent-uuid",
    "type": "requirements",
    "description": "Create PRD for JWT auth system with login/signup flows",
    "priority": 10
  }
}

Step 3: Architect Designs System

{
  "tool": "thinking_create_chain",
  "args": {
    "agentId": "architect-agent-uuid",
    "taskId": "arch-task-uuid",
    "title": "Auth System Architecture"
  }
}

{
  "tool": "thinking_add_thought",
  "args": {
    "chainId": "chain-uuid",
    "content": "Use JWT with refresh token pattern",
    "reasoning": "Better security and user experience",
    "confidence": 0.95
  }
}

Step 4: Engineers Implement in Parallel

{
  "tool": "parallel_execute",
  "args": {
    "tasks": [
      {
        "agentType": "engineer",
        "type": "implementation",
        "description": "Create /api/auth/login endpoint",
        "priority": 9
      },
      {
        "agentType": "engineer",
        "type": "implementation",
        "description": "Create /api/auth/register endpoint",
        "priority": 9
      }
    ],
    "maxConcurrency": 2
  }
}

Step 5: Context Handoff to QA

{
  "tool": "context_handoff",
  "args": {
    "fromAgentId": "engineer-1-uuid",
    "toAgentId": "qa-agent-uuid",
    "taskId": "implementation-task-uuid",
    "notes": "Focus on testing JWT token expiration and refresh flow"
  }
}

Step 6: Code Review

{
  "tool": "assign_task",
  "args": {
    "agentId": "reviewer-agent-uuid",
    "type": "review",
    "description": "Review auth implementation for security best practices",
    "context": {
      "files": ["auth.ts", "middleware.ts"]
    }
  }
}

Guide 2: Using Different LLM Providers

Example: Mix Providers for Different Tasks

Claude for Architecture (complex reasoning):

{
  "tool": "spawn_agent",
  "args": {
    "type": "architect",
    "name": "claude_architect",
    "provider": "claude"
  }
}

Kimi for Coding (fast implementation):

{
  "tool": "spawn_agent",
  "args": {
    "type": "engineer",
    "name": "kimi_coder",
    "provider": "kimi"
  }
}

Gemini for QA (thorough testing):

{
  "tool": "spawn_agent",
  "args": {
    "type": "qa",
    "name": "gemini_tester",
    "provider": "gemini"
  }
}

Now assign tasks to each - they'll use their respective LLM providers!

Guide 3: Sequential Thinking for Complex Problems

Scenario: Design a microservices architecture

// 1. Create thinking chain
{
  "tool": "thinking_create_chain",
  "args": {
    "agentId": "architect-uuid",
    "taskId": "microservices-design",
    "title": "Microservices Architecture Decision"
  }
}

// 2. Add initial thought
{
  "tool": "thinking_add_thought",
  "args": {
    "chainId": "chain-uuid",
    "content": "Split into 3 services: Auth, API Gateway, User Service",
    "reasoning": "Single responsibility principle",
    "confidence": 0.9
  }
}

// 3. Branch alternative approach
{
  "tool": "thinking_add_thought",
  "args": {
    "chainId": "chain-uuid",
    "content": "Use monolith with modular structure instead",
    "reasoning": "Simpler for small team, easier deployment",
    "confidence": 0.75,
    "branchFrom": "first-thought-uuid"
  }
}

// 4. Revise with new information
{
  "tool": "thinking_add_thought",
  "args": {
    "chainId": "chain-uuid",
    "content": "Start with monolith, extract services later",
    "reasoning": "Evolutionary architecture - start simple, grow as needed",
    "confidence": 0.95,
    "revisionOf": "second-thought-uuid"
  }
}

// 5. Export final decision
{
  "tool": "thinking_export",
  "args": {
    "chainId": "chain-uuid",
    "format": "markdown"
  }
}

Guide 4: Auto-Routing for Smart Task Assignment

Let AI choose the best agent for your task:

// Classify intent
{
  "tool": "routing_classify_intent",
  "args": {
    "input": "Review this code for SQL injection vulnerabilities"
  }
}

Response:

{
  "intent": "review",
  "confidence": 0.94,
  "category": "review",
  "complexity": "medium"
}

// Get routing recommendation
{
  "tool": "routing_route",
  "args": {
    "input": "Review this code for SQL injection vulnerabilities"
  }
}

Response:

{
  "targetAgent": "reviewer",
  "confidence": 0.96,
  "reasoning": "Input classified as review task",
  "suggestedMode": "plan"
}

Then spawn the recommended agent:

{
  "tool": "spawn_agent",
  "args": {
    "type": "reviewer",
    "provider": "claude"
  }
}

Guide 5: Parallel Execution for Speed

Scenario: Analyze multiple files simultaneously

{
  "tool": "parallel_execute",
  "args": {
    "tasks": [
      {
        "agentType": "engineer",
        "type": "analysis",
        "description": "Analyze auth.ts for security issues",
        "priority": 8
      },
      {
        "agentType": "engineer",
        "type": "analysis",
        "description": "Analyze database.ts for performance",
        "priority": 7
      },
      {
        "agentType": "engineer",
        "type": "analysis",
        "description": "Analyze api.ts for error handling",
        "priority": 7
      }
    ],
    "maxConcurrency": 3,
    "aggregationStrategy": "all"
  }
}

Guide 6: Monitoring & Debugging

Check System Health

{
  "tool": "system_health",
  "args": {}
}

View System Stats

{
  "tool": "system_stats",
  "args": {}
}

List All Agents

{
  "tool": "list_agents",
  "args": {}
}

List Busy Agents

{
  "tool": "list_agents",
  "args": {
    "status": "busy"
  }
}

View Agent Messages

{
  "tool": "get_agent_messages",
  "args": {
    "agentId": "agent-uuid",
    "limit": 20
  }
}

Export Metrics

{
  "tool": "system_metrics",
  "args": {
    "format": "prometheus"
  }
}

Guide 7: Working with Plugins

List Available Plugins

{
  "tool": "plugin_list",
  "args": {}
}

Register Custom Plugin

{
  "tool": "plugin_register",
  "args": {
    "pluginPath": "/path/to/my-plugin.js"
  }
}

🐛 Troubleshooting

Issue: "LLM API Key not configured"

Solution: Set the API key for your provider:

export GEMINI_API_KEY='your_key'
# or
export ANTHROPIC_API_KEY='your_key'
# or
export KIMI_API_KEY='your_key'

Issue: Agent stuck in "busy" status

Solution: Check and fail the task:

{
  "tool": "fail_task",
  "args": {
    "taskId": "task-uuid",
    "error": "Manual timeout - agent not responding"
  }
}

Or terminate the agent:

{
  "tool": "terminate_agent",
  "args": {
    "agentId": "agent-uuid"
  }
}

Issue: Parallel execution timeout

Solution: Increase timeout in task config:

{
  "tool": "assign_task",
  "args": {
    "agentId": "uuid",
    "type": "implementation",
    "description": "...",
    "timeout": 300
  }
}

Issue: Too many agents

Solution: Check limits and clean up:

{
  "tool": "system_config",
  "args": {
    "action": "get"
  }
}

Increase limit:

export SWARM_MAX_AGENTS=200

💡 Best Practices

1. Use Bootstrap for New Projects

Always start with system_bootstrap to get a properly structured team.

2. Mix LLM Providers

• Claude: Complex reasoning, architecture
• Kimi: Fast coding, implementation
• Gemini: Balanced tasks, testing
• OpenCode: Custom/local models

3. Use Sequential Thinking for Big Decisions

Document your reasoning process for future reference.

4. Parallelize Independent Tasks

Use parallel_execute when tasks don't depend on each other.

5. Always Handoff Context

Use context_handoff when transferring work between agents.

6. Monitor System Health

Regularly check system_health and system_stats.

7. Clean Up Regularly

Terminate idle agents to free up resources:

{
  "tool": "list_agents",
  "args": {"status": "idle"}
}

Then terminate unused agents.

🔧 Configuration

API Keys Setup

Choose your LLM provider and set the corresponding API key:

Google Gemini (Default)

export GEMINI_API_KEY='your_gemini_api_key'

Anthropic Claude

export ANTHROPIC_API_KEY='your_anthropic_api_key'
# Optional: export CLAUDE_API_KEY as fallback

Kimi (K2.5 Latest)

export KIMI_API_KEY='your_kimi_api_key'
# Optional: Custom endpoint
# export KIMI_BASE_URL='https://api.moonshot.cn/v1'

OpenCode

export OPENCODE_API_KEY='your_opencode_api_key'
# Optional: export OPENAI_API_KEY as fallback
# Optional: Custom endpoint
# export OPENCODE_BASE_URL='https://api.opencode.ai/v1'

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GEMINI_API_KEY | Gemini API Key | - | | GOOGLE_API_KEY | Gemini fallback | - | | ANTHROPIC_API_KEY | Claude API Key | - | | CLAUDE_API_KEY | Claude fallback | - | | KIMI_API_KEY | Kimi API Key | - | | KIMI_BASE_URL | Kimi endpoint | https://api.kimi.com/coding | | OPENCODE_API_KEY | OpenCode API Key | - | | OPENAI_API_KEY | OpenCode fallback | - | | OPENCODE_BASE_URL | OpenCode endpoint | https://api.opencode.ai/v1 | | SWARM_LLM_PROVIDER | Default provider | gemini | | SWARM_LLM_MODEL | Model name | Provider-specific | | SWARM_MAX_AGENTS | Max agents | 100 (PC) / 50 (Termux) | | SWARM_LOG_LEVEL | Log level | info |

🛠️ Available Tools

1. Agent Management

Tools for creating and managing AI agents in the swarm.

spawn_agent

Create a new agent with specified configuration.

Parameters:

{
  "type": "engineer",        // Required: product_manager | architect | engineer | qa | reviewer
  "name": "my_agent",        // Optional: custom name
  "mode": "edit",            // Optional: plan | edit | ralph
  "provider": "claude",      // Optional: gemini | claude | kimi | opencode
  "capabilities": ["coding"], // Optional: array of capabilities
  "metadata": {}             // Optional: custom metadata
}

Example:

{
  "type": "engineer",
  "name": "code_reviewer",
  "mode": "edit",
  "provider": "claude"
}

spawn_agents_batch

Create multiple agents at once.

Parameters:

{
  "type": "engineer",
  "count": 3,
  "baseName": "worker",
  "mode": "edit",
  "provider": "kimi"
}

get_agent

Get details of a specific agent.

Parameters:

{
  "agentId": "uuid-of-agent"
}

list_agents

List all agents, optionally filtered by type or status.

Parameters (optional):

{
  "type": "engineer",     // Filter by type
  "status": "idle"        // Filter by status: idle | busy | completed | error | terminated
}

terminate_agent

Terminate an agent and cleanup its tasks.

Parameters:

{
  "agentId": "uuid-of-agent"
}

send_agent_message

Send a message between agents.

Parameters:

{
  "fromAgentId": "sender-uuid",
  "toAgentId": "receiver-uuid",
  "messageType": "info",
  "content": "Hello from agent 1"
}

get_agent_messages

Get messages for an agent.

Parameters:

{
  "agentId": "uuid-of-agent",
  "limit": 50
}

2. Task Management

Tools for assigning and managing tasks.

assign_task

Assign a task to an agent.

Parameters:

{
  "agentId": "uuid-of-agent",
  "type": "implementation",
  "description": "Implement user authentication",
  "context": {"file": "auth.ts"},
  "priority": 8,
  "timeout": 120,
  "dependencies": ["task-uuid-1"]  // Optional: dependent task IDs
}

get_task

Get task details.

Parameters:

{
  "taskId": "uuid-of-task"
}

complete_task

Mark a task as completed.

Parameters:

{
  "taskId": "uuid-of-task",
  "result": "Task completed successfully"
}

fail_task

Mark a task as failed.

Parameters:

{
  "taskId": "uuid-of-task",
  "error": "Failed due to timeout"
}

cancel_task

Cancel a pending task.

Parameters:

{
  "taskId": "uuid-of-task"
}

list_tasks

List tasks, optionally filtered.

Parameters (optional):

{
  "agentId": "uuid-of-agent",  // Filter by agent
  "status": "pending"          // Filter by status
}

3. Sequential Thinking

Advanced reasoning system with thought chains, branching, and revision.

thinking_create_chain

Create a new thought chain for an agent.

Parameters:

{
  "agentId": "uuid-of-agent",
  "taskId": "uuid-of-task",
  "title": "Architecture Decision"
}

thinking_add_thought

Add a thought to a chain.

Parameters:

{
  "chainId": "uuid-of-chain",
  "content": "We should use microservices",
  "reasoning": "Scalability and maintainability",
  "confidence": 0.85,
  "branchFrom": "thought-uuid",    // Optional: create branch
  "revisionOf": "thought-uuid"     // Optional: revise existing thought
}

thinking_get_chain

Get a thought chain with all thoughts.

Parameters:

{
  "chainId": "uuid-of-chain"
}

thinking_export

Export thought chain to JSON or Markdown.

Parameters:

{
  "chainId": "uuid-of-chain",
  "format": "markdown"  // Optional: json | markdown (default: json)
}

4. Auto-Routing

AI-powered intent classification and agent routing.

routing_classify_intent

Classify the intent of user input.

Parameters:

{
  "input": "Create a login system with JWT authentication"
}

Returns:

{
  "intent": "implementation",
  "confidence": 0.92,
  "category": "modify",
  "complexity": "complex",
  "requiredCapabilities": ["coding", "security"]
}

routing_route

Find the best agent for a task.

Parameters:

{
  "input": "Review this code for security issues",
  "preferredAgent": "reviewer"  // Optional: suggest agent type
}

Returns:

{
  "targetAgent": "reviewer",
  "confidence": 0.95,
  "reasoning": "Input classified as review task",
  "alternativeAgents": [...],
  "suggestedMode": "plan",
  "estimatedComplexity": 7.5
}

5. Parallel Execution

Execute multiple tasks concurrently with real LLM calls.

parallel_execute

Execute tasks in parallel across multiple agents.

Parameters:

{
  "tasks": [
    {
      "agentType": "engineer",
      "type": "implementation",
      "description": "Create API endpoint",
      "priority": 8
    },
    {
      "agentType": "qa",
      "type": "testing",
      "description": "Write unit tests",
      "priority": 7
    }
  ],
  "maxConcurrency": 3,
  "aggregationStrategy": "all"  // Options: all | first | majority | custom
}

parallel_get_execution

Get execution status and results.

Parameters:

{
  "executionId": "uuid-of-execution"
}

6. Context Management

Manage context and handoffs between agents.

context_create

Create a context for an agent.

Parameters:

{
  "agentId": "uuid-of-agent",
  "maxTokens": 4000
}

context_handoff

Handoff context from one agent to another.

Parameters:

{
  "fromAgentId": "agent-1-uuid",
  "toAgentId": "agent-2-uuid",
  "taskId": "task-uuid",
  "notes": "Review the authentication logic"
}

context_get_handoff_history

Get handoff history for an agent.

Parameters:

{
  "agentId": "uuid-of-agent"
}

7. System Tools

System monitoring and management.

system_stats

Get comprehensive system statistics.

Returns:

{
  "agents": {
    "total": 10,
    "byType": {"engineer": 5, "qa": 3, ...},
    "byStatus": {"idle": 7, "busy": 3}
  },
  "tasks": {...},
  "database": {...},
  "parallel": {...},
  "plugins": {...}
}

system_health

Check system health status.

Returns:

{
  "status": "healthy",
  "healthCheck": {...},
  "config": {...},
  "timestamp": "2026-02-01T..."
}

system_config

Get or update system configuration.

Parameters:

{
  "action": "get"  // Options: get | update | reset
}

For update:

{
  "action": "update",
  "config": {
    "maxAgents": 50,
    "logLevel": "debug"
  }
}

system_metrics

Export metrics in JSON or Prometheus format.

Parameters:

{
  "format": "prometheus"  // Options: json | prometheus
}

8. Plugin Management

Extend functionality with plugins.

plugin_list

List all registered plugins.

Returns:

{
  "plugins": [...],
  "hooks": [...]
}

plugin_register

Register a new plugin.

Parameters:

{
  "pluginPath": "/path/to/plugin.js"
}

plugin_unregister

Unregister a plugin.

Parameters:

{
  "pluginId": "plugin-uuid"
}

9. Bootstrap

Automatic team setup.

system_bootstrap

Automatically analyze project and create agent team.

Parameters:

{
  "teamSize": "standard",  // Options: minimal | standard | full
  "provider": "claude",    // Optional: LLM provider
  "objective": "Build a web app",  // Optional: project description
  "confirm": true          // Required to confirm
}

First call (without confirm):

{
  "teamSize": "standard"
}

Returns available providers to choose from.

Second call (with confirm):

{
  "teamSize": "standard",
  "provider": "claude",
  "confirm": true
}

💡 Usage Examples

Example 1: Create a Development Team

// Step 1: Bootstrap the system
{
  "tool": "system_bootstrap",
  "args": {
    "teamSize": "standard",
    "provider": "claude",
    "confirm": true
  }
}

// Returns: Team of PM, Architect, and Engineer created

Example 2: Assign a Coding Task

// Create an agent
{
  "tool": "spawn_agent",
  "args": {
    "type": "engineer",
    "name": "backend_dev",
    "provider": "kimi"
  }
}

// Assign task
{
  "tool": "assign_task",
  "args": {
    "agentId": "uuid-from-spawn",
    "type": "implementation",
    "description": "Create REST API for user management",
    "priority": 9
  }
}

Example 3: Parallel Code Review

{
  "tool": "parallel_execute",
  "args": {
    "tasks": [
      {
        "agentType": "reviewer",
        "type": "review",
        "description": "Review auth.ts for security issues"
      },
      {
        "agentType": "reviewer",
        "type": "review",
        "description": "Review database.ts for SQL injection"
      },
      {
        "agentType": "qa",
        "type": "testing",
        "description": "Create test cases for auth module"
      }
    ],
    "maxConcurrency": 3,
    "aggregationStrategy": "all"
  }
}

Example 4: Sequential Thinking for Architecture

// Create thought chain
{
  "tool": "thinking_create_chain",
  "args": {
    "agentId": "architect-uuid",
    "taskId": "arch-task-uuid",
    "title": "Database Architecture Decision"
  }
}

// Add thoughts
{
  "tool": "thinking_add_thought",
  "args": {
    "chainId": "chain-uuid",
    "content": "Use PostgreSQL for relational data",
    "reasoning": "ACID compliance and complex queries",
    "confidence": 0.9
  }
}

// Export to markdown
{
  "tool": "thinking_export",
  "args": {
    "chainId": "chain-uuid",
    "format": "markdown"
  }
}

Example 5: Context Handoff

// Architect hands off to Engineer
{
  "tool": "context_handoff",
  "args": {
    "fromAgentId": "architect-uuid",
    "toAgentId": "engineer-uuid",
    "taskId": "implementation-task",
    "notes": "Follow the database schema in the design doc"
  }
}

🔥 Multi-LLM Provider Support (v1.7.0)

Supported Providers

| Provider | API Endpoint | Latest Models | |----------|-------------|---------------| | Gemini | generativelanguage.googleapis.com | gemini-3-flash-preview | | Claude | api.anthropic.com | claude-3-5-sonnet-20241022 | | Kimi | api.kimi.com/coding | kimi-k2.5, kimi-k2.5-coder | | OpenCode | api.opencode.ai | opencode-default |

Per-Agent Provider Selection

Each agent can use a different LLM provider:

// Agent 1 uses Claude
{
  "tool": "spawn_agent",
  "args": {
    "type": "architect",
    "provider": "claude"
  }
}

// Agent 2 uses Kimi
{
  "tool": "spawn_agent",
  "args": {
    "type": "engineer",
    "provider": "kimi"
  }
}

// Agent 3 uses Gemini
{
  "tool": "spawn_agent",
  "args": {
    "type": "qa",
    "provider": "gemini"
  }
}

📊 System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    SmartAgent (MCP Server)                  │
├─────────────────────────────────────────────────────────────┤
│  Agent Manager │ Task Scheduler │ Context Manager           │
├─────────────────────────────────────────────────────────────┤
│  Sequential Thinking │ Auto-Routing │ Parallel Execution    │
├─────────────────────────────────────────────────────────────┤
│  Gemini │ Claude │ Kimi │ OpenCode                         │
└─────────────────────────────────────────────────────────────┘

📝 Changelog

v1.7.0 (2026-02-01) - Multi-LLM Support

• ✅ Full Claude API Support - Real Anthropic API integration
• ✅ Full Kimi API Support - Kimi K2.5 with multiple endpoints
• ✅ Full OpenCode API Support - OpenAI-compatible API
• 🆕 New environment variables for all providers
• 🆕 Per-agent provider selection
• 📚 Complete API documentation

v1.6.0

• Initial release with Gemini support
• Sequential Thinking Engine
• Auto-Routing
• Parallel Execution

📄 License

MIT License - Enterprise AI Team

🤝 Support

For issues and feature requests, please visit the project repository.

Powered by: Model Context Protocol (MCP) | Multi-Agent Swarm Intelligence