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

$3

``bash
npx @gotza02/smartagent
`

$3

`bash
npm install -g @gotza02/smartagent
smartagent
`

$3

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

---

🚀 Quick Start Guide

$3

`bash


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'
`

$3

`bash


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
`

$3

Once connected, create your first agent:

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

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

---

📖 Usage Guide

$3

Scenario: Build a web application with authentication

#### Step 1: Bootstrap Team
`json
{
"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
`json
{
"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
`json
{
"tool": "thinking_create_chain",
"args": {
"agentId": "architect-agent-uuid",
"taskId": "arch-task-uuid",
"title": "Auth System Architecture"
}
}
`

`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"tool": "assign_task",
"args": {
"agentId": "reviewer-agent-uuid",
"type": "review",
"description": "Review auth implementation for security best practices",
"context": {
"files": ["auth.ts", "middleware.ts"]
}
}
}
`

---

$3

#### Example: Mix Providers for Different Tasks

Claude for Architecture (complex reasoning):
`json
{
"tool": "spawn_agent",
"args": {
"type": "architect",
"name": "claude_architect",
"provider": "claude"
}
}
`

Kimi for Coding (fast implementation):
`json
{
"tool": "spawn_agent",
"args": {
"type": "engineer",
"name": "kimi_coder",
"provider": "kimi"
}
}
`

Gemini for QA (thorough testing):
`json
{
"tool": "spawn_agent",
"args": {
"type": "qa",
"name": "gemini_tester",
"provider": "gemini"
}
}
`

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

---

$3

Scenario: Design a microservices architecture

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

`json
// 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
}
}
`

`json
// 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"
}
}
`

`json
// 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"
}
}
`

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

---

$3

Let AI choose the best agent for your task:

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

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

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

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

Then spawn the recommended agent:
`json
{
"tool": "spawn_agent",
"args": {
"type": "reviewer",
"provider": "claude"
}
}
`

---

$3

Scenario: Analyze multiple files simultaneously

`json
{
"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"
}
}
`

---

$3

#### Check System Health
`json
{
"tool": "system_health",
"args": {}
}
`

#### View System Stats
`json
{
"tool": "system_stats",
"args": {}
}
`

#### List All Agents
`json
{
"tool": "list_agents",
"args": {}
}
`

#### List Busy Agents
`json
{
"tool": "list_agents",
"args": {
"status": "busy"
}
}
`

#### View Agent Messages
`json
{
"tool": "get_agent_messages",
"args": {
"agentId": "agent-uuid",
"limit": 20
}
}
`

#### Export Metrics
`json
{
"tool": "system_metrics",
"args": {
"format": "prometheus"
}
}
`

---

$3

#### List Available Plugins
`json
{
"tool": "plugin_list",
"args": {}
}
`

#### Register Custom Plugin
`json
{
"tool": "plugin_register",
"args": {
"pluginPath": "/path/to/my-plugin.js"
}
}
`

---

🐛 Troubleshooting

$3

Solution: Set the API key for your provider:
`bash
export GEMINI_API_KEY='your_key'


or

export ANTHROPIC_API_KEY='your_key'

or

export KIMI_API_KEY='your_key'
`

$3

Solution: Check and fail the task:
`json
{
"tool": "fail_task",
"args": {
"taskId": "task-uuid",
"error": "Manual timeout - agent not responding"
}
}
`

Or terminate the agent:
`json
{
"tool": "terminate_agent",
"args": {
"agentId": "agent-uuid"
}
}
`

$3

Solution: Increase timeout in task config:
`json
{
"tool": "assign_task",
"args": {
"agentId": "uuid",
"type": "implementation",
"description": "...",
"timeout": 300
}
}
`

$3

Solution: Check limits and clean up:
`json
{
"tool": "system_config",
"args": {
"action": "get"
}
}
`

Increase limit:
`bash
export SWARM_MAX_AGENTS=200
`

---

💡 Best Practices

$3


Always start with system_bootstrap to get a properly structured team.

$3

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

$3

Document your reasoning process for future reference.

$3

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

$3

Use context_handoff when transferring work between agents.

$3

Regularly check system_health and system_stats.

$3

Terminate idle agents to free up resources:
`json
{
"tool": "list_agents",
"args": {"status": "idle"}
}
`
Then terminate unused agents.

---

🔧 Configuration

$3

Choose your LLM provider and set the corresponding API key:

#### Google Gemini (Default)
`bash
export GEMINI_API_KEY='your_gemini_api_key'
`

#### Anthropic Claude
`bash
export ANTHROPIC_API_KEY='your_anthropic_api_key'


