AgentZero Discord Bot 🤖

A powerful, modular Discord bot powered by Langchain Agents with multi-agent capabilities, FREE self-hosted web search, and long-term memory. Built with extensibility in mind - add new agents simply by creating a file!

🎉 NEW: Self-Hosted Web Search - NO API Keys Required!

Web search is now completely FREE and self-hosted! No more Google Custom Search API keys or billing. Uses Playwright to bypass anti-scraping mechanisms. See SELF_HOSTED_SEARCH.md for details.

✨ Features

• 🤖 Multi-Agent System: Automatic agent discovery and integration - just drop a file in agents/!
• 🔍 FREE Web Search: Self-hosted Google search with NO API keys - searches ANY topic
• 🧠 Long-Term Memory: ChromaDB-powered persistent conversation history
• 💬 Short-Term Memory: Context-aware conversations within sessions
• 🔌 Flexible LLM Support: Ollama, LMStudio, Anthropic, OpenAI, OpenRouter, Google Gemini
• 📦 Modular Architecture: Completely decoupled components for easy extension
• 🛡️ Robust Error Handling: Graceful fallbacks and user-friendly error messages
• 📊 Built-in Testing: Comprehensive test suite included
• 💰 Zero Cost Search: Unlimited web searches at no cost!

Architecture

Agentzero/
├── agents/              # Agent definitions (auto-discovered)
│   ├── chat_agent.py
│   └── websearch_agent.py
├── tools/               # Custom tools for agents
│   ├── chromadb_tool.py
│   └── google_mcp_wrapper.py
├── config.py            # LLM configuration and selection
├── crew_manager.py      # Dynamic crew creation and management
├── main.py              # Discord bot entry point
├── search_bridge.js     # Node.js bridge for self-hosted search
├── google-search/       # Self-hosted search tool (installed via setup)
└── requirements.txt     # Python dependencies

🚀 Quick Start

1. Prerequisites

• Python 3.10+
• Node.js 18+
• Discord Bot Token (Get one here)
• API key for your chosen LLM provider (Gemini, OpenAI, etc.)
• NO web search API keys needed! (Self-hosted and free)

2. Automated Setup

# Clone the repository
git clone <your-repo-url>
cd Agentzero

# Run the setup script (handles everything!)
python setup.py

The setup script will:

• ✅ Check Python and Node.js versions
• ✅ Create .env file from template
• ✅ Install all dependencies (Python + Node.js)
• ✅ Create necessary directories
• ✅ Test your configuration

3. Configuration

Edit .env with your credentials:

# Required
DISCORD_TOKEN=your_discord_bot_token_here
LLM_PROVIDER=GEMINI  # or OPENAI, ANTHROPIC, OLLAMA, etc.
GOOGLE_API_KEY=your_google_api_key_here

# Optional: Restrict bot to specific channel
# Leave empty to respond in all channels
DISCORD_CHANNEL_ID=1234567890123456789

# Web search is self-hosted - NO API KEYS NEEDED!

See SETUP_GUIDE.md for detailed configuration options.

Channel Restriction

To restrict the bot to a specific channel:

1. Enable Developer Mode in Discord (User Settings > Advanced > Developer Mode)
2. Right-click on the desired channel and select "Copy ID"
3. Paste the channel ID into DISCORD_CHANNEL_ID in your .env file
4. When channel restriction is enabled:
   • Bot will respond to ALL messages in that channel (no @mention needed)
   • Bot will still respond to DMs
5. When channel restriction is disabled (empty):
   • Bot will only respond when @mentioned or in DMs
6. Leave DISCORD_CHANNEL_ID empty to require @mentions in all channels

4. Run the Bot

python main.py

That's it! Your bot is now online. 🎉

💬 Usage

In Discord

Mention the bot or use the !crew command:

@YourBot what's the current temperature in Salt Lake City?
!crew explain quantum computing
!crew latest news about AI
@YourBot remember I prefer Python
!crew help
!crew status

See EXAMPLES.md for more usage examples.

