Skip to main content

❓ Frequently Asked Questions (FAQ)

This document collects common questions and answers about using the Wegent platform.

📋 Table of Contents​

🔧 Installation & Deployment​

Q1: Which operating systems does Wegent support?​

A: Wegent supports all major operating systems:

  • Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+
  • macOS: macOS 11+
  • Windows: Windows 10/11 (via WSL2 or Docker Desktop)

Linux or macOS is recommended for production deployments.

Q2: What are the minimum hardware requirements?​

A: Minimum configuration:

  • CPU: 2 cores
  • Memory: 4 GB
  • Storage: 20 GB

Recommended (for production):

  • CPU: 4+ cores
  • Memory: 8+ GB
  • Storage: 50+ GB (SSD preferred)

Q3: Can I deploy on cloud platforms?​

A: Yes. Wegent supports deployment on various cloud platforms:

  • AWS: EC2, ECS, EKS
  • Google Cloud: Compute Engine, GKE
  • Azure: Virtual Machines, AKS
  • Alibaba Cloud: ECS, ACK
  • Tencent Cloud: CVM, TKE

Docker Compose works in any Docker-supported environment.

Q4: Do I need a domain and SSL certificate?​

A:

  • Development: No, use localhost
  • Production: Highly recommended
    • Use Let's Encrypt for free SSL
    • Use Nginx or Traefik as reverse proxy

Q5: Are there deployment options besides Docker?​

A: Yes. Besides Docker Compose:

  • Source deployment: Run Python and Node.js services directly
  • Binary deployment: Build backend as executable (requires additional configuration)

⚙️ Configuration & Usage​

Q6: How to configure multiple AI models?​

A: Configure different environment variables in Model resources:

# Claude model
apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: claude-sonnet
spec:
  modelConfig:
    env:
      ANTHROPIC_MODEL: "claude-sonnet-4"
      ANTHROPIC_API_KEY: "sk-xxx"

---
# GPT model
apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: gpt-4
spec:
  modelConfig:
    env:
      OPENAI_API_KEY: "sk-xxx"
      OPENAI_MODEL: "gpt-4"

Q7: What permissions does GitHub Token need?​

A: GitHub Personal Access Token requires:

  • ✅ repo - Full repository access
  • ✅ workflow - Workflow permissions
  • ✅ read:org - Read organization info (if using org repos)

Steps to create Token:

  1. GitHub Settings → Developer settings → Personal access tokens
  2. Select "Tokens (classic)"
  3. Generate new token
  4. Select above permissions
  5. Copy Token to Wegent configuration

Q8: How to configure proxy server?​

A: Configure proxy in environment variables:

# HTTP/HTTPS proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# Or in .env file
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

Q9: Does it support multiple users?​

A: Current version supports basic multi-user functionality:

  • Each user has independent workspace
  • Can configure different GitHub Tokens
  • Teams and Bots can be shared (based on namespace)

Future versions will support more comprehensive permission management.

Q10: How to backup data?​

A: Main backups needed:

1. MySQL Database:

# Backup
docker-compose exec mysql mysqldump -u task_user -p task_manager > backup.sql

# Restore
docker-compose exec -T mysql mysql -u task_user -p task_manager < backup.sql

2. Workspace Files:

# Backup workspace
tar -czf workspace_backup.tar.gz /path/to/workspace

# Restore
tar -xzf workspace_backup.tar.gz -C /path/to/restore

3. Configuration Files:

  • .env file
  • docker-compose.yml
  • Custom YAML configurations

💻 Development​

Q11: How to debug agent execution?​

A: Several debugging methods:

1. View Executor logs:

# Docker method
docker-compose logs -f executor

# View specific Executor
docker logs -f <executor-container-id>

2. Enable verbose logging:

# In .env
LOG_LEVEL=DEBUG

3. Enter Executor container:

docker exec -it <executor-container-id> /bin/bash

Q12: How to develop custom Agent?​

A: Steps to develop custom Agent:

  1. Create new Agent in executor/agents/
  2. Inherit from BaseAgent class
  3. Implement required methods:
    • initialize()
    • execute()
    • cleanup()
  4. Register Agent in agent_factory.py
  5. Create corresponding Shell configuration

Q13: Which programming languages are supported?​

A:

Core Platform:

  • Backend: Python 3.10+ (FastAPI)
  • Frontend: TypeScript (Next.js 15)
  • Executor: Python 3.10+

Agents can use:

  • Python (recommended)
  • JavaScript/TypeScript
  • Other languages (requires custom Agent implementation)

🤖 Agents & Teams​