Optional: export CLAUDE_API_KEY as fallback


`

#### Kimi (K2.5 Latest)
`bash
export KIMI_API_KEY='your_kimi_api_key'


Optional: Custom endpoint

export KIMI_BASE_URL='https://api.moonshot.cn/v1'

`

#### OpenCode
`bash
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'

`

$3

| 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

$3

Tools for creating and managing AI agents in the swarm.

#### spawn_agent
Create a new agent with specified configuration.

Parameters:
`json
{
"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:
`json
{
"type": "engineer",
"name": "code_reviewer",
"mode": "edit",
"provider": "claude"
}
`

#### spawn_agents_batch
Create multiple agents at once.

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

#### get_agent
Get details of a specific agent.

Parameters:
`json
{
"agentId": "uuid-of-agent"
}
`

#### list_agents
List all agents, optionally filtered by type or status.

Parameters (optional):
`json
{
"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:
`json
{
"agentId": "uuid-of-agent"
}
`

#### send_agent_message
Send a message between agents.

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

#### get_agent_messages
Get messages for an agent.

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

---

$3

Tools for assigning and managing tasks.

#### assign_task
Assign a task to an agent.

Parameters:
`json
{
"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:
`json
{
"taskId": "uuid-of-task"
}
`

#### complete_task
Mark a task as completed.

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

#### fail_task
Mark a task as failed.

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

#### cancel_task
Cancel a pending task.

Parameters:
`json
{
"taskId": "uuid-of-task"
}
`

#### list_tasks
List tasks, optionally filtered.

Parameters (optional):
`json
{
"agentId": "uuid-of-agent", // Filter by agent
"status": "pending" // Filter by status
}
`

---

$3

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

#### thinking_create_chain
Create a new thought chain for an agent.

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

#### thinking_add_thought
Add a thought to a chain.

Parameters:
`json
{
"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:
`json
{
"chainId": "uuid-of-chain"
}
`

#### thinking_export
Export thought chain to JSON or Markdown.

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

---

$3

AI-powered intent classification and agent routing.

#### routing_classify_intent
Classify the intent of user input.

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

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

#### routing_route
Find the best agent for a task.

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

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

---

$3

Execute multiple tasks concurrently with real LLM calls.

#### parallel_execute
Execute tasks in parallel across multiple agents.

Parameters:
`json
{
"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:
`json
{
"executionId": "uuid-of-execution"
}
`

---

$3

Manage context and handoffs between agents.

#### context_create
Create a context for an agent.

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

#### context_handoff
Handoff context from one agent to another.

Parameters:
`json
{
"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:
`json
{
"agentId": "uuid-of-agent"
}
`

---

$3

System monitoring and management.

#### system_stats
Get comprehensive system statistics.

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

#### system_health
Check system health status.

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

#### system_config
Get or update system configuration.

Parameters:
`json
{
"action": "get" // Options: get | update | reset
}
`

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

#### system_metrics
Export metrics in JSON or Prometheus format.

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

---

$3

Extend functionality with plugins.

#### plugin_list
List all registered plugins.

Returns:
`json
{
"plugins": [...],
"hooks": [...]
}
`

#### plugin_register
Register a new plugin.

Parameters:
`json
{
"pluginPath": "/path/to/plugin.js"
}
`

#### plugin_unregister
Unregister a plugin.

Parameters:
`json
{
"pluginId": "plugin-uuid"
}
`

---

$3

Automatic team setup.

#### system_bootstrap
Automatically analyze project and create agent team.

Parameters:
`json
{
"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):
`json
{
"teamSize": "standard"
}
`
Returns available providers to choose from.

Second call (with confirm):
`json
{
"teamSize": "standard",
"provider": "claude",
"confirm": true
}
`

---

💡 Usage Examples

$3

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

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

$3

`json
// 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
}
}
`

$3

`json
{
"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"
}
}
`

$3

`json
// 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"
}
}
`

$3

`json
// 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)

$3

| 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 |

$3

Each agent can use a different LLM provider:

`json
// 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

$3

- ✅ 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

$3

- 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