Adding New Agents (It's Automatic! 🎯)

1. Create a new file in agents/ directory (e.g., agents/code_agent.py)
2. Define your agent with CrewAI's Agent class
3. That's it! The agent is automatically discovered and loaded on next run!

Example:

from crewai import Agent
from tools.your_tool import YourTool

code_agent = Agent(
    role='Code Analysis Expert',
    goal='Analyze code and provide insights',
    backstory='You are an expert code reviewer...',
    tools=[YourTool()],
    verbose=True
)

No need to modify any other files - the system automatically finds and loads your agent!

See CONTRIBUTING.md for detailed guide on adding agents and tools.

⚙️ Configuration Options

LLM Providers

Set LLM_PROVIDER in .env:

Provider	Description	API Key Required
GEMINI	Google Gemini models	✅ GOOGLE_API_KEY
OPENAI	GPT models	✅ OPENAI_API_KEY
ANTHROPIC	Claude models	✅ ANTHROPIC_API_KEY
OPENROUTER	Multiple models via OpenRouter	✅ OPENROUTER_API_KEY
OLLAMA	Local Ollama instance	✅ (local)
LMSTUDIO	Local LMStudio instance	✅ (local)

Memory System

• Short-term Memory:

  • Managed by Discord bot (last 10 messages per channel)
  • CrewAI's built-in memory during task execution

• Long-term Memory:

  • ChromaDB vector database
  • Persistent across sessions
  • Semantic search capabilities

🏗️ Architecture

Discord → Bot (main.py) → Crew Manager → CrewAI Framework
                              ↓
                    [Dynamic Agent Loading]
                              ↓
                    ┌─────────┴─────────┐
                    ↓                   ↓
              Chat Agent          Web Search Agent
                    ↓                   ↓
              ChromaDB            Google MCP Bridge
           (Long-term Memory)     (Web Search)

See ARCHITECTURE.md for detailed system design.

🧪 Development

Project Structure

Agentzero/
├── agents/              # Agent definitions (auto-discovered)
│   ├── chat_agent.py
│   ├── websearch_agent.py
│   └── agent_registry.py
├── tools/               # Custom tools for agents
│   ├── chromadb_tool.py
│   └── google_mcp_wrapper.py
├── utils/               # Utility modules
│   ├── logger.py
│   └── error_handler.py
├── tests/               # Test suite
├── config.py            # LLM configuration
├── crew_manager.py      # Crew orchestration
├── main.py              # Discord bot entry point
└── mcp_search_bridge.js # Node.js bridge for web search

Running Tests

# Run all tests
python run_tests.py

# Run specific test file
python -m unittest tests.test_tools

# Run with verbose output
python run_tests.py -v

🔧 Troubleshooting

Bot not responding

• ✅ Check DISCORD_TOKEN is valid
• ✅ Ensure bot has "Message Content Intent" enabled in Discord Developer Portal
• ✅ Verify bot has proper channel permissions (Read/Send Messages)

LLM errors

• ✅ Confirm API keys are set correctly in .env
• ✅ Check LLM_PROVIDER matches your configuration
• ✅ Verify model name is correct for your provider
• ✅ For local models (Ollama/LMStudio), ensure the service is running

Web search not working

• ✅ Run npm install to install Node.js dependencies
• ✅ Check GOOGLE_SEARCH_API_KEY and GOOGLE_SEARCH_ENGINE_ID are set
• ✅ Verify Custom Search API is enabled in Google Cloud Console
• ✅ Test the bridge: node mcp_search_bridge.js "test query"

See SETUP_GUIDE.md for detailed troubleshooting.

📚 Documentation

• SETUP_GUIDE.md: Detailed setup instructions
• ARCHITECTURE.md: System architecture and design
• EXAMPLES.md: Usage examples and best practices
• CONTRIBUTING.md: How to contribute

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (python run_tests.py)
5. Commit your changes (git commit -m 'Add: amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

• Built with CrewAI
• Powered by discord.py
• Uses ChromaDB for long-term memory
• Web search via Google Custom Search API

📧 Support

• 📖 Check the documentation files
• 🐛 Report bugs via Issues
• 💡 Request features via Issues
• 💬 Ask questions in Discussions

---

Made with ❤️ using CrewAI and Python