Q14: What's the difference between Ghost, Bot, and Team?​

A:

  • Ghost: Agent's "soul" - defines personality and capabilities
  • Bot: Complete agent instance = Ghost + Shell + Model
  • Team: Collaboration of multiple Bots, defines workflow

Relationship: Ghost + Shell + Model → Bot → Team

See Core Concepts

Q15: How many Bots can a Team have?​

A: No theoretical limit, but recommended:

  • Dialogue mode: 3-5 Bots
  • Coding mode: 1-3 Bots
  • Complex workflows: 5-10 Bots

Too many Bots may cause:

  • Context confusion
  • Performance degradation
  • Increased costs

Q16: How to choose collaboration mode?​

A: Choose based on task type:

ModeUse CaseExample
PipelineSequential tasksDev→Review→Test→Deploy
RouteContent-based routingRoute to expert Bot
CoordinateParallel task aggregationMulti-angle analysis
CollaborateFree discussionBrainstorming, problem-solving

See Collaboration Models

Q17: Can Bots be reused?​

A: Yes. Bots can be reused across multiple Teams:

# Team 1
spec:
  members:
    - botRef:
        name: shared-developer-bot  # Reuse

# Team 2
spec:
  members:
    - botRef:
        name: shared-developer-bot  # Reuse

Each Team can configure different task prompts for the same Bot.

Q18: How to control agent costs?​

A: Several methods:

  1. Choose appropriate models:

    • Simple tasks: Haiku (cheap)
    • Complex tasks: Sonnet or Opus

  2. Optimize prompts:

    • Clear, specific instructions
    • Avoid redundancy

  3. Set limits:

    • Maximum tokens
    • Timeout
    • Maximum retries

  4. Monitor usage:

    • Check task logs
    • Track API calls

⚡ Performance & Optimization​

Q19: How to improve task execution speed?​

A: Several optimization methods:

  1. Increase concurrent executors:
# In .env
MAX_CONCURRENT_TASKS=10  # Default is 5

  1. Use faster models:

    • Haiku faster than Sonnet
    • Local models faster than API

  2. Optimize Docker:

    • Use SSD
    • Increase memory limits
    • Use image cache

  3. Optimize database:

    • Regular log cleanup
    • Add indexes
    • Use connection pooling

Q20: How many concurrent tasks are supported?​

A: Depends on hardware:

HardwareRecommended Concurrent
2core 4GB2-3
4core 8GB5-8
8core 16GB10-15
16core 32GB20-30

Adjust via MAX_CONCURRENT_TASKS environment variable.

🔍 Troubleshooting​

Q21: Task stuck in PENDING status?​

A: Possible causes and solutions:

  1. Executor Manager not running:
docker-compose ps executor_manager
docker-compose logs executor_manager
  1. No available Executors:
docker ps | grep executor

  1. Insufficient resources:

    • Check CPU and memory usage
    • Increase MAX_CONCURRENT_TASKS

  2. Configuration error:

    • Check Bot, Shell, Model configuration
    • View error logs

See Troubleshooting Guide

Q22: API returns 500 error?​

A:

  1. Check backend logs:
docker-compose logs backend
  1. Check database connection:
docker-compose exec backend python -c "from app.db import engine; engine.connect()"
  1. Check environment variables:
docker-compose exec backend env | grep DATABASE_URL

Q23: Frontend cannot connect to backend?​

A:

  1. Check API URL configuration:
# frontend/.env.local or environment variables
# Runtime variables (recommended, can be changed without rebuilding):
RUNTIME_INTERNAL_API_URL=http://localhost:8000
RUNTIME_SOCKET_DIRECT_URL=http://localhost:8000

# Legacy (deprecated):
# NEXT_PUBLIC_API_URL=http://localhost:8000

Note: The frontend now uses RUNTIME_INTERNAL_API_URL instead of NEXT_PUBLIC_API_URL. Runtime variables can be changed without rebuilding the application.

  1. Check CORS settings:

    • Ensure backend allows frontend domain

  2. Check firewall:

    • Ensure port 8000 is not blocked

  3. Check service status:

curl http://localhost:8000/api/health

📞 Get More Help​

If your question is not listed here:

  1. 📖 View Full Documentation
  2. 🔍 Search GitHub Issues
  3. 🐛 Check Troubleshooting Guide
  4. 💬 Create new Issue
  5. 🌟 Join community discussions

🔄 Continuous Updates​

This FAQ is continuously updated based on user feedback. If you have new questions or suggestions:

  • Submit Issue
  • Submit Pull Request
  • Participate in community discussions

Hope these answers help! 🎉